sveltekit

name	sveltekit
description	ALWAYS use this when the request matches Sveltekit: Build full-stack web applications with SvelteKit — file-based routing, SSR, SSG, API routes, and form actions in one framework.

SvelteKit Full-Stack Development

Selective Reading Rule

Start with:

• references/senior-master-standard.md
• references/usage-routing.md
• references/quality-checklist.md

Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.

Overview

SvelteKit is the official full-stack framework built on top of Svelte. It provides file-based routing, server-side rendering (SSR), static site generation (SSG), API routes, and progressive form actions — all with Svelte's compile-time reactivity model that ships zero runtime overhead to the browser. Use this skill when building fast, modern web apps where both DX and performance matter.

When to Use This Skill

• Use when building a new full-stack web application with Svelte
• Use when you need SSR or SSG with fine-grained control per route
• Use when migrating a SPA to a framework with server capabilities
• Use when working on a project that needs file-based routing and collocated API endpoints
• Use when the user asks about +page.svelte, +layout.svelte, load functions, or form actions

How It Works

Step 1: Project Setup

npm create svelte@latest my-app
cd my-app
npm install
npm run dev

Choose Skeleton project + TypeScript + ESLint/Prettier when prompted.

Directory structure after scaffolding:

src/
  routes/
    +page.svelte        ← Root page component
    +layout.svelte      ← Root layout (wraps all pages)
    +error.svelte       ← Error boundary
  lib/
    server/             ← Server-only code (never bundled to client)
    components/         ← Shared components
  app.html              ← HTML shell
static/                 ← Static assets

Step 2: File-Based Routing

Every +page.svelte file in src/routes/ maps directly to a URL:

src/routes/+page.svelte          → /
src/routes/about/+page.svelte    → /about
src/routes/blog/[slug]/+page.svelte  → /blog/:slug
src/routes/shop/[...path]/+page.svelte → /shop/* (catch-all)

Route groups (no URL segment): wrap in (group)/ folder. Private routes (not accessible as URLs): prefix with _ or (group).

Step 3: Loading Data with load Functions

Use a +page.ts (universal) or +page.server.ts (server-only) file alongside the page:

// src/routes/blog/[slug]/+page.server.ts
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ params, fetch }) => {
  const post = await fetch(`/api/posts/${params.slug}`).then(r => r.json());

  if (!post) {
    error(404, 'Post not found');
  }

  return { post };
};

<!-- src/routes/blog/[slug]/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  export let data: PageData;
</script>

<h1>{data.post.title}</h1>
<article>{@html data.post.content}</article>

Step 4: API Routes (Server Endpoints)

Create +server.ts files for REST-style endpoints:

// src/routes/api/posts/+server.ts
import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = async ({ url }) => {
  const limit = Number(url.searchParams.get('limit') ?? 10);
  const posts = await db.post.findMany({ take: limit });
  return json(posts);
};

export const POST: RequestHandler = async ({ request }) => {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return json(post, { status: 201 });
};

Step 5: Form Actions

Form actions are the SvelteKit-native way to handle mutations — no client-side fetch required:

// src/routes/contact/+page.server.ts
import { fail, redirect } from '@sveltejs/kit';
import type { Actions } from './$types';

export const actions: Actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    const email = data.get('email');

    if (!email) {
      return fail(400, { email, missing: true });
    }

    await sendEmail(String(email));
    redirect(303, '/thank-you');
  }
};

<!-- src/routes/contact/+page.svelte -->
<script lang="ts">
  import { enhance } from '$app/forms';
  import type { ActionData } from './$types';
  export let form: ActionData;
</script>

<form method="POST" use:enhance>
  <input name="email" type="email" />
  {#if form?.missing}<p class="error">Email is required</p>{/if}
  <button type="submit">Subscribe</button>
</form>

Step 6: Layouts and Nested Routes

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import type { LayoutData } from './$types';
  export let data: LayoutData;
</script>

<nav>
  <a href="/">Home</a>
  <a href="/blog">Blog</a>
  {#if data.user}
    <a href="/dashboard">Dashboard</a>
  {/if}
</nav>

<slot />  <!-- child page renders here -->

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
  return { user: locals.user ?? null };
};

Step 7: Rendering Modes

Control per-route rendering with page options:

// src/routes/docs/+page.ts
export const prerender = true;   // Static — generated at build time
export const ssr = true;         // Default — rendered on server per request
export const csr = false;        // Disable client-side hydration entirely

Examples

Example 1: Protected Dashboard Route

// src/routes/dashboard/+layout.server.ts
import { redirect } from '@sveltejs/kit';
import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
  if (!locals.user) {
    redirect(303, '/login');
  }
  return { user: locals.user };
};

Example 2: Hooks — Session Middleware

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import { verifyToken } from '$lib/server/auth';

export const handle: Handle = async ({ event, resolve }) => {
  const token = event.cookies.get('session');
  if (token) {
    event.locals.user = await verifyToken(token);
  }
  return resolve(event);
};

Example 3: Preloading and Invalidation

<script lang="ts">
  import { invalidateAll } from '$app/navigation';

  async function refresh() {
    await invalidateAll(); // re-runs all load functions on the page
  }
</script>

<button on:click={refresh}>Refresh</button>

Best Practices

• ✅ Use +page.server.ts for database/auth logic — it never ships to the client
• ✅ Use $lib/server/ for shared server-only modules (DB client, auth helpers)
• ✅ Use form actions for mutations instead of client-side fetch — works without JS
• ✅ Type all load return values with generated $types (PageData, LayoutData)
• ✅ Use event.locals in hooks to pass server-side context to load functions
• ❌ Don't import server-only code in +page.svelte or +layout.svelte directly
• ❌ Don't store sensitive state in stores — use locals on the server
• ❌ Don't skip use:enhance on forms — without it, forms lose progressive enhancement

Security & Safety Notes

• All code in +page.server.ts, +server.ts, and $lib/server/ runs exclusively on the server — safe for DB queries, secrets, and session validation.
• Always validate and sanitize form data before database writes.
• Use error(403) or redirect(303) from @sveltejs/kit rather than returning raw error objects.
• Set httpOnly: true and secure: true on all auth cookies.
• CSRF protection is built-in for form actions — do not disable checkOrigin in production.

Common Pitfalls

• Problem: Cannot use import statement in a module in +page.server.ts Solution: The file must be .ts or .js, not .svelte. Server files and Svelte components are separate.

• Problem: Store value is undefined on first SSR render Solution: Populate the store from the load function return value (data prop), not from client-side onMount.

• Problem: Form action does not redirect after submit Solution: Use redirect(303, '/path') from @sveltejs/kit, not a plain return. 303 is required for POST redirects.

• Problem: locals.user is undefined inside a +page.server.ts load function Solution: Set event.locals.user in src/hooks.server.ts before the resolve() call.

Related Skills

• @nextjs-app-router-patterns — When you prefer React over Svelte for SSR/SSG
• @trpc-fullstack — Add end-to-end type safety to SvelteKit API routes
• @auth-implementation-patterns — Authentication patterns usable with SvelteKit hooks
• @tailwind-patterns — Styling SvelteKit apps with Tailwind CSS

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.