sveltekit-config

SvelteKit Config

When to use this skill

Use this skill whenever you are working on SvelteKit's configuration, build pipeline, deployment, performance, images, accessibility, SEO, debugging, or migration concerns. This includes:

• Choosing or configuring an adapter (adapter-node, adapter-static, adapter-cloudflare, adapter-netlify, adapter-vercel)
• Building (vite build) and previewing (vite preview) production apps
• Advanced routing (rest params, optional params, matchers, route sorting, filename encoding)
• Advanced layouts (route groups, breaking out of layouts with @)
• Auth integration patterns (sessions vs tokens, hooks-based auth)
• Performance optimization (code splitting, asset opt, avoiding waterfalls)
• Image handling (@sveltejs/enhanced-img, CDN loading, <picture>/<img> patterns)
• Accessibility (route announcements, focus management, lang attribute)
• SEO (titles, meta tags, sitemaps, JSON-LD)
• Breakpoint debugging (VS Code, Chrome DevTools)
• Migrating from SvelteKit v1 or Sapper

For routing/data/load basics, see sveltekit-overview. For Svelte components/runes, see svelte-runes.

Critical: Building and previewing

vite build runs in two stages: Vite produces an optimized production build, then your adapter tailors the output for the target platform. Prerendering executes during build.

During the build, SvelteKit loads your +page/layout(.server).js for analysis. Code that must NOT run at build time should guard with building from $app/environment:

import { building } from '$app/environment';
import { initialiseDatabase } from '$lib/server/database';

if (!building) initialiseDatabase();

export function load() { /* ... */ }

After building, run vite preview (or npm run preview) to test the production build locally. Preview runs in Node, so adapter-specific behavior (e.g. Cloudflare's platform object) does NOT apply — use wrangler dev for Cloudflare or the platform's CLI for accurate testing.

npm run build       # vite build + adapter
npm run preview     # vite preview (Node)

Critical: Adapters — when to use which

The adapter is configured in svelte.config.js under kit.adapter. adapter-auto ships by default in new projects and picks the right adapter for known deployment environments (Cloudflare Pages, Netlify, Vercel, Azure SWA, SST, Google Cloud Run). Once you've chosen a target, install that adapter explicitly so it lands in your lockfile.

Adapter quick guide:

// svelte.config.js
import adapter from '@sveltejs/adapter-node';
export default { kit: { adapter: adapter() } };

Platform-specific context

Some adapters expose platform info (KV namespaces, Durable Objects, env vars) via event.platform in hooks/server routes. Type augmentation in src/app.d.ts:

declare global {
  namespace App {
    interface Platform {
      env: { MY_KV: KVNamespace };
    }
  }
}
export {};

Always prefer $env/static/private for environment variables — $env/dynamic/* cannot be used during prerendering.

Critical: Advanced routing

SvelteKit routes are filesystem-based. Beyond basic dynamic segments, you have several advanced features.

Rest parameters — [...rest]

Match an unknown number of segments. src/routes/a/[...rest]/z/+page.svelte matches /a/z, /a/b/z, /a/b/c/z. The rest param is a string with /-separated segments.

src/routes/[org]/[repo]/tree/[branch]/[...file]/+page.svelte

Use rest parameters to render custom 404s — add [...path]/+page.js that calls error(404) so a nested +error.svelte is reached.

Optional parameters — [[lang]]

Wrap with double brackets to make a param optional. [[lang]]/home matches both /home and /en/home. An optional param cannot follow a rest param.

Matching — [name=type]

Constrain a parameter with a matcher from src/params/:

// src/params/fruit.js
/** @type {import('@sveltejs/kit').ParamMatcher} */
export function match(param) {
  return param === 'apple' || param === 'orange';
}

Then write src/routes/fruits/[page=fruit]/+page.svelte. Matchers run on both server and browser.

Sorting

When multiple routes match, SvelteKit sorts by:

1. More specific routes win (fewer params = more specific)
2. Matchers ([name=type]) beat unconstrained ([name])
3. [[optional]] and [...rest] are lowest priority unless they're the final segment
4. Ties resolved alphabetically

Encoding special characters

Use hex escape [x+nn] in folder names: / → [x+2f], : → [x+3a], etc. Use [u+nnnn] for Unicode (no surrogate pairs needed).

src/routes/smileys/[x+3a]-[x+29]/+page.svelte
# matches /smileys/:-)

Critical: Advanced layouts

By default, the layout hierarchy mirrors the folder hierarchy. Use these patterns to reshape it.

Route groups — (group)

Parentheses-wrapped folder names don't appear in the URL. Use to share a layout between routes without affecting URL structure.

src/routes/
├ (app)/dashboard/+page.svelte
├ (app)/+layout.svelte          # app shell
├ (marketing)/about/+page.svelte
├ (marketing)/+layout.svelte    # marketing shell
└ +layout.svelte

Breaking out — +page@layout.svelte

Append @<segment> (or @ for root) to reset the layout chain. +page@(app).svelte inherits only from (app)/+layout.svelte.

Options: +page@[id].svelte, +page@item.svelte, +page@(app).svelte, +page@.svelte.

Layouts can also break out: +layout@.svelte rewinds to root for everything below it.

Reset to root

If you want most of your app under one layout but a few routes to escape, put everything inside a group except the outliers:

src/routes/
├ (app)/...
└ admin/+page.svelte   # does NOT inherit (app) layout

Critical: Auth integration

Auth = authentication (who is this?) + authorization (what can they do?).

Sessions vs tokens

• Sessions: ID stored in DB. Revocable instantly, requires DB lookup per request.
• JWT tokens: Self-contained, no DB lookup, but cannot be revoked immediately. Better latency.

Integration pattern

Check auth cookies in src/hooks.server.js, populate event.locals.user, then read locals in +page.server.js / +server.js load functions.

// src/hooks.server.js
export async function handle({ event, resolve }) {
  event.locals.user = await getUser(event.cookies.get('session'));
  return resolve(event);
}

Libraries

• npx sv add better-auth — Better Auth integration via Svelte CLI
• Lucia auth guide — reference SvelteKit examples for session-based auth

Always require path: '/' when calling cookies.set(...) in SvelteKit v2.

Critical: Performance optimization

SvelteKit ships with: code-splitting, asset preloading, file hashing, request coalescing, parallel loading, data inlining, conservative invalidation, link preloading. To go further:

Diagnose

• PageSpeed Insights / Lighthouse / WebPageTest
• Chrome DevTools Network + Performance tabs
• Test in preview mode (after vite build), not dev mode

Assets

• Use @sveltejs/enhanced-img for images (smaller formats, intrinsic dimensions)
• Lazy-load below-the-fold videos with preload="none"
• Subset fonts; preload critical fonts via handle hook's preload filter

Code size

• Use Svelte 5 (smaller than 4)
• Use rollup-plugin-visualizer to find heavy packages
• Prefer dynamic import() for conditional code
• Push third-party scripts to web workers (Partytown)

Avoid waterfalls

• Use server `load` functions for backend calls (avoid client → server → backend chains)
• Issue parallel queries with Promise.all / DB joins
• SPA mode causes waterfalls — prerender instead

Hosting

• Deploy frontend near backend (or use edge)
• Ensure HTTP/2+

Critical: Images

Vite's built-in handling

<script>
  import logo from '$lib/assets/logo.png';
</script>
<img alt="logo" src={logo} />

Vite hashes the filename and inlines small assets.

@sveltejs/enhanced-img

Build-time image optimization: generates avif/webp, sets intrinsic width/height (prevents CLS), strips EXIF.

// vite.config.js — plugin order matters
import { enhancedImages } from '@sveltejs/enhanced-img';
import { sveltekit } from '@sveltejs/kit/vite';
export default { plugins: [enhancedImages(), sveltekit()] };

Usage:

<enhanced:img src="./image.jpg" alt="..." sizes="min(1280px, 100vw)" />

Generated <picture> includes multiple formats and sizes for HiDPI. Provide 2x source for retina displays.

Custom widths: <enhanced:img src="./image.png?w=1280;640;400" /> Per-image transforms: <enhanced:img src="./image.jpg?blur=15" />

Dynamic CDN loading

For images unavailable at build time (CMS, DB), use a CDN library:

• @unpic/svelte — CDN-agnostic
• svelte-cloudinary — Cloudinary
• CMS-bundled: Contentful, Storyblok, Contentstack

Best practices

• Set fetchpriority="high" and avoid loading="lazy" for LCP images
• Always provide alt text
• Don't use em/rem in sizes
• Mix strategies: Vite for <meta>, enhanced-img for hero, CDN for user content

Critical: Accessibility

SvelteKit provides an accessible foundation; you're still responsible for app-level a11y.

Route announcements

SvelteKit injects a live region that reads the <title> after each client-side navigation. Every page must have a unique, descriptive <title> in a <svelte:head>:

<svelte:head>
  <title>Todo List</title>
</svelte:head>

Focus management

After each navigation, SvelteKit focuses <body> (or [autofocus] element if present). Override with afterNavigate for custom behavior:

import { afterNavigate } from '$app/navigation';
afterNavigate(() => document.querySelector('.focus-me')?.focus());

Use data-sveltekit-keepfocus on a <form> to preserve input focus. goto(url, { keepFocus: true }) for programmatic nav.

lang attribute

Set <html lang="en"> (or your language) in src/app.html. For multi-language sites, use a transformPageChunk in handle to set per-request.

Critical: SEO

SvelteKit ships with SSR, normalized trailing-slash URLs, and good defaults. Manual steps:

Per-page meta

<svelte:head>
  <title>Page Title — Site Name</title>
  <meta name="description" content="..." />
  <meta property="og:title" content="..." />
  <meta property="og:description" content="..." />
  <meta property="og:image" content="..." />
  <meta property="og:type" content="website" />
  <link rel="canonical" href="https://..." />
</svelte:head>

Common pattern: return SEO data from load, render in root layout's <svelte:head>.

Sitemap

// src/routes/sitemap.xml/+server.js
export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      <!-- <url> entries -->
    </urlset>`, { headers: { 'Content-Type': 'application/xml' } });
}

JSON-LD structured data

Inject via <svelte:head> with <script type="application/ld+json">.

Critical: Migration

SvelteKit v1 → v2

Use npx sv migrate sveltekit-2 (or npx svelte-migrate for older projects). Breaking changes:

• error(...) and redirect(...) are no longer thrown — just call them
• cookies.set/delete/serialize requires path: '/'
• Top-level promises in load are NOT awaited automatically — use await explicitly
• goto no longer accepts external URLs (use window.location.href)
• paths are now consistently relative (default true)
• $app/stores deprecated in 2.12 — migrate to $app/state (Svelte 5 runes)
• Svelte 4 required, Node 18.13+
• vitePreprocess must be imported from @sveltejs/vite-plugin-svelte

Sapper → SvelteKit

• package.json: add "type": "module", remove polka/sapper/sirv/compression
• Add @sveltejs/kit + an adapter
• Scripts: sapper build → vite build, sapper dev → vite dev, node __sapper__/build → node build
• src/template.html → src/app.html (replace %sapper.* placeholders)
• Routes: routes/about/index.svelte → routes/about/+page.svelte
• _layout.svelte → +layout.svelte, _error.svelte → +error.svelte
• preload → load (different API: single event arg, no this.fetch)
• stores / navigating from $app/stores (or $app/state in 2.12+)
• Regex routes → matchers in src/params/
• sapper:prefetch → data-sveltekit-preload-data
• sapper:noscroll → data-sveltekit-noscroll
• Move internal libs from src/node_modules/... to src/lib

Critical: Debugging

VS Code

Built-in debug terminal works out of the box:

1. CMD/Ctrl+Shift+P → "Debug: JavaScript Debug Terminal"
2. Run npm run dev in that terminal
3. Set breakpoints, hit them in the browser

Or create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    { "command": "npm run dev", "name": "dev", "request": "launch", "type": "node-terminal" }
  ]
}

Chrome DevTools / Edge

NODE_OPTIONS="--inspect" npm run dev

Open the site, then click the "Open dedicated DevTools for Node.js" icon (Node logo, top-left). Or visit chrome://inspect.

Quick Fixes

• `building` flag: Wrap one-time init code in if (!building) to prevent it running during vite build.
• `fallback` in `adapter-static`: Use 200.html for SPA mode, but avoid index.html (conflicts with prerendered /).
• GitHub Pages: Set paths.base to repo name and fallback: '404.html'. Add .nojekyll to static/.
• Node origin: Set ORIGIN env var if you're behind a proxy and see "Cross-site POST form submissions are forbidden".
• XFF depth: Behind N proxies, set XFF_DEPTH=N so getClientAddress() returns the real client IP.
• Compression: Use @polka/compression not compression — SvelteKit streams responses.
• `.env` in production: Production doesn't auto-load .env. Use node --env-file=.env build (Node 20.6+) or -r dotenv/config.
• `platform` only in dev/preview: Test Cloudflare/Netlify/Vercel platform APIs with their respective CLIs (wrangler dev, netlify dev, vercel dev).
• `fs` not available: Use read from $app/server (works in edge by fetching from deployed assets).
• `goto` external URL: Use window.location.href instead.
• Cookie path: SvelteKit v2 requires path: '/' on cookies.set(...).
• Trailing slash: Set trailingSlash: 'always' if your host doesn't serve /a.html from /a.

Gotchas

• Preview is not production: vite preview runs in Node, doesn't emulate adapter-specific behavior. Use the platform's CLI for accurate local testing.
• `adapter-auto` is just for zero-config: Once you've decided on a target, install the real adapter so it lands in the lockfile and you can pass options.
• Server bundle size on Cloudflare: Workers have a size limit. Move large libraries to client-only imports if you hit it.
• AWS / Node 18: SvelteKit v2 requires Node 18.13+. Older Node versions fail with cryptic errors.
• ISR + prerender: ISR has no effect on routes with export const prerender = true.
• `adapter-cloudflare-workers` deprecated: Use @sveltejs/adapter-cloudflare (with assets.directory + assets.binding in wrangler config).
• Svelte 4 → 5: $app/stores is deprecated; use $app/state. Update Svelte first, then SvelteKit.
• Tailwind + `<enhanced:img>`: Tag-name selectors need enhanced\:img to escape the colon.
• Match `data-sveltekit-noscroll` for chat/SPA-like UIs: Default scroll-to-top behavior can break infinite-scroll apps.
• Vite asset inlining: Assets below assetsInlineLimit (default ~4kb) get base64-inlined. Excludes svg for enhanced-img.

FAQ

Should I use `adapter-auto`? Yes for prototyping. Once you've chosen a target, swap to the specific adapter so you can configure it.

SPA mode vs full SSR? Full SSR with adapter-static (prerender) is best for SEO/perf. SPA fallback is for when you must deploy to static-only hosting without prerendering everything. SPA hurts SEO and performance.

When should I prerender? Pages that return the same content for every visitor (marketing pages, blog posts, docs). Add export const prerender = true to the route.

How do I know which adapter is being used in production? adapter-auto logs at build time which one it picked. Otherwise, check svelte.config.js.

Can I use the same `svelte.config.js` for multiple adapters? No — you must run vite build once per adapter. Common CI pattern: build matrix per target.

Why is my Cloudflare Worker huge? Bundle bloat — server-side imports pull in large deps. Move them to dynamic import() or client-only.

Do I need Svelte 5 for SvelteKit 2? You need Svelte 4+. Svelte 5 is recommended for $app/state and runes.

Examples & References

Examples

References