SvelteKit full-stack framework - file-based routing, load functions, form actions, server hooks, SSR/SSG, API routes, streaming, progressive enhancement
Quick Guide: SvelteKit is the full-stack framework for Svelte. Use
+page.server.tsload functions for server-side data, form actions for mutations with progressive enhancement, and+server.tsfor API routes. Data flows from load functions to components via thedataprop. Useuse:enhanceon forms for client-side progressive enhancement.
<critical_requirements>
All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type, named constants)
(You MUST use server load functions (+page.server.ts) for data requiring database access, secrets, or cookies)
(You MUST use form actions for mutations — NOT API routes for form submissions)
(You MUST use fail() from @sveltejs/kit for validation errors — NEVER throw errors for validation)
(You MUST validate all input data on the server — client-side validation is NOT sufficient for security)
(You MUST use the auto-generated $types for type-safe load functions and page props)
(You MUST use use:enhance on forms for progressive enhancement — forms should work without JavaScript)
(You MUST NOT catch redirect() in try/catch — it throws a special exception SvelteKit handles)
</critical_requirements>
Auto-detection: SvelteKit, +page.svelte, +page.ts, +page.server.ts, +layout.svelte, +layout.ts, +layout.server.ts, +error.svelte, +server.ts, load function, form actions, use:enhance, hooks.server.ts, hooks.client.ts, hooks.ts, handle hook, handleFetch, handleError, handleValidationError, init hook, reroute, transport hook, $app/navigation, $app/forms, $app/state, PageLoad, PageServerLoad, LayoutLoad, LayoutServerLoad, RequestHandler, fail, redirect, error, .remote.ts
When to use:
+server.ts routesKey patterns covered:
+page.svelte, +layout.svelte, +error.svelte)+page.server.ts, +layout.server.ts)+page.ts, +layout.ts)handle, handleFetch, handleError, handleValidationError, init), universal hooks (reroute, transport)+server.ts) and streaming responsesprerender, ssr, csr)When NOT to use:
Detailed Resources:
Routing & Data:
+page.svelte, +layout.svelte, +error.svelte, dynamic routesMutations & Forms:
use:enhance, validation with fail(), redirectsServer:
handle, handleFetch, handleError, init, reroute, transport, sequence, auth patterns+server.ts API routes, streaming, content negotiationSvelteKit is a full-stack framework built on Svelte that handles routing, server-side rendering, data loading, and form handling. It embraces web platform standards — using native Request/Response, FormData, and progressive enhancement.
Core principles:
+page.svelte, +layout.svelte, etc.) define behavior.use:enhance adds client-side behavior on top.$types provide type-safe load functions, page props, and form data.Request, Response, URL, Headers, FormData — standard web APIs.Data flow in SvelteKit:
Request → hooks.server.ts (handle) → +layout.server.ts (load) → +page.server.ts (load) → +page.svelte (render)
← form actions (POST)
When to use SvelteKit:
When NOT to use:
SvelteKit uses filesystem-based routing where directories in src/routes/ define URL paths and special files define behavior.
| File | Purpose | Runs On |
|---|---|---|
+page.svelte | Page component (UI) | Server (SSR) + Client |
+page.ts | Universal load function | Server + Client |
+page.server.ts | Server load function + form actions | Server only |
+layout.svelte | Shared layout wrapper | Server (SSR) + Client |
+layout.ts | Universal layout load | Server + Client |
+layout.server.ts | Server layout load | Server only |
+error.svelte | Error boundary | Server (SSR) + Client |
+server.ts | API route (GET, POST, etc.) | Server only |
src/routes/
├── +layout.svelte # Root layout
├── +page.svelte # Home page (/)
├── +error.svelte # Root error boundary
├── about/
│ └── +page.svelte # /about
├── blog/
│ ├── +page.svelte # /blog (list)
│ ├── +page.server.ts # Load blog posts
│ └── [slug]/
│ ├── +page.svelte # /blog/:slug (detail)
│ └── +page.server.ts # Load single post
├── dashboard/
│ ├── +layout.svelte # Dashboard layout (sidebar)
│ ├── +layout.server.ts # Auth check for all dashboard pages
│ ├── +page.svelte # /dashboard
│ └── settings/
│ └── +page.svelte # /dashboard/settings
├── (marketing)/ # Route group (no URL segment)
│ ├── +layout.svelte # Marketing-specific layout
│ ├── pricing/
│ │ └── +page.svelte # /pricing
│ └── features/
│ └── +page.svelte # /features
└── api/
└── health/
└── +server.ts # GET /api/health
Why this works: File conventions eliminate routing configuration, layouts nest automatically, route groups organize without affecting URLs
Server load functions (+page.server.ts) run only on the server. Use for database access, secrets, and cookie-based auth.
// src/routes/blog/+page.server.ts
import { error } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";
const POSTS_PER_PAGE = 10;
export const load: PageServerLoad = async ({ url, locals }) => {
// Access query params
const page = Number(url.searchParams.get("page") ?? "1");
// Access server-only data (locals set in hooks)
if (!locals.user) {
error(401, "Not authenticated");
}
// Fetch from database (server-only)
const offset = (page - 1) * POSTS_PER_PAGE;
const [posts, total] = await Promise.all([
db.post.findMany({
take: POSTS_PER_PAGE,
skip: offset,
orderBy: { createdAt: "desc" },
}),
db.post.count(),
]);
return {
posts,
pagination: {
page,
totalPages: Math.ceil(total / POSTS_PER_PAGE),
},
};
};
<!-- src/routes/blog/+page.svelte -->
<script lang="ts">
import type { PageProps } from './$types';
let { data }: PageProps = $props();
</script>
<h1>Blog</h1>
{#each data.posts as post}
<article>
<h2><a href="/blog/{post.slug}">{post.title}</a></h2>
<p>{post.excerpt}</p>
</article>
{/each}
<nav>
{#if data.pagination.page > 1}
<a href="?page={data.pagination.page - 1}">Previous</a>
{/if}
{#if data.pagination.page < data.pagination.totalPages}
<a href="?page={data.pagination.page + 1}">Next</a>
{/if}
</nav>
Why good: Server-only code (database access), type-safe with auto-generated $types, named constant for pagination, parallel data fetching with Promise.all
Universal load functions (+page.ts) run on both server and client. Use for external APIs that don't need secrets.
// src/routes/weather/+page.ts
import { error } from "@sveltejs/kit";
import type { PageLoad } from "./$types";
export const load: PageLoad = async ({ fetch, params }) => {
// SvelteKit's fetch: works on server and client, inherits cookies
const response = await fetch(`https://api.weather.com/forecast?city=london`);
if (!response.ok) {
error(response.status, "Failed to load weather data");
}
const forecast = await response.json();
return { forecast };
};
Why good: fetch from SvelteKit works on both server (SSR) and client (navigation), auto-deduplicates on the client, inherits cookies for authenticated APIs
When to use: External public APIs, data that doesn't require server secrets
When not to use: Database access, private environment variables, cookie manipulation — use +page.server.ts
Layout load functions provide data to all child pages in the route segment.
// src/routes/dashboard/+layout.server.ts
import { redirect } from "@sveltejs/kit";
import type { LayoutServerLoad } from "./$types";
export const load: LayoutServerLoad = async ({ cookies, locals }) => {
// Auth check for all dashboard routes
if (!locals.user) {
redirect(303, "/login");
}
// Data available to all dashboard pages
const notifications = await db.notification.findMany({
where: { userId: locals.user.id, read: false },
});
return {
user: locals.user,
notifications,
};
};
<!-- src/routes/dashboard/+layout.svelte -->
<script lang="ts">
import type { LayoutProps } from './$types';
let { data, children }: LayoutProps = $props();
</script>
<div class="dashboard">
<aside class="sidebar">
<nav>
<a href="/dashboard">Overview</a>
<a href="/dashboard/settings">Settings</a>
</nav>
<p>Welcome, {data.user.name}</p>
<span class="badge">{data.notifications.length} unread</span>
</aside>
<main>
{@render children()}
</main>
</div>
Why good: Auth check runs for all dashboard child pages, layout data cascades to children, redirect throws for unauthenticated users, Svelte 5 {@render children()} for layout slot
Form actions handle POST requests in +page.server.ts. They enable progressive enhancement — forms work without JavaScript.
// src/routes/login/+page.server.ts
import { fail, redirect } from "@sveltejs/kit";
import type { Actions, PageServerLoad } from "./$types";
const MIN_PASSWORD_LENGTH = 8;
export const load: PageServerLoad = async ({ locals }) => {
if (locals.user) {
redirect(303, "/dashboard");
}
};
export const actions: Actions = {
login: async ({ request, cookies }) => {
const data = await request.formData();
const email = data.get("email")?.toString() ?? "";
const password = data.get("password")?.toString() ?? "";
// Validation
if (!email) {
return fail(400, { email, missing: true, message: "Email is required" });
}
if (password.length < MIN_PASSWORD_LENGTH) {
return fail(400, {
email,
invalid: true,
message: `Password must be at least ${MIN_PASSWORD_LENGTH} characters`,
});
}
// Authentication (defer to your auth solution)
const user = await authenticateUser(email, password);
if (!user) {
return fail(400, {
email,
invalid: true,
message: "Invalid credentials",
});
}
// Set session cookie
cookies.set("session", user.sessionId, {
path: "/",
httpOnly: true,
sameSite: "lax",
secure: true,
maxAge: 60 * 60 * 24 * 30, // 30 days
});
redirect(303, "/dashboard");
},
register: async ({ request }) => {
// Named action for registration
const data = await request.formData();
// ... registration logic
},
};
<!-- src/routes/login/+page.svelte -->
<script lang="ts">
import { enhance } from '$app/forms';
import type { PageProps } from './$types';
let { form }: PageProps = $props();
</script>
<h1>Login</h1>
{#if form?.message}
<p class="error" role="alert">{form.message}</p>
{/if}
<form method="POST" action="?/login" use:enhance>
<label>
Email
<input
type="email"
name="email"
value={form?.email ?? ''}
required
/>
</label>
<label>
Password
<input
type="password"
name="password"
required
/>
</label>
<button type="submit">Log in</button>
<button type="submit" formaction="?/register">Register</button>
</form>
Why good: fail() returns validation errors without clearing form data, form prop shows returned data, use:enhance for client-side enhancement, action="?/login" targets named action, redirect after successful auth, named constant for password length
SvelteKit uses +error.svelte components as error boundaries and the error() helper for controlled errors.
<!-- src/routes/+error.svelte -->
<script lang="ts">
import { page } from '$app/state';
</script>
<div class="error-page">
<h1>{page.status}</h1>
{#if page.status === 404}
<p>Page not found</p>
<a href="/">Go home</a>
{:else if page.status === 401}
<p>You need to log in to access this page.</p>
<a href="/login">Log in</a>
{:else}
<p>{page.error?.message ?? 'Something went wrong'}</p>
{/if}
</div>
// In a load function
import { error } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ params }) => {
const post = await db.post.findUnique({
where: { slug: params.slug },
});
if (!post) {
error(404, "Post not found");
}
return { post };
};
Why good: error() throws a controlled error that renders +error.svelte, page from $app/state provides status and error info (Svelte 5 pattern), error boundary walks up the tree to find nearest +error.svelte
Return unawaited promises from load functions to stream data — fast data renders immediately, slow data streams in.
// src/routes/dashboard/+page.server.ts
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ locals }) => {
// Fast query - awaited (blocks render until ready)
const user = await db.user.findUnique({
where: { id: locals.user.id },
});
// Slow queries - NOT awaited (streamed after initial render)
const analyticsPromise = fetchAnalytics(locals.user.id);
const recommendationsPromise = fetchRecommendations(locals.user.id);
return {
user,
analytics: analyticsPromise, // Streams when ready
recommendations: recommendationsPromise, // Streams when ready
};
};
<!-- src/routes/dashboard/+page.svelte -->
<script lang="ts">
import type { PageProps } from './$types';
let { data }: PageProps = $props();
</script>
<h1>Welcome, {data.user.name}</h1>
{#await data.analytics}
<div class="skeleton">Loading analytics...</div>
{:then analytics}
<div class="analytics">
<p>Views: {analytics.views}</p>
<p>Revenue: ${analytics.revenue}</p>
</div>
{:catch error}
<p class="error">Failed to load analytics: {error.message}</p>
{/await}
{#await data.recommendations}
<div class="skeleton">Loading recommendations...</div>
{:then recommendations}
<ul>
{#each recommendations as rec}
<li>{rec.title}</li>
{/each}
</ul>
{:catch error}
<p class="error">Failed to load recommendations</p>
{/await}
Why good: User sees fast data immediately, slow data streams in progressively, each section handles loading and error states independently, {#await} blocks handle all three states
Use bracket notation for dynamic route segments.
// src/routes/blog/[slug]/+page.server.ts
import { error } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ params }) => {
const post = await db.post.findUnique({
where: { slug: params.slug },
});
if (!post) {
error(404, "Post not found");
}
return { post };
};
// src/routes/docs/[...path]/+page.server.ts
// Matches /docs/a, /docs/a/b, /docs/a/b/c
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ params }) => {
// params.path is "a/b/c" for /docs/a/b/c
const segments = params.path.split("/");
const doc = await loadDocument(segments);
return { doc, breadcrumbs: segments };
};
// src/routes/[[lang]]/about/+page.svelte
// Matches /about and /en/about, /fr/about, etc.
Control rendering behavior per-page or per-layout.
// src/routes/blog/+page.ts
// Prerender blog listing at build time
export const prerender = true;
// src/routes/dashboard/+page.ts
// Disable SSR for client-only dashboard
export const ssr = false;
// src/routes/marketing/+layout.ts
// Prerender all marketing pages
export const prerender = true;
// src/routes/api/realtime/+server.ts
// Force dynamic rendering (no caching)
export const prerender = false;
| Option | Values | Effect |
|---|---|---|
prerender | true, false, 'auto' | Generate static HTML at build time |
ssr | true, false | Enable/disable server-side rendering |
csr | true, false | Enable/disable client-side rendering (hydration) |
When to use:
prerender = true — Static content (blog posts, marketing pages)ssr = false — Client-only pages with browser APIs (dashboards with charts)csr = false — Zero JavaScript pages (legal text, documentation)SvelteKit is the full-stack framework. It builds on Svelte for routing, data loading, and server-side concerns.
Svelte component integration:
data prop from load functions via $props()PageProps, LayoutProps from auto-generated $typesData fetching integration:
invalidate() and invalidateAll() for programmatic data refreshForm handling integration:
use:enhance adds client-side behavior (no page reload)fail() returns validation errors to the form propAuth integration:
hooks.server.ts handle hook for session verificationevent.locals for passing auth data to load functions and actionsDeployment:
adapter-auto — Auto-detects deployment platformadapter-node — Node.js serveradapter-static — Static site generationadapter-vercel, adapter-netlify, adapter-cloudflare — Platform-specific<red_flags>
High Priority Issues:
fail() to return errors without clearing form stateredirect() in try/catch -- redirect() throws a special exception; don't catch itlocals.user+page.ts for database access -- Universal loads run on the client; use +page.server.tsMedium Priority Issues:
use:enhance on forms -- Forms reload the full page without it$types for load function typing -- Lose automatic type inferencegoto() instead of <a> links -- Lose prefetching and progressive enhancementGotchas & Edge Cases:
redirect() inside try/catch -- Redirect throws internally; wrap only the mutation in try/catch, not the redirectpage from $app/stores instead of $app/state -- $app/state is the Svelte 5 pattern (SvelteKit 2.12+)fail() -- fail() doesn't exit the function; you must return fail(...)transport hook)event.locals is request-scoped -- Safe for per-request data (auth), not for global state.remote.ts) are experimental -- Enable via kit.experimental.remoteFunctions in config; API may changeSee reference.md for the full red flags list and decision frameworks.
</red_flags>
<critical_reminders>
All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type, named constants)
(You MUST use server load functions (+page.server.ts) for data requiring database access, secrets, or cookies)
(You MUST use form actions for mutations — NOT API routes for form submissions)
(You MUST use fail() from @sveltejs/kit for validation errors — NEVER throw errors for validation)
(You MUST validate all input data on the server — client-side validation is NOT sufficient for security)
(You MUST use the auto-generated $types for type-safe load functions and page props)
(You MUST use use:enhance on forms for progressive enhancement — forms should work without JavaScript)
(You MUST NOT catch redirect() in try/catch — it throws a special exception SvelteKit handles)
Failure to follow these rules will break data loading, create security vulnerabilities, lose progressive enhancement, or cause redirect failures.
</critical_reminders>