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

(You MUST use form actions for mutations — NOT API routes for form submissions)

(You MUST use

fail()

@sveltejs/kit

(You MUST validate all input data on the server — client-side validation is NOT sufficient for security)

(You MUST use the auto-generated

$types

(You MUST use

use:enhance

(You MUST NOT catch

redirect()

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

Routing & Data:

• examples/core.md - File-based routing,

  +page.svelte

  ,

  +layout.svelte

  ,

  +error.svelte

  , dynamic routes
• examples/load-functions.md - Server load, universal load, streaming, parent data, invalidation

Mutations & Forms:

• examples/form-actions.md - Form actions,

  use:enhance

  , validation with

  fail()

  , redirects

Server:

• examples/hooks.md -

  handle

  ,

  handleFetch

  ,

  handleError

  ,

  init

  ,

  reroute

  ,

  transport

  ,

  sequence

  , auth patterns
• examples/api-routes.md -

  +server.ts

  API routes, streaming, content negotiation

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

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

Core Patterns

Pattern 1: File-Based Routing

SvelteKit uses filesystem-based routing where directories in

src/routes/

File Conventions

+page.svelte

+page.ts

+page.server.ts

+layout.svelte

+layout.ts

+layout.server.ts

+error.svelte

+server.ts

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

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

Promise.all

Pattern 3: Universal Load Functions

Universal load functions (

+page.ts

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

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

Pattern 4: Layout Load Functions

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

{@render children()}

Pattern 5: Form Actions

Form actions handle

POST

+page.server.ts

// 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()

form

use:enhance

action="?/login"

redirect

Pattern 6: Error Handling

SvelteKit uses

+error.svelte

error()

<!-- 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()

+error.svelte

page

$app/state

+error.svelte

Pattern 7: Streaming with Load Functions

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}

Pattern 8: Dynamic Routes

Use bracket notation for dynamic route segments.

Single Parameter

// 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 };
};

Rest Parameters

// 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 };
};

Optional Parameters

// src/routes/[[lang]]/about/+page.svelte
// Matches /about and /en/about, /fr/about, etc.

Pattern 9: Page Options

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;

prerender

true

false

'auto'

ssr

true

false

csr

true

false

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)

Integration Guide

SvelteKit is the full-stack framework. It builds on Svelte for routing, data loading, and server-side concerns.

Svelte component integration:

• All Svelte 5 patterns (Runes, snippets, events) work in SvelteKit pages and layouts
• Page components receive

  data

  prop from load functions via

  $props()

• Use

  PageProps

  ,

  LayoutProps

  from auto-generated

  $types

Data fetching integration:

• Server load functions fetch data before rendering (no waterfalls)
• Layout load data cascades to all child pages

• invalidate()

  and

  invalidateAll()

  for programmatic data refresh

Form handling integration:

• Form actions handle POST requests with progressive enhancement

• use:enhance

  adds client-side behavior (no page reload)

• fail()

  returns validation errors to the

  form

  prop

Auth integration:

• hooks.server.ts

  handle hook for session verification

• event.locals

  for passing auth data to load functions and actions
• Layout server load for protecting route groups

Deployment:

• adapter-auto

  — Auto-detects deployment platform

• adapter-node

  — Node.js server

• adapter-static

  — Static site generation

• adapter-vercel

  ,

  adapter-netlify

  ,

  adapter-cloudflare

  — Platform-specific

<red_flags>

RED FLAGS

High Priority Issues:

• Using API routes for form submissions -- Use form actions for mutations; API routes are for external clients
• Throwing errors for validation -- Use

  fail()

  to return errors without clearing form state
• Catching

  redirect()

  in try/catch --

  redirect()

  throws a special exception; don't catch it
• Missing auth checks in form actions -- Actions are public POST endpoints; always verify

  locals.user

• Using

  +page.ts

  for database access -- Universal loads run on the client; use

  +page.server.ts

Medium Priority Issues:

• Missing

  use:enhance

  on forms -- Forms reload the full page without it
• Not using

  $types

  for load function typing -- Lose automatic type inference
• Fetching data in components instead of load functions -- Creates client-side waterfalls
• Using

  goto()

  instead of

  <a>

  links -- Lose prefetching and progressive enhancement

Gotchas & Edge Cases:

• redirect()

  inside try/catch -- Redirect throws internally; wrap only the mutation in try/catch, not the redirect
• Using

  page

  from

  $app/stores

  instead of

  $app/state

  --

  $app/state

  is the Svelte 5 pattern (SvelteKit 2.12+)
• Not returning from

  fail()

  --

  fail()

  doesn't exit the function; you must

  return fail(...)

• Using default action with named actions -- A page with named actions cannot also have a default action
• Server load must return serializable data -- No classes, functions, or component instances (unless you define a

  transport

  hook)

• event.locals

  is request-scoped -- Safe for per-request data (auth), not for global state
• Remote functions (

  .remote.ts

  ) are experimental -- Enable via

  kit.experimental.remoteFunctions

  in config; API may change

See reference.md for the full red flags list and decision frameworks.

</red_flags>

<critical_reminders>

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

(You MUST use form actions for mutations — NOT API routes for form submissions)

(You MUST use

fail()

@sveltejs/kit

(You MUST validate all input data on the server — client-side validation is NOT sufficient for security)

(You MUST use the auto-generated

$types

(You MUST use

use:enhance

(You MUST NOT catch

redirect()

Failure to follow these rules will break data loading, create security vulnerabilities, lose progressive enhancement, or cause redirect failures.

</critical_reminders>