Svelte 5 / SvelteKit — Best Practices

Cross-cutting guidance: how to choose the right primitives, keep apps fast and accessible, and write code that doesn't break in production.

State Management Strategy

Pick the smallest scope that works:

Component-local — let x = $state(0) inside a .svelte file. Default for anything not shared.
Per-feature module — .svelte.ts exporting an object with mutable fields (export const counter = $state({ value: 0 })). Default for cross-component state in a feature.
Context — setContext / getContext for tree-scoped state where multiple components need a per-instance shared object (e.g., a form, a dropdown). Pair context with a reactive $state object so the value can update.
URL — for state that should survive reloads, deep-link, or affect SSR (filters, pagination, tabs). Read via page.url.searchParams, write via goto('?x=1', { replaceState: true, keepFocus: true, noScroll: true }).
Cookies / DB — for state that crosses sessions or needs server enforcement. Set in form actions / +server / hooks; read in server load.

Avoid:

Global module-level singletons that get reassigned (the rune transform breaks across module boundaries — see svelte-core "Sharing State Across Modules").
Putting per-request server state in module scope — SvelteKit reuses module instances across requests, so anything you write to a module-level variable from a load function leaks between users.
Mixing legacy writable stores with runes in the same feature unless you have a migration reason.

Server-Only Modules

Three rules:

Anything in $lib/server/** is server-only — importing it from a +page.svelte or any *.client.* is a build error.
+page.server.ts, +layout.server.ts, +server.ts, hooks.server.ts are server-only.
$env/static/private and $env/dynamic/private are server-only.

When unsure, check whether a secret could leak. If it could, it goes server-side.

Performance

Loading

Streaming: Return promises (not awaited) from server load for non-critical data. Wrap in {#await} blocks. Keeps TTFB low.
Parallel loads: Sibling load functions run in parallel automatically. Avoid await parent() unless you actually need parent data; placement of await parent() controls whether you cause a waterfall.
fetch in load: Always use the load event's fetch (not the global). It coalesces SSR + hydration responses and forwards cookies.
Preload: data-sveltekit-preload-data="hover" on <a> (or an ancestor like <body>) starts the load on hover. Use "tap" for mobile-heavy apps.
Code-split: Routes are auto code-split. For large feature components, prefer dynamic import() inside an {#await} block.

Rendering

Prefer prerender = true for pages whose content is build-time stable. This produces zero-JS-by-default pages (when csr is also false) or hydration-only pages.
prerender = 'auto' is a useful fallback during incremental adoption.
Use csr = false for static content pages (docs, marketing) — eliminates the JS bundle.
Use ssr = false only for routes that genuinely can't render server-side (auth-walled dashboards backed by client-only APIs). The cost is a flash of empty content.

Reactivity

$derived is lazy and skips downstream updates when the value is referentially identical. Don't try to manually memoize; let the compiler do it.
$state.raw for large arrays/objects you replace wholesale. Avoids the proxy cost.
Avoid $effect for things that should be $derived. Effects run on every dependency change with all the cleanup overhead; deriveds are pull-based.
Keep effects narrow — read only what you need so dependency tracking stays accurate.

Bundle

Run vite build --mode=analyze (with rollup-plugin-visualizer) to inspect chunks.
Avoid importing large libraries at the route level when only one page uses them; dynamic-import them inside the page component.
Use precompress: true on adapters that support it.

Accessibility

The Svelte compiler emits a11y warnings — treat them as errors. They catch real issues:

a11y_click_events_have_key_events, a11y_no_static_element_interactions: if you put onclick on a non-button, you must also handle keyboard.
a11y_label_has_associated_control: pair every <label> with for or wrap.
a11y_missing_attribute: <img> needs alt, <a> needs href.
a11y_autofocus: don't auto-focus — disorients screen reader users.

Routing & focus

SvelteKit doesn't move focus on client-side navigation by default — set data-sveltekit-keepfocus carefully and consider a "skip to content" link plus an <h1> per page that focus moves to. Use afterNavigate to manage focus deliberately on SPA-style pages.

`aria-current="page"`

For nav links pointing at the current route:

<a href="/" aria-current={page.url.pathname === '/' ? 'page' : undefined}>Home</a>

For preserving the highlight during a slow navigation, $state.eager(page.url.pathname) reflects user intent immediately.

Reduced motion

import { prefersReducedMotion } from 'svelte/motion';
$: duration = prefersReducedMotion.current ? 0 : 300;

SEO

Set <svelte:head> per page (<title>, <meta name="description">, OG tags, canonical URL).
Prefer SSR or prerendering for any public, indexable page.
For sitemaps, expose +server.ts at /sitemap.xml returning XML with Content-Type: application/xml.
Use semantic HTML (<article>, <nav>, <main>) — Svelte's a11y warnings nudge you toward this anyway.
Avoid client-only rendering for marketing pages; crawlers vary in JS support.

TypeScript

Project setup

sv create with the TypeScript option scaffolds correct tsconfig.json (inherits from .svelte-kit/tsconfig.json which Kit generates). Don't override paths blindly — Kit relies on its aliases.

Components

<script lang="ts">
  import type { Snippet } from 'svelte';

  interface Props {
    title: string;
    count?: number;
    children?: Snippet;
    onsave?: (value: string) => void;
  }

  let { title, count = 0, children, onsave }: Props = $props();
</script>

Generic components

<script lang="ts" generics="T extends { id: string }">
  let { items, render }: { items: T[]; render: Snippet<[T]> } = $props();
</script>

{#each items as item (item.id)}
  {@render render(item)}
{/each}

Routes

PageProps, LayoutProps, PageServerLoad, PageLoad, LayoutServerLoad, LayoutLoad, RequestHandler, Actions — all from ./$types. Don't write them by hand; svelte-kit sync regenerates them.

App-wide types

src/app.d.ts:

declare global {
  namespace App {
    interface Locals { user?: { id: string; email: string } }
    interface PageData {}
    interface PageState { showModal?: boolean }
    interface Platform {}
    interface Error { code?: string }
  }
}
export {};

Locals is the type of event.locals. PageState types page.state (shallow routing). Platform types event.platform (Cloudflare bindings, etc.).

Testing

`vitest` for unit/component tests

Use @testing-library/svelte plus vitest:

// counter.test.ts
import { render, fireEvent } from '@testing-library/svelte';
import { expect, test } from 'vitest';
import Counter from './Counter.svelte';

test('increments', async () => {
  const { getByRole } = render(Counter, { props: { initial: 0 } });
  const button = getByRole('button');
  await fireEvent.click(button);
  expect(button.textContent).toContain('1');
});

For pure logic in .svelte.ts modules, vitest can import them directly — runes work in test mode when the vitest config includes the Svelte plugin.

`playwright` for E2E

tests/example.test.ts:

import { expect, test } from '@playwright/test';

test('home page', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
});

Run via npm run test after sv add playwright. Playwright spins up the dev or preview server automatically.

Test boundaries

Test pure functions in plain modules with vitest.
Test components with @testing-library/svelte.
Test routes (load functions, form actions) by calling the exported functions directly with mock event objects, OR by E2E with playwright.
Don't unit-test the framework — trust SvelteKit's primitives.

Error Handling

Expected vs. unexpected

Expected (error(404, '...'), fail(400, ...)): user-facing, status-coded. Use them liberally.
Unexpected (uncaught throw, runtime exceptions): logged via handleError. Never expose internals to the user.

Patterns

// +page.server.ts
import { error } from '@sveltejs/kit';

export const load: PageServerLoad = async ({ params, locals }) => {
  const post = await db.getPost(params.slug);
  if (!post) error(404, { message: 'post not found' });   // typed message
  if (!locals.user && post.private) error(401, 'login required');
  return { post };
};

For typed errors, augment App.Error in app.d.ts:

namespace App {
  interface Error { message: string; code?: 'NOT_FOUND' | 'FORBIDDEN' }
}

`+error.svelte`

Show the error from page.error and consider linking back home or to the previous page. Keep production messages generic; rely on logs for diagnostics.

Form actions

Return validation problems with fail(status, data) instead of throwing — the form prop preserves user input.

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

`<svelte:boundary>`

For component-level recovery (e.g., a flaky third-party widget), wrap it in a boundary with a failed snippet that includes a reset() button. Don't use boundaries to hide bugs — log via onerror={(err) => report(err)}.

Migration & Compatibility

Don't half-migrate within a single file. A file is either runes-mode (uses any rune) or legacy. Mixing breaks subtle assumptions.
<svelte:options runes={true} /> forces runes mode for that component when the project default is legacy.
Use sv migrate svelte-5 for codemods on incoming Svelte 4 code.

Hygiene Checklist Before Marking a Task Done

[ ] Compiler a11y warnings addressed (or explicitly suppressed with reason)
[ ] No console.log left in production paths
[ ] No server-only imports from client code (pnpm check / npm run check passes)
[ ] All public-facing pages have <svelte:head> with title + description
[ ] Form actions return fail(...) for validation, throw error(...) for unexpected
[ ] All {#each} over reorderable lists are keyed
[ ] All effects with subscriptions return a cleanup function
[ ] Generated types (./$types) are imported, not hand-written
[ ] svelte-check passes

Svelte 5 / SvelteKit — Best Practices

Cross-cutting guidance: how to choose the right primitives, keep apps fast and accessible, and write code that doesn't break in production.

State Management Strategy

Pick the smallest scope that works:

Component-local — let x = $state(0) inside a .svelte file. Default for anything not shared.
Per-feature module — .svelte.ts exporting an object with mutable fields (export const counter = $state({ value: 0 })). Default for cross-component state in a feature.
Context — setContext / getContext for tree-scoped state where multiple components need a per-instance shared object (e.g., a form, a dropdown). Pair context with a reactive $state object so the value can update.
URL — for state that should survive reloads, deep-link, or affect SSR (filters, pagination, tabs). Read via page.url.searchParams, write via goto('?x=1', { replaceState: true, keepFocus: true, noScroll: true }).
Cookies / DB — for state that crosses sessions or needs server enforcement. Set in form actions / +server / hooks; read in server load.

Avoid:

Global module-level singletons that get reassigned (the rune transform breaks across module boundaries — see svelte-core "Sharing State Across Modules").
Putting per-request server state in module scope — SvelteKit reuses module instances across requests, so anything you write to a module-level variable from a load function leaks between users.
Mixing legacy writable stores with runes in the same feature unless you have a migration reason.

Server-Only Modules

Three rules:

Anything in $lib/server/** is server-only — importing it from a +page.svelte or any *.client.* is a build error.
+page.server.ts, +layout.server.ts, +server.ts, hooks.server.ts are server-only.
$env/static/private and $env/dynamic/private are server-only.

When unsure, check whether a secret could leak. If it could, it goes server-side.

Performance

Loading

Streaming: Return promises (not awaited) from server load for non-critical data. Wrap in {#await} blocks. Keeps TTFB low.
Parallel loads: Sibling load functions run in parallel automatically. Avoid await parent() unless you actually need parent data; placement of await parent() controls whether you cause a waterfall.
fetch in load: Always use the load event's fetch (not the global). It coalesces SSR + hydration responses and forwards cookies.
Preload: data-sveltekit-preload-data="hover" on <a> (or an ancestor like <body>) starts the load on hover. Use "tap" for mobile-heavy apps.
Code-split: Routes are auto code-split. For large feature components, prefer dynamic import() inside an {#await} block.

Rendering

Prefer prerender = true for pages whose content is build-time stable. This produces zero-JS-by-default pages (when csr is also false) or hydration-only pages.
prerender = 'auto' is a useful fallback during incremental adoption.
Use csr = false for static content pages (docs, marketing) — eliminates the JS bundle.
Use ssr = false only for routes that genuinely can't render server-side (auth-walled dashboards backed by client-only APIs). The cost is a flash of empty content.

Reactivity

$derived is lazy and skips downstream updates when the value is referentially identical. Don't try to manually memoize; let the compiler do it.
$state.raw for large arrays/objects you replace wholesale. Avoids the proxy cost.
Avoid $effect for things that should be $derived. Effects run on every dependency change with all the cleanup overhead; deriveds are pull-based.
Keep effects narrow — read only what you need so dependency tracking stays accurate.

Bundle

Run vite build --mode=analyze (with rollup-plugin-visualizer) to inspect chunks.
Avoid importing large libraries at the route level when only one page uses them; dynamic-import them inside the page component.
Use precompress: true on adapters that support it.

Accessibility

The Svelte compiler emits a11y warnings — treat them as errors. They catch real issues:

a11y_click_events_have_key_events, a11y_no_static_element_interactions: if you put onclick on a non-button, you must also handle keyboard.
a11y_label_has_associated_control: pair every <label> with for or wrap.
a11y_missing_attribute: <img> needs alt, <a> needs href.
a11y_autofocus: don't auto-focus — disorients screen reader users.

Routing & focus

`aria-current="page"`

For nav links pointing at the current route:

<a href="/" aria-current={page.url.pathname === '/' ? 'page' : undefined}>Home</a>

For preserving the highlight during a slow navigation, $state.eager(page.url.pathname) reflects user intent immediately.

Reduced motion

import { prefersReducedMotion } from 'svelte/motion';
$: duration = prefersReducedMotion.current ? 0 : 300;

SEO

Set <svelte:head> per page (<title>, <meta name="description">, OG tags, canonical URL).
Prefer SSR or prerendering for any public, indexable page.
For sitemaps, expose +server.ts at /sitemap.xml returning XML with Content-Type: application/xml.
Use semantic HTML (<article>, <nav>, <main>) — Svelte's a11y warnings nudge you toward this anyway.
Avoid client-only rendering for marketing pages; crawlers vary in JS support.

TypeScript

Project setup

sv create with the TypeScript option scaffolds correct tsconfig.json (inherits from .svelte-kit/tsconfig.json which Kit generates). Don't override paths blindly — Kit relies on its aliases.

Components

<script lang="ts">
  import type { Snippet } from 'svelte';

  interface Props {
    title: string;
    count?: number;
    children?: Snippet;
    onsave?: (value: string) => void;
  }

  let { title, count = 0, children, onsave }: Props = $props();
</script>

Generic components

<script lang="ts" generics="T extends { id: string }">
  let { items, render }: { items: T[]; render: Snippet<[T]> } = $props();
</script>

{#each items as item (item.id)}
  {@render render(item)}
{/each}

Routes

App-wide types

src/app.d.ts:

declare global {
  namespace App {
    interface Locals { user?: { id: string; email: string } }
    interface PageData {}
    interface PageState { showModal?: boolean }
    interface Platform {}
    interface Error { code?: string }
  }
}
export {};

Locals is the type of event.locals. PageState types page.state (shallow routing). Platform types event.platform (Cloudflare bindings, etc.).

Testing

`vitest` for unit/component tests

Use @testing-library/svelte plus vitest:

// counter.test.ts
import { render, fireEvent } from '@testing-library/svelte';
import { expect, test } from 'vitest';
import Counter from './Counter.svelte';

test('increments', async () => {
  const { getByRole } = render(Counter, { props: { initial: 0 } });
  const button = getByRole('button');
  await fireEvent.click(button);
  expect(button.textContent).toContain('1');
});

For pure logic in .svelte.ts modules, vitest can import them directly — runes work in test mode when the vitest config includes the Svelte plugin.

`playwright` for E2E

tests/example.test.ts:

import { expect, test } from '@playwright/test';

test('home page', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
});

Run via npm run test after sv add playwright. Playwright spins up the dev or preview server automatically.

Test boundaries

Test pure functions in plain modules with vitest.
Test components with @testing-library/svelte.
Test routes (load functions, form actions) by calling the exported functions directly with mock event objects, OR by E2E with playwright.
Don't unit-test the framework — trust SvelteKit's primitives.

Error Handling

Expected vs. unexpected

Expected (error(404, '...'), fail(400, ...)): user-facing, status-coded. Use them liberally.
Unexpected (uncaught throw, runtime exceptions): logged via handleError. Never expose internals to the user.

Patterns

// +page.server.ts
import { error } from '@sveltejs/kit';

export const load: PageServerLoad = async ({ params, locals }) => {
  const post = await db.getPost(params.slug);
  if (!post) error(404, { message: 'post not found' });   // typed message
  if (!locals.user && post.private) error(401, 'login required');
  return { post };
};

For typed errors, augment App.Error in app.d.ts:

namespace App {
  interface Error { message: string; code?: 'NOT_FOUND' | 'FORBIDDEN' }
}

`+error.svelte`

Show the error from page.error and consider linking back home or to the previous page. Keep production messages generic; rely on logs for diagnostics.

Form actions

Return validation problems with fail(status, data) instead of throwing — the form prop preserves user input.

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

`<svelte:boundary>`

Migration & Compatibility

Don't half-migrate within a single file. A file is either runes-mode (uses any rune) or legacy. Mixing breaks subtle assumptions.
<svelte:options runes={true} /> forces runes mode for that component when the project default is legacy.
Use sv migrate svelte-5 for codemods on incoming Svelte 4 code.

Hygiene Checklist Before Marking a Task Done

[ ] Compiler a11y warnings addressed (or explicitly suppressed with reason)
[ ] No console.log left in production paths
[ ] No server-only imports from client code (pnpm check / npm run check passes)
[ ] All public-facing pages have <svelte:head> with title + description
[ ] Form actions return fail(...) for validation, throw error(...) for unexpected
[ ] All {#each} over reorderable lists are keyed
[ ] All effects with subscriptions return a cleanup function
[ ] Generated types (./$types) are imported, not hand-written
[ ] svelte-check passes

Adoption

hirogakatageri/svelte-best-practices

$ install --global

Security Scan Results

SKILL.md

Svelte 5 / SvelteKit — Best Practices

State Management Strategy

Server-Only Modules

Performance

Loading

Rendering

Reactivity

Bundle

Accessibility

Routing & focus

aria-current="page"

Reduced motion

SEO

TypeScript

Project setup

Components

Generic components

Routes

App-wide types

Testing

vitest for unit/component tests

playwright for E2E

Test boundaries

Error Handling

Expected vs. unexpected

Patterns

+error.svelte

Form actions

<svelte:boundary>

Migration & Compatibility

Hygiene Checklist Before Marking a Task Done

Related Skills

hirogakatageri/verify-and-fix

hirogakatageri/svelte-env-vars-check

hirogakatageri/save-log

hirogakatageri/query-changes

hirogakatageri/svelte-best-practices

$ install --global

Security Scan Results

SKILL.md

Svelte 5 / SvelteKit — Best Practices

State Management Strategy

Server-Only Modules

Performance

Loading

Rendering

Reactivity

Bundle

Accessibility

Routing & focus

aria-current="page"

Reduced motion

SEO

TypeScript

Project setup

Components

Generic components

Routes

App-wide types

Testing

vitest for unit/component tests

playwright for E2E

Test boundaries

Error Handling

Expected vs. unexpected

Patterns

+error.svelte

Form actions

<svelte:boundary>

Migration & Compatibility

Hygiene Checklist Before Marking a Task Done

Related Skills

hirogakatageri/verify-and-fix

hirogakatageri/svelte-env-vars-check

hirogakatageri/save-log

`aria-current="page"`

`vitest` for unit/component tests

`playwright` for E2E

`+error.svelte`

`<svelte:boundary>`

`aria-current="page"`

`vitest` for unit/component tests

`playwright` for E2E

`+error.svelte`

`<svelte:boundary>`