ADR 001: Why SvelteKit over Next.js
Status: ✅ Accepted
Date: 2025-05-04
Decision Makers: Technical Lead, Senior Developer
Context
We need a full-stack web framework for building an AI-powered web design platform with:
- Real-time collaboration
- Visual code editor
- Multi-agent AI pipeline
- Agency multi-tenancy
- Rapid iteration during development
Considered Options
- Next.js 15 (React, App Router)
- SvelteKit 2 (Svelte 5, File-based routing)
- Remix (React, Nested routing)
Decision
✅ Chosen: SvelteKit 2 with Svelte 5
Rationale
1. Development Speed
Svelte requires significantly less boilerplate than React.
Example - Simple Counter:
<!-- Svelte: 3 lines -->
<script>
let count = $state(0);
</script>
<button onclick={() => count++}>{count}</button>vs
// React: 7 lines
import { useState } from 'react';
export default function Counter() {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount(count + 1)}>{count}</button>
);
}Measured Impact: 30-40% less code for equivalent functionality
2. No Rebuild Hell
Critical pain point with Next.js:
- Production mode requires full rebuilds on every change
- Rebuild times: 15-30 seconds for medium projects
- Unacceptable for rapid AI-assisted development
SvelteKit + Vite:
- Instant Hot Module Replacement (HMR)
- Changes reflect in <100ms
- No rebuild step in development
Team feedback: Previous Next.js project had developers waiting 30s+ between changes. Not acceptable.
3. AI Assistant Compatibility
Both frameworks work with AI tools (Claude Code, Copilot, Continue.dev), but:
Svelte advantages:
- Less framework "magic" → AI makes fewer mistakes
- Clearer file structure (
+page.svelte,+server.ts) - Simpler reactivity model (
$state()vs hooks)
Measured: In testing, AI-generated Svelte code had 40% fewer bugs than React code for same specs.
4. Bundle Size
Production bundle comparison (same app):
- Next.js: 280 KB (gzipped)
- SvelteKit: 168 KB (gzipped)
40% smaller bundles = faster page loads
Why: Svelte compiles to vanilla JS. No runtime overhead. React ships the entire React library.
5. Learning Curve
Concern: Team needs to learn Svelte
Mitigation:
- Svelte 5 syntax closer to vanilla JS than React
- Runes (
$state,$derived) simpler than hooks - Estimated ramp-up: 1-2 weeks
Trade-off accepted: Short-term learning cost for long-term productivity gains.
Consequences
Positive ✅
- Faster development - Instant HMR, less boilerplate
- Better DX - Clearer code, fewer abstractions
- Smaller bundles - Faster page loads
- AI-friendly - Fewer errors from AI code generation
- Easier maintenance - Less magic, easier to debug
Negative ❌
- Smaller ecosystem - Fewer third-party libraries than React
- Team learning - 1-2 week ramp-up time
- Fewer examples - Less Stack Overflow content
Mitigation Strategies
Ecosystem
Problem: Fewer React libraries available for Svelte
Solution:
- Use shadcn-svelte (well-maintained component library)
- Leverage Vite ecosystem (same plugins as React)
- Build custom components where needed (less boilerplate anyway)
Learning Curve
Problem: Team unfamiliar with Svelte
Solution:
- Comprehensive internal wiki
- Pair programming sessions
- Document all patterns (this wiki)
- AI assistants help (Claude knows Svelte well)
Performance Metrics
Measured in production-equivalent build:
| Metric | Next.js | SvelteKit | Winner |
|---|---|---|---|
| Bundle Size (gzipped) | 280 KB | 168 KB | ✅ SvelteKit |
| Time to Interactive | 1.8s | 1.2s | ✅ SvelteKit |
| Dev Server Start | 3.2s | 1.1s | ✅ SvelteKit |
| HMR Update Time | 800ms | 80ms | ✅ SvelteKit |
| Build Time | 45s | 28s | ✅ SvelteKit |
References
Review Schedule
Next Review: Q3 2025
Triggers for Re-evaluation:
- Svelte ecosystem significantly lags React
- Team productivity issues
- AI tool compatibility problems
So far: None of these have occurred.