SvelteKit Advanced

Advanced SvelteKit features reference. Covers state management across server/client, the remote functions API, env vars (legacy and explicit), hooks (server/shared/universal), error handling, link options, service workers, server-only modules, snapshots, shallow routing, and the $app/* modules.

Source: official SvelteKit llms.txt documentation.

When to use this skill

Use this skill when you need to:

Choose where state lives (server context, URL, snapshot, store).
Build type-safe client/server RPC with query/form/command/prerender.
Read env vars safely (private vs public, static vs dynamic).
Customize request handling via hooks (handle, handleFetch, handleError, handleValidationError, reroute, transport, init).
Throw expected/unexpected errors, customize the fallback error page, type error shape via App.Error.
Configure link behavior with data-sveltekit-* attributes.
Add a service worker for offline / precaching.
Prevent secret leak via .server.* or $lib/server/.
Persist ephemeral DOM state with snapshots or route history entries with shallow routing.
Use the $app/* modules (forms, navigation, state, paths, server, environment, types).

Do NOT use this skill for routing, form actions (legacy), load, basic setup, adapters configuration beyond env vars, or CSS/styling.

Critical sections

1. State management

No shared server state — module-level variables (let user;) leak across requests. Authenticate via cookies, persist to DB.
Pure load functions — no side effects (no global stores). Return data instead.
Context for per-request state — setContext('user', () => data.user) (pass a function so reactivity crosses boundaries). Reading context updated during SSR in a child does NOT propagate to the parent (it has already rendered).
Component state is preserved across nav — const derived from data only computes once. Use $derived(...) for values that should recompute when data changes.
URL state — search params for filters/sort; survives reload, affects SSR.
Snapshots — disposable UI state (e.g., "is accordion open?") bound to history entry.

2. Remote functions (since 2.27, experimental)

Opt in via svelte.config.js:

kit: { experimental: { remoteFunctions: true } },
compilerOptions: { experimental: { async: true } }

Flavors exported from *.remote.js:

| Flavor | Purpose | Key features | |---|---|---| | query | Read dynamic server data | Dedup, refresh(), loading/error/current | | query.batch | Batch n+1 queries in one call | Returns (input, idx) => Output | | query.live | Real-time async iterable | connected, reconnect(); first value serialized for SSR | | form | Progressive-enhanced <form> | <form {...createPost}>, createPost.fields.x.as('text'), validate(), enhance(), for(id), preflight(schema) | | command | Imperative mutation from event handlers | Cannot be called during render | | prerender | Build-time data | inputs, dynamic: true |

Validate with any Standard Schema (Zod/Valibot).
Args/returns serialized via devalue.
getRequestEvent() works inside remote functions for cookies.
redirect(...) allowed in query/form/prerender, NOT in command.
Single-flight mutations: getPosts().refresh() or getPost(id).set(...) in server handler; requested(getPosts, 1).refreshAll() for client-requested refreshes (limit is DoS protection).

3. Environment variables

Legacy $env/* (default before SvelteKit 2.63):

| Module | Scope | Timing | |---|---|---| | $env/dynamic/private | Server only | Runtime (process.env-like) | | $env/dynamic/public | Public (PUBLIC_*) | Runtime | | $env/static/private | Server only | Build time (inlined) | | $env/static/public | Public | Build time (inlined) |

Explicit env vars (opt-in, default in v3):

Enable in svelte.config.js: kit.experimental.explicitEnvironmentVariables = true. Then create src/env.ts:

import { defineEnvVars } from '@sveltejs/kit/hooks';
import * as v from 'valibot';
import { building } from '$app/env';

export const variables = defineEnvVars({
  API_KEY: {},                              // private
  GOOGLE_ANALYTICS_ID: { public: true },    // public
  SHOW_DEBUG_OVERLAY: { public: true, static: true },  // inlined, dead-code-eliminated
  SECRET: { schema: building ? v.optional(v.string()) : v.string() },
  CACHE_TTL_SECONDS: { description: 'How long...' }
});

Import from $app/env/private or $app/env/public. $app/environment is renamed to $app/env.

4. Hooks

Three optional files: src/hooks.server.js, src/hooks.client.js, src/hooks.js.

Server (hooks.server.js):

handle({ event, resolve }) — runs on every request; return Response or call resolve(event, opts). resolve opts: transformPageChunk, filterSerializedResponseHeaders, preload. Use sequence(...) for multiple.
handleFetch({ request, fetch, event }) — rewrite cross-origin requests to internal APIs; cookie forwarding for sibling subdomains.
handleValidationError({ event, issues }) — customize 400 response for bad remote function args.

Shared (hooks.server.js AND hooks.client.js):

handleError({ error, event, status, message }) — for unexpected errors only. Return { message, ... } -> becomes page.error. Must never throw. Server type: HandleServerError; client type: HandleClientError; client event is NavigationEvent.
init() — runs once at startup; useful for DB connections.

Universal (hooks.js):

reroute({ url, fetch }) — translate URL to a different route (e.g., i18n). Pure/idempotent. Can be async since 2.18.
transport — custom encoders/decoders for types crossing the server/client boundary (e.g., Vector).

5. Errors

Expected errors — error(404, 'Not found') (or error(404, { message, code })) from @sveltejs/kit. Renders nearest +error.svelte, sets status code. page.error = the object passed.
Unexpected errors — any other exception. Not exposed (generic Internal Error); routed through handleError.
Rendering errors — opt in via experimental.handleRenderingErrors. Error passed directly to +error.svelte as error prop (not via page.error).
Responses — custom src/error.html with %sveltekit.status% and %sveltekit.error.message%. Errors in root +layout.server.js use fallback page (root contains +error.svelte).
Type safety — declare App.Error interface in src/app.d.ts:

declare global {
  namespace App {
    interface Error { message: string; code: string; id: string; }
  }
}

6. Link options

data-sveltekit-* attributes on <a> (or parent). Also apply to <form method="GET">.

| Attribute | Values | Effect | |---|---|---| | preload-data | hover (default), tap | Preload load data on hover/tap | | preload-code | eager, viewport, hover, tap | Preload route code only | | reload | boolean | Force full-page nav (also rel="external") | | replacestate | boolean | Replace history entry instead of push | | keepfocus | boolean | Keep focus on the same element after nav | | noscroll | boolean | Disable scroll-to-top after nav |

Disable in subtree with data-sveltekit-preload-data="false". Respects navigator.connection.saveData.

7. Service workers

Place src/service-worker.js (or src/service-worker/index.js) — bundled and auto-registered. Disable via config to register manually.

Available from $service-worker: base, build, files, prerendered, version.

Standard pattern: cache build + files on install, network-first with cache fallback on fetch. Skip responses with Cache-Control: no-store (live queries). build/prerendered are empty arrays in dev.

8. Server-only modules

$env/static/private and $env/dynamic/private — server-only.
$app/server — server-only.
Your modules — add .server.js suffix OR place under $lib/server/.

Illegal imports from browser code error at build. Use import type for type-only. Detection is disabled in tests (process.env.TEST === 'true').

9. Snapshots & shallow routing

Snapshots — export snapshot = { capture, restore } from +page.svelte or +layout.svelte. Captured to sessionStorage before page updates; restored on history nav. Must be JSON-serializable. Don't return huge objects.

Shallow routing — pushState(url, state) / replaceState(url, state) create history entries without navigating. Read via page.state. Use preloadData(href) to grab load data, then pushState(href, { selected: result.data }) to render another +page.svelte inside a modal. page.state is always {} on first SSR and during first paint.

Quick Fixes

| Symptom | Fix | |---|---| | User data leaks between requests | Don't use module-level vars; use cookies + DB | | load data not updating on nav | Use $derived(...) not const for values derived from data | | Cannot import $lib/server/... | Move shared types to import type | | Live query stream stops | Reconnect with .reconnect(); don't cache no-store responses in SW | | error(404, ...) shows blank page | Add +error.svelte nearest to the route | | Server-only env leaked to client | Use $env/static/private or .server naming | | Validation 400 generic message | Implement handleValidationError | | Component state lost on nav | Wrap with {#key page.url.pathname}<X/>{/key} to force remount |

Gotchas

load must be pure — no global store writes. Return the data instead.
Context updates during SSR don't propagate up — pass state down to avoid flash on hydration.
query.batch returns a single function that maps individual inputs to outputs; not a direct array of results.
query.live on SSR returns ONLY the first yielded value then closes.
command cannot be called during render — invoke from event handlers.
requested requires a limit — DoS protection; pass Infinity only if explicitly safe.
error() no longer needs throw in SvelteKit 2.x.
page.state is {} on SSR and first paint — don't rely on it for critical render.
reroute must be pure/idempotent — its result is cached per URL on the client.
Service worker build/prerendered empty in dev — test in production build.
Cookie forwarding for sibling subdomains requires manual handleFetch — SvelteKit can't tell which parent-domain cookie belongs to which subdomain.
handleError must not throw — wrap risky work in try/catch.

FAQ

Q: $app/state vs $app/stores? A: $app/state (since 2.12) is rune-based and reactive. $app/stores is the legacy store-based version. Use $app/state with Svelte 5.

Q: query vs prerender? A: query for dynamic data; prerender for build-time-frozen data that can be served from a CDN. query cannot be used on a fully prerendered page.

Q: form vs command? A: form is progressive-enhanced — works without JS, spreads onto <form>. command is JS-only, called from event handlers. Prefer form.

Q: $env/dynamic vs $env/static? A: dynamic reads at runtime (e.g., process.env); static inlined at build time (enables dead-code elimination). Use static for build-time-known values.

Q: $env/static/private vs $env/dynamic/private? A: Same access restriction; difference is when the value is read. Static gives DCE; dynamic allows runtime override (e.g., MY_FLAG=1 npm run dev).

Q: Can I use $lib/server modules from +page.svelte? A: No — server-only modules cannot be imported by client code, transitively. SvelteKit errors at build.

Q: How do I keep focus on a search input after submit? A: Add data-sveltekit-keepfocus to the <form>.

Q: How do I throw a 404 from a load? A: import { error } from '@sveltejs/kit'; error(404, 'Not found'); (don't throw in SvelteKit 2).

Q: Should I use Sentry? A: Yes — initialize in handleError of both hooks.server.js and hooks.client.js. Server uses HandleServerError; client uses HandleClientError with NavigationEvent.

Examples

| Topic | File | |---|---| | State management with context + URL + derived | examples/state-management.md | | Remote query/form/command/batch/live | examples/remote-functions.md | | Env vars (legacy + explicit) | examples/env-vars.md | | Server + universal hooks | examples/hooks.md | | Expected/unexpected errors + App.Error | examples/errors.md | | data-sveltekit-* link options | examples/link-options.md | | Service worker precache + offline | examples/service-worker.md | | $app/* modules (forms, navigation, state, paths, server) | examples/app-modules.md | | Snapshots + shallow routing | examples/shallow-snapshots.md |

References

| Topic | File | |---|---| | State management | references/state-management.md | | Remote functions | references/remote-functions.md | | Environment variables | references/env-vars.md | | Hooks | references/hooks.md | | Errors | references/errors.md | | Link options | references/link-options.md | | Service workers | references/service-worker.md | | Server-only modules | references/server-only.md | | $app/* modules | references/app-modules.md | | Snapshots & shallow routing | references/shallow-snapshots.md |