web-meta-framework-sveltekit

SvelteKit Patterns

Quick Guide: SvelteKit is the full-stack framework for Svelte. Use +page.server.ts load functions for server-side data, form actions for mutations with progressive enhancement, and +server.ts for API routes. Data flows from load functions to components via the data prop. Use use:enhance on forms for client-side progressive enhancement.

<critical_requirements>

CRITICAL: Before Using This Skill

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:

• Building SvelteKit applications with file-based routing
• Loading data for pages with server or universal load functions
• Handling form submissions with form actions and progressive enhancement
• Creating API endpoints with +server.ts routes
• Implementing server hooks for auth, logging, or request modification
• Configuring SSR, SSG, or prerendering strategies

Key patterns covered:

• File-based routing (+page.svelte, +layout.svelte, +error.svelte)
• Server load functions (+page.server.ts, +layout.server.ts)
• Universal load functions (+page.ts, +layout.ts)
• Form actions with validation and progressive enhancement
• Server hooks (handle, handleFetch, handleError, handleValidationError, init), universal hooks (reroute, transport)
• API routes (+server.ts) and streaming responses
• Page options (prerender, ssr, csr)
• Data invalidation and rerunning load functions

When NOT to use:

• Svelte 5 component patterns (Runes, snippets, events) — use web-framework-svelte
• Pure client-side Svelte without SvelteKit routing
• General React/Next.js patterns — use the appropriate framework skill

Detailed Resources:

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

Routing & Data:

• [examples/core.md](examples/core.md) - File-based routing, +page.svelte, +layout.svelte, +error.svelte, dynamic routes
• [examples/load-functions.md](examples/load-functions.md) - Server load, universal load, streaming, parent data, invalidation

Mutations & Forms:

• [examples/form-actions.md](examples/form-actions.md) - Form actions, use:enhance, validation with fail(), redirects

Server:

• [examples/hooks.md](examples/hooks.md) - handle, handleFetch, handleError, init, reroute, transport, sequence, auth patterns
• [examples/api-routes.md](examples/api-routes.md) - +server.ts API routes, streaming, content negotiation

<philosophy>

Philosophy

SvelteKit 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:

1. File-based routing — Directory structure defines URL structure. Special files (+page.svelte, +layout.svelte, etc.) define behavior.
2. Server-first data loading — Load functions run on the server for initial requests, providing data before rendering.
3. Progressive enhancement — Forms work without JavaScript. use:enhance adds client-side behavior on top.
4. Separation of concerns — Load functions fetch data, form actions handle mutations, hooks handle cross-cutting concerns.
5. Type safety — Auto-generated $types provide type-safe load functions, page props, and form data.
6. Web standards — Built on 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:

• Full-stack web applications with routing
• Server-rendered pages with SEO requirements
• Form-heavy applications with progressive enhancement
• API backends alongside page rendering
• Static site generation (SSG) with prerendering

When NOT to use:

• Client-only single-page apps without routing (use Svelte directly)
• Pure API servers (use a dedicated API framework)
• Micro-frontends embedded in other frameworks

</philosophy>

<patterns>

Core Patterns

Pattern 1: File-Based Routing

SvelteKit uses filesystem-based routing where directories in src/routes/ define URL paths and special files define behavior.

File Conventions

| 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 |

Route Structure

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

Pattern 2: Server Load Functions

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