` element. Every page needs unique, descriptive title: ```svelte <svelte:head> <title>Todo List

## Directories ### getting_started Initial setup, project structure, rendering modes, and standard web APIs available in SvelteKit. ## Project Creation Initialize with `npx sv create my-app`, runs on localhost:5173. CLI scaffolds project and optionally sets up TypeScript. Each page is a Svelte component in `src/routes`, server-rendered on first visit then client-side app takes over. ## Project Structure ``` src/ ├ lib/ [utilities, components, imported via $lib] │ └ server/ [server-only code, imported via $lib/server] ├ params/ [param matchers] ├ routes/ [application routes] ├ app.html [page template with %sveltekit.head%, %sveltekit.body%, %sveltekit.assets%, %sveltekit.nonce%, %sveltekit.env.[NAME]%, %sveltekit.version%] ├ error.html [fallback error page with %sveltekit.status%, %sveltekit.error.message%] ├ hooks.client.js [client hooks] ├ hooks.server.js [server hooks] ├ service-worker.js └ tracing.server.js static/ [static assets served as-is] tests/ [Playwright tests] package.json [must include @sveltejs/kit, svelte, vite as devDependencies, "type": "module"] svelte.config.js [Svelte/SvelteKit config] tsconfig.json [extends .svelte-kit/tsconfig.json] vite.config.js [uses @sveltejs/kit/vite plugin] ``` Everything except `src/routes` and `src/app.html` is optional. `.svelte-kit/` is generated and can be deleted. ## Rendering Modes **Default (Hybrid)**: SSR for initial load (SEO, perceived performance), then CSR for navigation (faster without re-rendering common components). **Static Site Generation**: Use `adapter-static` to prerender entire site, or `prerender` option for specific pages. Use `adapter-vercel` with ISR for large sites. **Single-Page App**: Exclusive CSR. Write backend separately in SvelteKit or another language. **Multi-Page App**: Remove JavaScript with `csr = false` or use `data-sveltekit-reload` for server-rendered links. **Serverless**: Use `adapter-auto` for zero-config, or platform-specific: `adapter-vercel`, `adapter-netlify`, `adapter-cloudflare`. Some offer `edge` option for edge rendering. **Own Server/Container**: Use `adapter-node`. **Library**: Use `@sveltejs/package` add-on. **Offline/PWA**: Full service worker support. **Mobile/Desktop**: Turn SPA into mobile app with Tauri/Capacitor or desktop app with Tauri/Wails/Electron. Use `bundleStrategy: 'single'` to limit concurrent requests. **Browser Extension**: Use `adapter-static` or community adapters. **Embedded Device**: Use `bundleStrategy: 'single'` for low-power devices. ## Web APIs Standard `fetch` available in hooks, server routes, browser. Special version in `load` functions, server hooks, API routes invokes endpoints directly during SSR without HTTP calls, preserving credentials. Server-side `fetch` outside `load` requires explicit `cookie`/`authorization` headers. Allows relative requests. `Request` accessible in hooks/server routes as `event.request`. Methods: `request.json()`, `request.formData()`. `Response` returned from `await fetch(...)` and `+server.js` handlers. `Headers` interface reads `request.headers`, sets `response.headers`: ```js import { json } from '@sveltejs/kit'; export function GET({ request }) { return json({ userAgent: request.headers.get('user-agent') }, { headers: { 'x-custom-header': 'potato' } }); } ``` `FormData` for HTML form submissions: ```js export async function POST(event) { const body = await event.request.formData(); return json({ name: body.get('name') ?? 'world' }); } ``` Streams: `ReadableStream`, `WritableStream`, `TransformStream` for large/chunked responses. URL APIs: `URL` interface in `event.url` (hooks/server routes), `page.url` (pages). Query parameters via `url.searchParams.get('foo')`. Web Crypto: `crypto` global available, e.g., `crypto.randomUUID()`. ## Editor Setup Recommended: Visual Studio Code with Svelte extension. ### core_concepts Filesystem routing, load functions for data, form actions for mutations, page options for rendering strategy, state management patterns, and type-safe remote functions for client-server communication. # Core Concepts ## Routing Filesystem-based routing in `src/routes` directory. Route files use `+` prefix: - `+page.svelte`: page component (SSR + CSR) - `+page.js`: universal load function (server + browser) - `+page.server.js`: server-only load function with database/env access - `+layout.svelte`/`+layout.js`/`+layout.server.js`: layouts apply to directory and subdirectories - `+error.svelte`: error boundary, walks up tree to find closest handler - `+server.js`: API routes exporting HTTP handlers (GET, POST, PATCH, PUT, DELETE, OPTIONS, HEAD) Load functions provide data to components via `data` prop. `+server.js` exports HTTP verb handlers returning Response. `$types` provides auto-generated type safety for load functions and components. ## Load Functions Load functions return data to components. Universal loads (`+page.js`, `+layout.js`) run on server during SSR and in browser during navigation, can return any values. Server loads (`+page.server.js`, `+layout.server.js`) run server-only, must return serializable data (JSON, BigInt, Date, Map, Set, RegExp, promises). Receive `params` (route parameters), `url` (URL object), `route` (route ID), `fetch` (credentialed fetch), `setHeaders` (cache headers), `parent()` (parent layout data), `depends(url)` (manual dependency), `untrack(fn)` (exclude from tracking). Throw `error(status, message)` for errors, use `redirect(status, location)` for redirects. Streaming: return promises from server loads, they resolve on client. Rerun when params/url change, parent reruns, or `invalidate(url)` / `invalidateAll()` called. Search parameters tracked independently. ## Form Actions Export `actions` from `+page.server.js` to handle POST from `

`. Default action or named actions via query parameter (`?/actionName`). Receive `RequestEvent`, read form data with `request.formData()`. Return data available as `form` prop and `page.form` app-wide. Use `fail(status, data)` for validation errors (typically 400/422). Use `redirect(status, location)` to redirect after action. Page re-renders with action return value unless redirect/error. Load functions run after action completes. Progressive enhancement with `use:enhance` directive (no full-page reload). Customize with `SubmitFunction` callback receiving `{ formElement, formData, action, cancel, submitter }` returning async callback with `{ result, update }`. Use `applyAction(result)` to apply result manually. `deserialize()` response (not JSON.parse) to handle Date/BigInt. ## Page Options Export from `+page.js`, `+page.server.js`, `+layout.js`, or `+layout.server.js`: - `prerender`: true/false/'auto' - render at build time as static HTML - `ssr`: false - render only on client (empty shell) - `csr`: false - no JavaScript, HTML/CSS only - `trailingSlash`: 'never'/'always'/'ignore' - control trailing slash behavior - `config`: adapter-specific configuration object Child layouts/pages override parent values. Prerenderer crawls from root following `` links; specify additional pages via `config.kit.prerender.entries`. Pages with form actions cannot be prerendered. Accessing `url.searchParams` during prerendering forbidden. ## State Management Never store shared state in server variables (visible to all users). Load functions must be pure, don't write to stores. Use context API to safely share state per-request/user via `setContext`/`getContext`. Component state preserved on navigation (data props update but lifecycle methods don't rerun) - use `$derived` for reactivity, `afterNavigate`/`beforeNavigate` for code that must rerun, `{#key}` to destroy/remount. Store URL-affecting state in search parameters (`?sort=price`). Use snapshots for ephemeral UI state (accordion open/closed) surviving navigation but not page refresh. ## Remote Functions Type-safe client-server communication via `.remote.js`/`.remote.ts` files. Four types: - `query(schema?, fn)`: read dynamic data, returns Promise-like with `loading`, `error`, `current`, or `await`. Caches per-page. Call `.refresh()` to re-fetch. Use `query.batch(schema, fn)` for n+1 problem. - `form(schema, fn)`: write data, returns object with `method`, `action` for non-JS fallback, progressive enhancement. Access fields via `form.fields.fieldName.as(type)`. Validate with `.validate()`, `.preflight()`. Get/set values with `.value()`, `.set()`. Use `.enhance()` for custom submission, `.for(id)` for repeated forms, `.buttonProps` for multiple buttons. - `command(schema, fn)`: write from anywhere, not tied to elements. Cannot call during render. Update queries via `.refresh()` or `.updates(query)`. - `prerender(schema?, fn, options)`: build-time static data, cached via Cache API. Specify inputs via `inputs()` option. Excluded from server bundle by default; set `dynamic: true` to allow non-prerendered arguments. Validate arguments with Standard Schema (Zod, Valibot). Both arguments and return values serialize via devalue. Single-flight mutations: server-side call `.refresh()` or `.set()` in form handler, client-side use `.updates()`. Sensitive fields use leading underscore to prevent repopulation. Use `getRequestEvent()` to access cookies/auth. Return `{ redirect: location }` from command instead of `redirect()`. ### build_and_deploy Build process, deployment adapters (official and custom), and platform-specific configuration for Cloudflare, Netlify, Node, static sites, and Vercel. ## Build Process SvelteKit builds in two stages via `vite build`: 1. **Vite optimization**: Creates optimized production builds of server, browser, and service worker code. Prerendering executes here if configured. 2. **Adapter tuning**: Adapter optimizes the build for the target deployment environment. Code that shouldn't execute at build time must check the `building` flag from `$app/environment`: ```js import { building } from '$app/environment'; if (!building) { setupMyDatabase(); } ``` Preview production builds locally with `vite preview` (doesn't perfectly reproduce deployed app). ## Adapters Overview Adapters are deployment plugins configured in `svelte.config.js` that transform built SvelteKit apps into deployment-ready output. **Official adapters**: - `@sveltejs/adapter-cloudflare` — Cloudflare Workers/Pages - `@sveltejs/adapter-netlify` — Netlify - `@sveltejs/adapter-node` — Node servers - `@sveltejs/adapter-static` — Static site generation - `@sveltejs/adapter-vercel` — Vercel Platform-specific context available via `RequestEvent.platform` (e.g., Cloudflare's `env` object with KV namespaces). ## adapter-auto (Zero-Config) Default adapter that automatically detects deployment environment and uses the appropriate adapter. Supports Cloudflare Pages, Netlify, Vercel, Azure Static Web Apps, AWS via SST, Google Cloud Run. Install specific adapter for config options and CI optimization. Does not accept configuration options. ## adapter-node Build standalone Node.js servers. Configuration via environment variables: - `PORT`, `HOST`, `SOCKET_PATH` (default `0.0.0.0:3000`) - `ORIGIN` or `PROTOCOL_HEADER`/`HOST_HEADER`/`PORT_HEADER` for reverse proxies - `ADDRESS_HEADER`, `XFF_DEPTH` for client IP behind proxies - `BODY_SIZE_LIMIT` (default 512kb, supports K/M/G suffixes) - `SHUTDOWN_TIMEOUT` (default 30s) Adapter options: ```js adapter({ out: 'build', precompress: true, envPrefix: '' }) ``` Graceful shutdown: listen to `sveltekit:shutdown` event for cleanup. Supports systemd socket activation with `IDLE_TIMEOUT`. Custom server via `handler.js` middleware for Express/Connect/Polka/Node http. For response compression, use `@polka/compression` (not `compression` package, which doesn't support streaming). Load `.env` files: in dev/preview SvelteKit reads automatically; in production use `node -r dotenv/config build` or Node v20.6+ `node --env-file=.env build`. ## adapter-static Prerender entire SvelteKit site as static files. Configuration: ```js adapter({ pages: 'build', assets: 'build', fallback: undefined, precompress: false, strict: true }) ``` Set `trailingSlash: 'always'` if host doesn't render `/a.html` for `/a` requests. **GitHub Pages**: Set `paths.base` to repo name, use `fallback: '404.html'`, add `.nojekyll` to `static/` if not using GitHub Actions. ## Single-Page Apps (SPA) Configure SvelteKit as client-rendered SPA using `adapter-static` with fallback page. Disable SSR globally with `export const ssr = false` in `+layout.js`. Significant performance/SEO drawbacks: multiple network round trips before content displays, harms Core Web Vitals, fails accessibility if JS disabled. Mitigation: prerender as many pages as possible, especially homepage. Fallback page serves any unhandled URLs. Avoid `index.html` to prevent conflicts with prerendering. Consult host docs for correct fallback filename (e.g., Surge uses `200.html`). Re-enable `ssr` and `prerender` for specific pages to server-render them during build to static `.html` files. Apache configuration example: ``` RewriteEngine On RewriteBase / RewriteRule ^200\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /200.html [L] ``` ## adapter-cloudflare Deploy to Cloudflare Workers or Pages. Configuration: ```js adapter({ config: undefined, platformProxy: { configPath, environment, persist }, fallback: 'plaintext', routes: { include: ['/*'], exclude: [''] } }) ``` **Workers**: Create `wrangler.jsonc`: ```jsonc { "name": "", "main": ".svelte-kit/cloudflare/_worker.js", "compatibility_date": "2025-01-01", "assets": { "binding": "ASSETS", "directory": ".svelte-kit/cloudflare" } } ``` **Pages**: Use Git integration with framework preset SvelteKit, build command `npm run build`, output directory `.svelte-kit/cloudflare`. Functions in `/functions` directory are NOT included; implement as SvelteKit server endpoints instead. Access Cloudflare bindings via `platform.env`: ```js declare global { namespace App { interface Platform { env: { YOUR_KV_NAMESPACE: KVNamespace; YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; }; } } } export async function POST({ request, platform }) { const x = platform?.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } ``` Local emulation: Cloudflare values in `platform` are emulated during dev/preview. For build testing use Wrangler v4: `wrangler dev .svelte-kit/cloudflare` (Workers) or `wrangler pages dev .svelte-kit/cloudflare` (Pages). Troubleshooting: Add `nodejs_compat` flag for Node.js compatibility. Can't use `fs` in Workers; use `read()` from `$app/server` or prerender routes. Single bundled file must not exceed Cloudflare size limits. Migration from deprecated `adapter-cloudflare-workers`: Replace adapter, remove `site` config, add `assets.directory` and `assets.binding` to wrangler config. ## adapter-netlify Deploy to Netlify. Configuration: ```js adapter({ edge: false, split: false }) ``` Requires `netlify.toml`: ```toml [build] command = "npm run build" publish = "build" ``` Set `edge: true` for Deno-based edge functions instead of Node. Set `split: true` to deploy each route as individual function. **Netlify Forms**: Create HTML form with hidden `form-name` input, prerender the form page (`export const prerender = true`). For custom success messages, ensure success page exists and is prerendered. **Netlify Functions**: SvelteKit endpoints become Netlify Functions. Access Netlify context via `event.platform?.context` in hooks and server endpoints. Place `_headers` and `_redirects` files in project root for static asset responses. Use `_redirects` instead of `[[redirects]]` in `netlify.toml` (higher priority). Don't add custom catch-all rules. Add custom Netlify functions by creating directory and configuring in `netlify.toml`: ```toml [functions] directory = "functions" ``` Troubleshooting: Can't use `fs` in edge deployments; use `read()` from `$app/server` instead (works in both edge and serverless) or prerender routes. ## adapter-vercel Deploy to Vercel. Configuration: ```js adapter({ images: { sizes, formats, minimumCacheTTL, domains }, // route-level config via export const config = { ... } }) ``` Control route deployment via `export const config` in `+server.js`, `+page(.server).js`, or `+layout(.server).js`: ```js export const config = { split: true, runtime: 'edge' | 'nodejs20.x' | 'nodejs22.x', regions: ['iad1'], memory: 1024, maxDuration: 10, isr: { expiration, bypassToken, allowQuery } } ``` **Incremental Static Regeneration (ISR)**: Only use on routes where all visitors see same content (no user-specific data). Generate bypass token: `crypto.randomUUID()` (≥32 chars). Set as `BYPASS_TOKEN` environment variable on Vercel. Pull locally: `vercel env pull .env.development.local`. Bypass cache via `__prerender_bypass=` cookie or `x-prerender-revalidate: ` header. **Skew Protection**: Vercel routes requests to original deployment via cookie with deployment ID. When user reloads, they get newest deployment. `updated.current` is exempt and reports new deployments. Enable in Advanced project settings. Caveat: multiple tabs with different versions will route older tabs to newer deployment, triggering SvelteKit's built-in skew protection. Environment variables from `$env/static/private` and `$env/dynamic/private` accessible on Vercel. Pass to client via server load. Troubleshooting: Can't use `fs` in edge functions. In serverless functions, use `read()` from `$app/server` instead (works in edge functions too by fetching from deployed public assets) or prerender routes. When using `read()` in edge functions with Deployment Protection enabled, must enable Protection Bypass for Automation. ## Writing Custom Adapters Adapter packages export default function returning `Adapter` object: ```js export default function (options) { return { name: 'adapter-package-name', async adapt(builder) { // implementation }, async emulate() { return { async platform({ config, prerender }) { // returned object becomes event.platform during dev, build, preview } } }, supports: { read: ({ config, route }) => true/false, tracing: () => true/false } } } ``` **Adapt method requirements**: 1. Clear build directory 2. Write SvelteKit output using `builder.writeClient()`, `builder.writeServer()`, `builder.writePrerendered()` 3. Output code that: - Imports `Server` from `${builder.getServerDirectory()}/index.js` - Instantiates app with manifest from `builder.generateManifest({ relativePath })` - Listens for platform requests, converts to standard `Request` if needed - Calls `server.respond(request, { getClientAddress })` to generate `Response` - Exposes platform-specific information via `platform` option to `server.respond()` - Globally shims `fetch` if necessary (SvelteKit provides `@sveltejs/kit/node/polyfills` for undici-compatible platforms) 4. Bundle output to avoid requiring dependencies on target platform (if necessary) 5. Place user's static files and generated JS/CSS in correct location for target platform Recommended: place adapter output under `build/` directory with intermediate output under `.svelte-kit/[adapter-name]`. Look at source code of existing adapters for similar platforms as starting point. ### advanced_features Advanced routing, hooks, error handling, link optimization, service workers, server-only modules, state preservation, shallow routing, observability, and component library packaging. ## Advanced Routing **Rest Parameters**: `[...file]` matches variable segments. `/[org]/[repo]/tree/[branch]/[...file]` extracts all path parts. Validate with matchers. Enable custom 404 handling via catch-all routes. **Optional Parameters**: `[[lang]]/home` matches both `home` and `en/home`. Cannot follow rest parameters. **Matchers**: Restrict parameter values with `src/params/fruit.js` exporting `match(param)` function. Use in routes: `[page=fruit]`. Run on server and browser. **Route Sorting**: When multiple routes match, priority is: static > dynamic > matchers > optional/rest. Alphabetical tiebreaker. **Encoding**: Filesystem/URL-reserved characters use hex escapes `[x+nn]`: `\`→`[x+5c]`, `/`→`[x+2f]`, `:`, `*`, `?`, `"`, `<`, `>`, `|`, `#`, `%`, `[`, `]`, `(`, `)`. Unicode: `[u+nnnn]` or literal emoji. **Route Groups**: Parenthesized directories `(app)`, `(marketing)` don't affect URL, enable different layouts per route set without affecting `/admin` routes. **Layout Reset**: `@` suffix on `+page.svelte` or `+layout.svelte` breaks out of layout hierarchy. `+page@(app).svelte` inherits `(app)/+layout.svelte`. `+page@.svelte` inherits root layout. `+layout@.svelte` resets for all children. ## Hooks **handle**: Runs every request. Modify response, bypass SvelteKit, transform HTML chunks, filter headers, control preloading. `resolve(event, { transformPageChunk, filterSerializedResponseHeaders, preload })`. **locals**: Populate `event.locals` with custom data (e.g., user info from cookies) accessible in `+server.js` and server `load` functions. **handleFetch**: Intercept `event.fetch` calls. Rewrite URLs, forward cookies to cross-origin APIs. Same-origin requests forward `cookie`/`authorization` headers by default; cross-origin includes cookies only for subdomains. **handleValidationError**: Called when remote function receives invalid arguments. Return object matching `App.Error` shape. **handleError**: Called on unexpected errors during loading/rendering/endpoints. Receives `error`, `event`, `status`, `message`. Log to services like Sentry. Not called for expected errors from `error()` helper. Must never throw. **init**: Runs once at startup (server) or app start (browser). Async initialization like database connections. Top-level await equivalent. **reroute**: Runs before `handle`. Changes URL-to-route mapping. Returns pathname used for route selection. Can be async (v2.18+) with `fetch` argument. Must be pure/idempotent; result cached on client. **transport**: Custom type serialization across server/client boundary. Each type has `encode` (server) and `decode` (client) functions. Example: `Vector: { encode: v => v instanceof Vector && [v.x, v.y], decode: ([x,y]) => new Vector(x,y) }`. ## Errors **Expected Errors**: Created with `error(404, { message: 'Not found' })` or `error(404, 'Not found')`. Caught by SvelteKit, sets status, renders nearest `+error.svelte` with `page.error`. **Unexpected Errors**: Any exception not from `error()` helper. Default response: `{ "message": "Internal Error" }`. Pass through `handleError` hook for custom handling. **Custom Error Shape**: Declare `App.Error` interface in `src/app.d.ts` with additional properties like `code`, `id`. **Fallback Error Page**: Customize `src/error.html` with `%sveltekit.status%` and `%sveltekit.error.message%` placeholders. **Error Boundaries**: Errors in `load` render nearest `+error.svelte`. Errors in root `+layout.js`/`+layout.server.js` use fallback page (root layout would contain error boundary). ## Link Options **data-sveltekit-preload-data**: Preload page code and data. Values: `"hover"` (default), `"tap"`. Skipped if `navigator.connection.saveData` is true. Programmatic: `preloadData()` from `$app/navigation`. **data-sveltekit-preload-code**: Preload only code with eagerness: `"eager"`, `"viewport"`, `"hover"`, `"tap"`. Only applies to links in DOM after navigation. No effect if `preload-data` is more eager. Respects `saveData`. **data-sveltekit-reload**: Force full-page navigation instead of client-side. Same as `rel="external"`. **data-sveltekit-replacestate**: Use `replaceState` instead of `pushState` for history. **data-sveltekit-keepfocus**: Retain focus on currently focused element after navigation. Useful for search forms. **data-sveltekit-noscroll**: Prevent scroll to top after navigation. Default scrolls to top unless link has `#hash`. **Disabling**: Set attribute to `"false"` to disable inherited options. Works on `` too. ## Service Workers **Automatic Registration**: If `src/service-worker.js` or `src/service-worker/index.js` exists, auto-bundled and registered on page load. **$service-worker Module**: Access `build` (built app files), `files` (static assets), `version` (app version for cache names), `base` (deployment base path). **Example Strategy**: Cache-first for assets, network-first for dynamic content. Install handler caches all assets. Activate handler cleans old caches. Fetch handler serves cached assets, tries network with cache fallback. **Development**: Only works in browsers supporting ES modules in service workers. Manual registration requires `type: dev ? 'module' : 'classic'`. `build` and `prerendered` are empty during dev. **Caching Considerations**: Stale cached data worse than unavailable. Browsers auto-clear when full; avoid caching large assets. ## Server-only Modules **Purpose**: Prevent accidental exposure of sensitive data (API keys, private env vars) to browser. **Private Env Vars**: `$env/static/private` and `$env/dynamic/private` only importable in server-only code. **Server-only Utilities**: `$app/server` module (contains `read()` for filesystem) is server-only. **Creating**: Add `.server` suffix (`secrets.server.js`) or place in `$lib/server/` directory. **Validation**: SvelteKit prevents importing server-only code into browser code, even indirectly through re-exports. Entire import chain checked. Error: "Cannot import ... into code that runs in the browser". **Dynamic Imports**: Works with dynamic imports including interpolated: `` await import(`./${foo}.js`) ``. **Testing**: Unit test frameworks don't distinguish; illegal import detection disabled when `process.env.TEST === 'true'`. ## Snapshots **Purpose**: Preserve ephemeral DOM state (scroll, form values) across navigation. **Implementation**: Export `snapshot` object from `+page.svelte` or `+layout.svelte` with `capture()` and `restore(value)` methods. `capture()` called before navigation, result stored in history. `restore()` called with stored value after page updates. **Constraints**: Data must be JSON-serializable (persists to `sessionStorage`). State restored on reload or back navigation from different site. Avoid large objects—remain in memory for session duration. ## Shallow Routing **Purpose**: Create history entries without navigation for modals/overlays. **Basic Usage**: `pushState('', { showModal: true })` creates history entry, accessible via `page.state`. First arg is relative URL (use `''` for current). Type-safe via `App.PageState` interface in `src/app.d.ts`. Use `replaceState` to set state without new entry. **Loading Data**: Use `preloadData(href)` to load route data for rendering another `+page.svelte` inside current page. Returns `{ type: 'loaded', status, data }` or error. If element has `data-sveltekit-preload-data`, request already made. **Caveats**: `page.state` always empty during SSR. State not applied until navigation on first landing. Requires JavaScript; provide fallback. **Legacy**: `page.state` from `$app/state` added in v2.12. Earlier versions use `$page.state` from `$app/stores`. ## Observability **OpenTelemetry Tracing**: Server-side spans for `handle` hooks, `load` functions, form actions, remote functions (v2.31+). **Enable**: Set `experimental: { tracing: { server: true }, instrumentation: { server: true } }` in `svelte.config.js`. **Augmenting**: Access `event.tracing.root` and `event.tracing.current` spans via `getRequestEvent()`. Set attributes: `event.tracing.root.setAttribute('userId', user.id)`. **Jaeger Setup**: Install `@opentelemetry/sdk-node`, `@opentelemetry/auto-instrumentations-node`, `@opentelemetry/exporter-trace-otlp-proto`, `import-in-the-middle`. Create `src/instrumentation.server.js` with NodeSDK config. Run Jaeger, view traces at localhost:16686. **Peer Dependency**: `@opentelemetry/api` optional; satisfied by trace collection libraries or install manually. ## Packaging **Overview**: Use `@sveltejs/package` to build component libraries. `src/lib` is public (library code), `src/routes` optional (docs/demo). `svelte-package` generates `dist` with preprocessed components, transpiled TypeScript, auto-generated types. **package.json Fields**: - `name`: Package name - `license`: Usage rights (e.g., MIT) - `files`: `["dist"]` (npm always includes package.json, README, LICENSE) - `exports`: Entry points. Default: `{ ".": { "types": "./dist/index.d.ts", "svelte": "./dist/index.js" } }`. Multiple: `{ ".": {...}, "./Foo.svelte": {...} }` imported as `import Foo from 'your-library/Foo.svelte'` - `svelte`: Legacy field for backwards compatibility - `sideEffects`: `["**/*.css"]` for tree-shaking; list CSS and side-effect scripts **TypeScript**: Auto-generated type definitions. Problem: TypeScript doesn't resolve `types` condition for non-root exports by default. Solutions: (1) Require consumers to set `moduleResolution` to `bundler`/`node16`/`nodenext` (recommended), (2) Use `typesVersions` field to map types: `{ "typesVersions": { ">4.0": { "foo": ["./dist/foo.d.ts"] } } }`. **Best Practices**: Avoid SvelteKit-specific modules (`$app/*`); use `esm-env` instead. Pass context as props. Define aliases in `svelte.config.js`. Semantic versioning: removing `exports` paths is breaking; adding is not. **Source Maps**: Enable `declarationMap: true` in tsconfig for "Go to Definition" support. **svelte-package Options**: `-w`/`--watch`, `-i`/`--input` (default: `src/lib`), `-o`/`--output` (default: `dist`), `-p`/`--preserve-output`, `-t`/`--types` (default: true), `--tsconfig`. **Caveats**: All relative imports must have extensions per Node ESM: `import { x } from './something/index.js'`. TypeScript imports use `.js` extension even for `.ts` files. Non-Svelte/TypeScript files copied as-is; Svelte preprocessed, TypeScript transpiled. ### best_practices Comprehensive best practices covering authentication (sessions vs JWT), performance optimization (built-in features, asset optimization, code reduction, waterfall prevention), icons (CSS vs Svelte libraries), image handling (Vite, enhanced-img, CDN), accessibility (announcements, focus, lang), and SEO (SSR, titles, sitemaps, AMP). ## Authentication and Authorization **Sessions vs Tokens**: Session IDs are stored in database, can be immediately revoked but require DB query per request. JWTs are not checked against datastore, cannot be immediately revoked, but offer improved latency and reduced load. **Implementation**: Check auth cookies in server hooks, store user info in `locals`. Use Lucia for session-based auth via `npx sv add lucia`. ## Performance Optimization **Built-in Features**: Code-splitting, asset preloading, file hashing, request coalescing, parallel loading, data inlining, conservative invalidation, prerendering, link preloading. **Diagnosing**: Use PageSpeed Insights, WebPageTest, browser devtools (Chrome/Edge Lighthouse, Network, Performance tabs). Test in preview mode, not dev. Instrument slow APIs with OpenTelemetry or Server-Timing headers. **Assets**: - Images: Use `@sveltejs/enhanced-img` package - Videos: Compress with Handbrake to `.webm`/`.mp4`, lazy-load with `preload="none"`, strip audio with FFmpeg - Fonts: In `handle` hook call `resolve` with `preload` filter, subset fonts to reduce size **Code Reduction**: Use latest Svelte (5 < 4 < 3 in size). Use `rollup-plugin-visualizer` to identify large packages. Minimize third-party scripts; use server-side analytics (Cloudflare, Netlify, Vercel) instead of JS-based. Use dynamic `import(...)` for conditional loading instead of static imports. **Navigation**: Return promises from `load` for slow non-essential data; server `load` functions stream after navigation. Prevent waterfalls: use server `load` functions for backend requests (avoids high-latency round trips), use database joins instead of sequential queries. **Hosting**: Frontend in same datacenter as backend, deploy to edge for sites without central backend, serve images from CDN, use HTTP/2+. ## Icons **CSS-based**: Use Iconify for many icon sets via CSS, works with Tailwind CSS or UnoCSS plugins via Iconify's framework plugins. **Svelte**: Avoid libraries providing one `.svelte` file per icon (thousands of files severely slow Vite's dependency optimization, especially with umbrella + subpath imports). ## Images **Vite Built-in**: Automatically processes imported assets with hashing for caching and inlining for small assets. ```svelte

``` **@sveltejs/enhanced-img**: Plug-and-play image processing generating smaller formats (avif/webp), setting intrinsic width/height to prevent layout shift, creating multiple sizes for devices, stripping EXIF. Setup: ```js import { enhancedImages } from '@sveltejs/enhanced-img'; export default defineConfig({ plugins: [enhancedImages(), sveltekit()] }); ``` Usage: ```svelte ``` At build time replaced with `` wrapped by `

sveltejs/sveltekit