## docs/kit/10-getting-started/10-introduction.md # SvelteKit Introduction ## What is SvelteKit? SvelteKit is a framework for building web applications using Svelte. Similar to Next.js (React) or Nuxt (Vue). ## What is Svelte? Svelte is a UI component framework that compiles components to optimized JavaScript and CSS. ## SvelteKit vs Svelte Svelte handles UI components. SvelteKit provides a complete application framework with: - Routing - Build optimizations - Offline support - Page preloading - Configurable rendering (SSR, CSR, prerendering) - Image optimization - HMR development experience via Vite ## Getting Started For beginners, check out the [interactive tutorial](/tutorial/kit) or get help in [Discord](/chat). ## docs/kit/10-getting-started/20-creating-a-project.md # Creating a SvelteKit Project ```bash npx sv create my-app cd my-app npm install npm run dev ``` This scaffolds a new project with optional TypeScript setup. Server runs on [localhost:5173](http://localhost:5173). ## Core Concepts - Pages are Svelte components - Pages are created in `src/routes` directory - Pages are server-rendered first, then hydrated client-side ## Editor Setup - Recommended: VS Code with [Svelte extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) - [Other editor support](https://sveltesociety.dev/resources#editor-support) ## docs/kit/10-getting-started/25-project-types.md # Project Types in SvelteKit SvelteKit offers configurable rendering to build various application types. Rendering settings can be mixed for optimal performance. ## Default Rendering - First page: Server-side rendering (SSR) - Subsequent pages: Client-side rendering (CSR) - Benefits: Better SEO, perceived performance, and smooth navigation ## Static Site Generation - Use `adapter-static` for fully prerendered sites - Selectively prerender pages with `prerender` option - For large sites, use Incremental Static Regeneration with `adapter-vercel` ## Single-Page App ```js // In src/routes/+layout.js export const ssr = false; ``` ## Multi-Page App ```js // In src/routes/+page.js export const csr = false; ``` Or use `data-sveltekit-reload` on links to force server rendering. ## Deployment Options ### Separate Backend - Deploy SvelteKit frontend separately with `adapter-node` or serverless adapter - Skip `server` files when using external backend ### Serverless - Use `adapter-auto` (default) for zero-config deployment - Platform-specific: `adapter-vercel`, `adapter-netlify`, `adapter-cloudflare` - Some offer edge rendering for improved latency ### Self-Hosted - Use `adapter-node` for your own server/VPS or containers ## Other Project Types ### Library - Create Svelte libraries with `@sveltejs/package` ### Offline/PWA - Full support for service workers ### Mobile Apps - Use Tauri or Capacitor with SvelteKit SPA - Consider `bundleStrategy: 'single'` to limit requests ### Desktop Apps - Tauri, Wails, or Electron with SvelteKit SPA ### Browser Extensions - Use `adapter-static` or community adapters ### Embedded Devices - Consider `bundleStrategy: 'single'` to reduce concurrent requests ## docs/kit/10-getting-started/30-project-structure.md # Project Structure in SvelteKit A typical SvelteKit project structure: ```bash my-project/ ├ src/ │ ├ lib/ │ │ ├ server/ # Server-only code │ │ └ [lib files] # Shared components/utilities │ ├ params/ # Param matchers │ ├ routes/ # Application routes │ ├ app.html # Page template │ ├ error.html # Error page │ ├ hooks.client.js │ ├ hooks.server.js │ └ service-worker.js ├ static/ # Static assets ├ tests/ # Tests ├ package.json ├ svelte.config.js ├ tsconfig.json └ vite.config.js ``` ## Key Files ### src/app.html Template with placeholders: - `%sveltekit.head%` - Links, scripts, and `` content - `%sveltekit.body%` - Rendered page markup (place inside a container element) - `%sveltekit.assets%` - Path to assets - `%sveltekit.nonce%` - CSP nonce - `%sveltekit.env.[NAME]%` - Environment variables (must start with public prefix) ### src/error.html Fallback error page with placeholders: - `%sveltekit.status%` - HTTP status - `%sveltekit.error.message%` - Error message ### src/lib Library code importable via `$lib` alias. Server-only code goes in `lib/server/` and is importable via `$lib/server`. ### src/routes Contains application routes and route-specific components. ### static Static assets served as-is (favicon, robots.txt, etc.) ### Configuration Files - **package.json**: Must include `@sveltejs/kit`, `svelte`, and `vite` as `devDependencies` - **svelte.config.js**: Svelte and SvelteKit configuration - **vite.config.js**: Vite configuration with `@sveltejs/kit/vite` plugin - **tsconfig.json**: TypeScript configuration (extends `.svelte-kit/tsconfig.json`) ### Generated Files The `.svelte-kit` directory contains generated files that can be safely deleted (they'll be regenerated). ## docs/kit/10-getting-started/40-web-standards.md # Svelte Web Standards ## Fetch APIs SvelteKit uses standard `fetch` for network requests in hooks, server routes, and browser. > Special `fetch` version in `load` functions, server hooks, and API routes allows direct endpoint invocation during SSR without HTTP calls, preserving credentials. ### Request ```js // Access in hooks and server routes export function GET({ request }) { const data = await request.json(); // or request.formData() } ``` ### Response ```js // Return from server routes export function GET() { return new Response('Hello', { status: 200 }); } ``` ### Headers ```js /// file: src/routes/what-is-my-user-agent/+server.js import { json } from '@sveltejs/kit'; /** @type {import('./$types').RequestHandler} */ export function GET({ request }) { // log all headers console.log(...request.headers); // create a JSON Response using a header we received return json({ // retrieve a specific header userAgent: request.headers.get('user-agent') }, { // set a header on the response headers: { 'x-custom-header': 'potato' } }); } ``` ## FormData ```js /// file: src/routes/hello/+server.js import { json } from '@sveltejs/kit'; /** @type {import('./$types').RequestHandler} */ export async function POST(event) { const body = await event.request.formData(); // log all fields console.log([...body]); return json({ // get a specific field's value name: body.get('name') ?? 'world' }); } ``` ## Stream APIs Use `ReadableStream`, `WritableStream`, and `TransformStream` for large responses or chunked data. ## URL APIs Access URL properties via `event.url` in hooks/server routes, `page.url` in pages, and `from`/`to` in navigation events. ### URLSearchParams ```js const foo = url.searchParams.get('foo'); ``` ## Web Crypto ```js const uuid = crypto.randomUUID(); ``` ## docs/kit/20-core-concepts/10-routing.md # SvelteKit Routing ## +page ### +page.svelte Defines a page component rendered on server (SSR) and browser (CSR). ```svelte

Hello and welcome to my site!

About my site ``` Receive data from load functions: ```svelte

{data.title}

{@html data.content}
``` ### +page.js Load data for pages: ```js import { error } from '@sveltejs/kit'; /** @type {import('./$types').PageLoad} */ export function load({ params }) { if (params.slug === 'hello-world') { return { title: 'Hello world!', content: 'Welcome to our blog. Lorem ipsum dolor sit amet...' }; } error(404, 'Not found'); } ``` Configure page behavior with exports: - `export const prerender = true|false|'auto'` - `export const ssr = true|false` - `export const csr = true|false` ### +page.server.js Server-only load functions: ```js import { error } from '@sveltejs/kit'; /** @type {import('./$types').PageServerLoad} */ export async function load({ params }) { const post = await getPostFromDatabase(params.slug); if (post) { return post; } error(404, 'Not found'); } ``` Also supports form actions and page options. ## +error Custom error pages: ```svelte

{page.status}: {page.error.message}

``` SvelteKit walks up the tree to find the closest error boundary. ## +layout ### +layout.svelte Shared UI elements across multiple pages: ```svelte {@render children()} ``` Nested layouts: ```svelte

Settings

{#each data.sections as section} {section.title} {/each}
{@render children()} ``` ### +layout.js Load data for layouts: ```js /** @type {import('./$types').LayoutLoad} */ export function load() { return { sections: [ { slug: 'profile', title: 'Profile' }, { slug: 'notifications', title: 'Notifications' } ] }; } ``` ### +layout.server.js Server-only layout data loading, same pattern as +page.server.js. ## +server API routes with HTTP verb handlers: ```js import { error } from '@sveltejs/kit'; /** @type {import('./$types').RequestHandler} */ export function GET({ url }) { const min = Number(url.searchParams.get('min') ?? '0'); const max = Number(url.searchParams.get('max') ?? '1'); const d = max - min; if (isNaN(d) || d < 0) { error(400, 'min and max must be numbers, and min must be less than max'); } const random = min + Math.random() * d; return new Response(String(random)); } ``` Handling POST requests: ```js import { json } from '@sveltejs/kit'; /** @type {import('./$types').RequestHandler} */ export async function POST({ request }) { const { a, b } = await request.json(); return json(a + b); } ``` Fallback handler for unhandled methods: ```js /** @type {import('./$types').RequestHandler} */ export async function fallback({ request }) { return text(`I caught your ${request.method} request!`); } ``` Content negotiation happens automatically when +server.js and +page files share a directory. ## $types TypeScript definitions for routes: - `PageProps`/`LayoutProps` - Component props - `PageLoad`/`PageServerLoad`/`LayoutLoad`/`LayoutServerLoad` - Load function types - `RequestHandler` - Server endpoint handlers ## Other files - Any other files in route directories are ignored by SvelteKit - Use `$lib` for shared components and utilities ## docs/kit/20-core-concepts/20-load.md # Loading Data in SvelteKit ## Page Data Load data for pages using `+page.js` or `+page.server.js`: ```js // src/routes/blog/[slug]/+page.js export function load({ params }) { return { post: { title: `Title for ${params.slug} goes here`, content: `Content for ${params.slug} goes here` } }; } ``` ```svelte

{data.post.title}

{@html data.post.content}
``` ## Layout Data Load data for layouts using `+layout.js` or `+layout.server.js`: ```js // src/routes/blog/[slug]/+layout.server.js export async function load() { return { posts: await db.getPostSummaries() }; } ``` ```svelte
{@render children()}
``` Child components can access parent layout data: ```svelte ``` ## Universal vs Server Load Functions **Server load functions** (`+page.server.js`, `+layout.server.js`): - Always run on the server - Can access database, filesystem, private env vars - Must return serializable data - Have access to `cookies`, `locals`, etc. **Universal load functions** (`+page.js`, `+layout.js`): - Run on server during SSR, then in browser - Useful for fetching from external APIs - Can return non-serializable data (like component constructors) - Receive data from server load functions via `data` property ## URL Data Access URL information in load functions: ```js export function load({ url, route, params }) { // url - URL instance with pathname, searchParams, etc. // route.id - current route path (e.g., '/a/[b]/[...c]') // params - derived from url.pathname and route.id } ``` ## Making Fetch Requests Use the provided `fetch` function for data fetching: ```js export async function load({ fetch, params }) { const res = await fetch(`/api/items/${params.id}`); const item = await res.json(); return { item }; } ``` ## Headers and Cookies Set response headers: ```js export async function load({ fetch, setHeaders }) { const response = await fetch(url); setHeaders({ 'cache-control': response.headers.get('cache-control') }); return response.json(); } ``` Access cookies in server load functions: ```js export async function load({ cookies }) { const sessionid = cookies.get('sessionid'); return { user: await db.getUser(sessionid) }; } ``` ## Parent Data Access data from parent load functions: ```js export async function load({ parent }) { const { a } = await parent(); return { b: a + 1 }; } ``` ## Errors and Redirects Throw errors: ```js import { error } from '@sveltejs/kit'; export function load({ locals }) { if (!locals.user) { error(401, 'not logged in'); } } ``` Redirect users: ```js import { redirect } from '@sveltejs/kit'; export function load({ locals }) { if (!locals.user) { redirect(307, '/login'); } } ``` ## Streaming with Promises Server load functions can stream promises: ```js export async function load({ params }) { return { comments: loadComments(params.slug), // streamed as it resolves post: await loadPost(params.slug) }; } ``` Use in templates: ```svelte {#await data.comments} Loading comments... {:then comments} {#each comments as comment}

{comment.content}

{/each} {:catch error}

Error: {error.message}

{/await} ``` ## Rerunning Load Functions Load functions rerun when: - Referenced params or URL properties change - A parent load function reran and this function calls `await parent()` - A dependency was invalidated Manually invalidate load functions: ```js // In load function export function load({ fetch, depends }) { depends('app:random'); // custom identifier const response = await fetch('https://api.example.com/random-number'); return { number: await response.json() }; } // In component import { invalidate } from '$app/navigation'; function rerunLoadFunction() { invalidate('app:random'); } ``` ## Authentication Best practices: - Use hooks for protecting multiple routes - Use auth guards in `+page.server.js` for route-specific protection - Use `getRequestEvent()` for shared auth logic ```js // src/lib/server/auth.js import { redirect } from '@sveltejs/kit'; import { getRequestEvent } from '$app/server'; export function requireLogin() { const { locals, url } = getRequestEvent(); if (!locals.user) { redirect(307, `/login?${new URLSearchParams({ redirectTo: url.pathname + url.search })}`); } return locals.user; } ``` ## docs/kit/20-core-concepts/30-form-actions.md # Svelte Form Actions ## Default Actions A `+page.server.js` file can export actions for `POST` requests via `
`. ```js /// file: src/routes/login/+page.server.js /** @satisfies {import('./$types').Actions} */ export const actions = { default: async (event) => { // TODO log the user in } }; ``` ```svelte
``` From other pages, specify the action path: ```html /// file: src/routes/+layout.svelte
``` ## Named Actions ```js /// file: src/routes/login/+page.server.js /** @satisfies {import('./$types').Actions} */ export const actions = { login: async (event) => { // TODO log the user in }, register: async (event) => { // TODO register the user } }; ``` Invoke with query parameter: ```svelte
``` Use `formaction` to target different actions with the same form: ```svelte /// file: src/routes/login/+page.svelte
``` ## Action Anatomy Actions receive a `RequestEvent` object and can return data available through the `form` prop: ```js /// file: src/routes/login/+page.server.js import * as db from '$lib/server/db'; /** @satisfies {import('./$types').Actions} */ export const actions = { login: async ({ cookies, request }) => { const data = await request.formData(); const email = data.get('email'); const password = data.get('password'); const user = await db.getUser(email); cookies.set('sessionid', await db.createSession(user), { path: '/' }); return { success: true }; } }; ``` ```svelte {#if form?.success}

Successfully logged in! Welcome back, {data.user.name}

{/if} ``` ### Validation Errors Return validation errors with the `fail` function: ```js /// file: src/routes/login/+page.server.js import { fail } from '@sveltejs/kit'; /** @satisfies {import('./$types').Actions} */ export const actions = { login: async ({ cookies, request }) => { const data = await request.formData(); const email = data.get('email'); const password = data.get('password'); if (!email) { return fail(400, { email, missing: true }); } const user = await db.getUser(email); if (!user || user.password !== db.hash(password)) { return fail(400, { email, incorrect: true }); } // Success logic } }; ``` ```svelte /// file: src/routes/login/+page.svelte
{#if form?.missing}

The email field is required

{/if} {#if form?.incorrect}

Invalid credentials!

{/if}
``` ### Redirects ```js /// file: src/routes/login/+page.server.js import { fail, redirect } from '@sveltejs/kit'; /** @satisfies {import('./$types').Actions} */ export const actions = { login: async ({ cookies, request, url }) => { // Validation logic if (url.searchParams.has('redirectTo')) { redirect(303, url.searchParams.get('redirectTo')); } return { success: true }; } }; ``` ## Loading Data After an action runs, the page's `load` functions run. Note that `handle` runs before the action but not before the subsequent `load`: ```js /// file: src/routes/account/+page.server.js /** @type {import('./$types').PageServerLoad} */ export function load(event) { return { user: event.locals.user }; } /** @satisfies {import('./$types').Actions} */ export const actions = { logout: async (event) => { event.cookies.delete('sessionid', { path: '/' }); event.locals.user = null; } }; ``` ## Progressive Enhancement ### use:enhance The simplest way to enhance forms: ```svelte /// file: src/routes/login/+page.svelte
``` Without arguments, `use:enhance` will: - Update `form` and `page.form` (only for same-page actions) - Reset the form - Invalidate all data on success - Handle redirects and errors - Reset focus ### Customizing use:enhance ```svelte { // Pre-submission logic return async ({ result, update }) => { // Post-submission logic }; }} > ``` For custom handling: ```svelte { return async ({ result }) => { if (result.type === 'redirect') { goto(result.location); } else { await applyAction(result); } }; }} > ``` ### Custom Event Listener ```svelte
``` To target a page action instead of a server endpoint: ```js const response = await fetch(this.action, { method: 'POST', body: data, headers: { 'x-sveltekit-action': 'true' } }); ``` ## GET Forms For forms that don't need to POST data: ```html
``` This navigates to `/search?q=...` using client-side routing without invoking an action. ## docs/kit/20-core-concepts/40-page-options.md # Svelte 5 Page Options ## Core Concepts ### Rendering Modes SvelteKit supports three rendering strategies: - **Server-Side Rendering (SSR)**: Default, renders on server first - **Client-Side Rendering (CSR)**: Hydrates server-rendered HTML - **Prerendering**: Generates static HTML at build time Options can be set in `+page.js`, `+page.server.js`, `+layout.js`, or `+layout.server.js`. Child pages override parent layouts. ## Page Options ### prerender ```js // Static generation at build time export const prerender = true; // Force prerender export const prerender = false; // Prevent prerendering export const prerender = 'auto'; // Prerender but keep in SSR manifest ``` **Notes:** - Prerendering crawls your app starting from the root - Pages must render the same content for all users - Cannot use `url.searchParams` during prerendering - Pages with form actions cannot be prerendered - During prerendering, `building` from `$app/environment` is `true` #### Entries for Dynamic Routes ```js /// file: src/routes/blog/[slug]/+page.server.js /** @type {import('./$types').EntryGenerator} */ export function entries() { return [ { slug: 'hello-world' }, { slug: 'another-blog-post' } ]; } export const prerender = true; ``` #### Route Conflicts - Use file extensions for server routes (e.g., `foo.json/+server.js`) - Pages are written as `foo/index.html` instead of `foo` ### ssr ```js export const ssr = false; // Disable server-side rendering ``` Renders an empty shell page on the server. Useful for browser-only code but generally not recommended. ### csr ```js export const csr = false; // Disable client-side rendering ``` When disabled: - No JavaScript is sent to the client - ` ``` ```svelte

Welcome {user().name}

``` > Pass functions to `setContext` to maintain reactivity across boundaries. ## Component State Preservation SvelteKit reuses components during navigation. Make values reactive: ```svelte ``` Correct approach: ```svelte ``` To force component remounting on navigation: ```svelte {#key page.url.pathname} {/key} ``` ## State Storage Options - **URL Parameters**: For state that should survive reloads (filters, sorting) - Access via `url` in load functions or `page.url.searchParams` in components - **Snapshots**: For ephemeral UI state (accordion open/closed) - Persists during navigation but not page refresh ## docs/kit/25-build-and-deploy/10-building-your-app.md # SvelteKit App Building Guide ## Building Your App SvelteKit builds in two stages when running `vite build`: 1. Vite creates optimized production builds of server code, browser code, and service worker 2. An adapter tunes the build for your target environment ### During the Build Skip code execution during build phase: ```js import { building } from '$app/environment'; import { setupMyDatabase } from '$lib/server/database'; if (!building) { setupMyDatabase(); } export function load() { // ... } ``` ### Preview Your App Preview production build locally with `vite preview` (or `npm run preview`). Note: Preview runs in Node and doesn't perfectly reproduce deployment environment (adapter-specific features like `platform` object aren't available). ## docs/kit/25-build-and-deploy/20-adapters.md # Adapters Adapters convert your SvelteKit app for deployment to specific platforms. ## Official Adapters - `@sveltejs/adapter-cloudflare` - Cloudflare Workers/Pages - `@sveltejs/adapter-netlify` - Netlify - `@sveltejs/adapter-node` - Node servers - `@sveltejs/adapter-static` - Static site generation (SSG) - `@sveltejs/adapter-vercel` - Vercel [Community adapters](https://sveltesociety.dev/packages?category=sveltekit-adapters) are available for other platforms. ## Configuration Specify your adapter in `svelte.config.js`: ```js /// file: svelte.config.js import adapter from 'svelte-adapter-foo'; /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { adapter: adapter({ // adapter options go here }) } }; export default config; ``` ## Platform-specific Context Some adapters provide platform-specific information via the `platform` property in the `RequestEvent` object used in hooks and server routes. Refer to each adapter's documentation for details. ## docs/kit/25-build-and-deploy/55-single-page-apps.md # Single-page apps in SvelteKit ## Basic Setup Convert any SvelteKit app to a SPA by disabling SSR in the root layout: ```js /// file: src/routes/+layout.js export const ssr = false; ``` > **Note**: Not recommended for most cases due to SEO, performance, and accessibility issues. ## Using adapter-static For apps without server-side logic, use `adapter-static` with a fallback page: ```js /// file: svelte.config.js import adapter from '@sveltejs/adapter-static'; export default { kit: { adapter: adapter({ fallback: '200.html' // platform-specific }) } }; ``` The fallback page loads your app and navigates to the correct route. The filename varies by hosting platform. ## Apache Configuration For Apache, add a `static/.htaccess` file: ``` RewriteEngine On RewriteBase / RewriteRule ^200\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /200.html [L] ``` ## Selective Prerendering Enable prerendering for specific pages: ```js /// file: src/routes/my-prerendered-page/+page.js export const prerender = true; export const ssr = true; ``` ## docs/kit/30-advanced/10-advanced-routing.md # Advanced Routing in SvelteKit ## Rest Parameters Use rest syntax for unknown number of route segments: ```bash /[org]/[repo]/tree/[branch]/[...file] ``` For `/sveltejs/kit/tree/main/documentation/docs/04-advanced-routing.md`: ```js { org: 'sveltejs', repo: 'kit', branch: 'main', file: 'documentation/docs/04-advanced-routing.md' } ``` > Note: `src/routes/a/[...rest]/z/+page.svelte` matches `/a/z`, `/a/b/z`, etc. Always validate rest parameters. ### Custom 404 Pages For custom 404s with nested routes, create a catch-all route: ```js /// file: src/routes/marx-brothers/[...path]/+page.js import { error } from '@sveltejs/kit'; /** @type {import('./$types').PageLoad} */ export function load(event) { error(404, 'Not Found'); } ``` ## Optional Parameters Make parameters optional with double brackets: `[[lang]]/home` This matches both `/home` and `/en/home`. > Note: Optional parameters can't follow rest parameters. ## Matching Ensure parameters are well-formed with matchers: ```js /// file: src/params/fruit.js /** * @param {string} param * @return {param is ('apple' | 'orange')} * @satisfies {import('@sveltejs/kit').ParamMatcher} */ export function match(param) { return param === 'apple' || param === 'orange'; } ``` Use in routes: ``` src/routes/fruits/[page=fruit] ``` ## Sorting When multiple routes match a path, SvelteKit prioritizes: 1. More specific routes (fewer parameters) 2. Routes with matchers 3. Non-optional, non-rest parameters 4. Alphabetical order for ties ## Encoding Use hexadecimal escape sequences for special characters: - `[x+5c]` for `\` - `[x+2f]` for `/` - `[x+3a]` for `:` - etc. Example: `/smileys/:-)` → `src/routes/smileys/[x+3a]-[x+29]/+page.svelte` Unicode escapes also work: `src/routes/[u+d83e][u+dd2a]/+page.svelte` = `src/routes/🤪/+page.svelte` ## Advanced Layouts ### (group) Group routes without affecting URL paths: ```tree src/routes/ │ (app)/ │ ├ dashboard/ │ ├ item/ │ └ +layout.svelte │ (marketing)/ │ ├ about/ │ ├ testimonials/ │ └ +layout.svelte ├ admin/ └ +layout.svelte ``` ### Breaking Out of Layouts Use `@` to specify which layout to inherit: - `+page@[id].svelte` - inherits from segment's layout - `+page@item.svelte` - inherits from parent segment's layout - `+page@(app).svelte` - inherits from group layout - `+page@.svelte` - inherits from root layout Example: ```tree src/routes/ ├ (app)/ │ ├ item/ │ │ ├ [id]/ │ │ │ ├ embed/ │ │ │ │ └ +page@(app).svelte │ │ │ └ +layout.svelte │ │ └ +layout.svelte │ └ +layout.svelte └ +layout.svelte ``` Layouts can also break out with `+layout@.svelte`. Consider composition as an alternative to complex layout grouping: ```svelte {@render children()} ``` ## docs/kit/30-advanced/20-hooks.md # Svelte 5 and SvelteKit Hooks ## Server Hooks (`src/hooks.server.js`) ### handle Processes requests and determines responses. ```js export async function handle({ event, resolve }) { if (event.url.pathname.startsWith('/custom')) { return new Response('custom response'); } const response = await resolve(event); return response; } ``` `resolve` accepts optional parameters: - `transformPageChunk({ html, done })` - Transforms HTML chunks - `filterSerializedResponseHeaders(name, value)` - Controls which headers are included in serialized responses - `preload({ type, path })` - Determines which files to preload ### handleFetch Modifies fetch requests in server-side `load` or `action` functions. ```js export async function handleFetch({ request, fetch }) { if (request.url.startsWith('https://api.yourapp.com/')) { request = new Request( request.url.replace('https://api.yourapp.com/', 'http://localhost:9999/'), request ); } return fetch(request); } ``` ### locals Add custom data to the request via `event.locals`. ```js export async function handle({ event, resolve }) { event.locals.user = await getUserInformation(event.cookies.get('sessionid')); const response = await resolve(event); response.headers.set('x-custom-header', 'potato'); return response; } ``` ## Shared Hooks (both server and client) ### handleError Handles unexpected errors during loading or rendering. ```js export async function handleError({ error, event, status, message }) { const errorId = crypto.randomUUID(); // Log to service like Sentry Sentry.captureException(error, { extra: { event, errorId, status } }); return { message: 'Whoops!', errorId }; } ``` ### init Runs once when server is created or app starts in browser. ```js export async function init() { await db.connect(); } ``` ## Universal Hooks (`src/hooks.js`) ### reroute Changes how URLs translate to routes. ```js const translated = { '/en/about': '/en/about', '/de/ueber-uns': '/de/about', '/fr/a-propos': '/fr/about', }; export function reroute({ url }) { if (url.pathname in translated) { return translated[url.pathname]; } } ``` Can be async since v2.18: ```js export async function reroute({ url, fetch }) { if (url.pathname === '/api/reroute') return; const api = new URL('/api/reroute', url); api.searchParams.set('pathname', url.pathname); const result = await fetch(api).then(r => r.json()); return result.pathname; } ``` ### transport Passes custom types across server/client boundary. ```js export const transport = { Vector: { encode: (value) => value instanceof Vector && [value.x, value.y], decode: ([x, y]) => new Vector(x, y) } }; ``` ## docs/kit/30-advanced/25-errors.md # Svelte Errors ## Error Objects SvelteKit handles two types of errors: - Expected errors (created with `error` helper) - Unexpected errors (other exceptions) Both are represented as `{ message: string }` objects by default, but can be extended. ## Expected Errors ```js import { error } from '@sveltejs/kit'; import * as db from '$lib/server/database'; export async function load({ params }) { const post = await db.getPost(params.slug); if (!post) { error(404, { message: 'Not found' }); } return { post }; } ``` Access errors in components: ```svelte

{page.error.message}

``` Shorthand for simple errors: ```js error(404, 'Not found'); // Same as error(404, { message: 'Not found' }) ``` ## Unexpected Errors Unexpected errors are any other exceptions. For security, their details aren't exposed to users. Default error shape for users: ```json { "message": "Internal Error" } ``` Customize via the `handleError` hook. ## Error Responses Error handling depends on context: - In `handle` or `+server.js`: Returns fallback error page or JSON - In `load` functions: Renders nearest `+error.svelte` component - In root `+layout.js/+layout.server.js`: Uses fallback error page ### Custom Fallback Error Page Create `src/error.html`: ```html %sveltekit.error.message%

My custom error page

Status: %sveltekit.status%

Message: %sveltekit.error.message%

``` ## Type Safety Customize error types in TypeScript: ```ts declare global { namespace App { interface Error { code: string; id: string; } } } export {}; ``` ## docs/kit/30-advanced/30-link-options.md # SvelteKit Link Options ## Preloading Data Control when SvelteKit preloads data for links: ```html
%sveltekit.body%
Get current stonk values ``` - `"hover"`: Preload on mouse hover or touchstart - `"tap"`: Preload only on touchstart or mousedown Preloading is skipped when `navigator.connection.saveData` is true. ## Preloading Code Control when SvelteKit preloads code for links: ```html About ``` - `"eager"`: Preload immediately - `"viewport"`: Preload when link enters viewport - `"hover"`: Preload on hover - `"tap"`: Preload on tap/click Note: `viewport` and `eager` only apply to links present in DOM immediately after navigation. ## Other Link Behaviors ### Full-page reload ```html Path ``` Forces a full-page navigation. Links with `rel="external"` behave the same and are ignored during prerendering. ### Replace history state ```html Path ``` Uses `replaceState` instead of `pushState` to avoid creating a new history entry. ### Keep focus ```html
``` Maintains focus on the current element after navigation. Avoid using on links. ### Prevent scrolling ```html Path ``` Prevents automatic scrolling to top after navigation. ## Disabling Options Disable options for specific elements: ```html
a
d
``` Conditional application: ```svelte
``` ## docs/kit/30-advanced/40-service-workers.md # Service Workers in SvelteKit Service workers act as proxy servers for network requests, enabling offline support and faster navigation through precaching. ## Basic Setup SvelteKit automatically registers `src/service-worker.js` (or `src/service-worker/index.js`). ```js // Manual registration (if you disable automatic registration) if ('serviceWorker' in navigator) { addEventListener('load', function () { navigator.serviceWorker.register('./path/to/service-worker.js'); }); } ``` ## Inside the Service Worker Access the `$service-worker` module for paths to assets, build files, and prerendered pages. ```js /// import { build, files, version } from '$service-worker'; // Create a unique cache name for this deployment const CACHE = `cache-${version}`; const ASSETS = [ ...build, // the app itself ...files // everything in `static` ]; self.addEventListener('install', (event) => { // Create a new cache and add all files to it async function addFilesToCache() { const cache = await caches.open(CACHE); await cache.addAll(ASSETS); } event.waitUntil(addFilesToCache()); }); self.addEventListener('activate', (event) => { // Remove previous cached data from disk async function deleteOldCaches() { for (const key of await caches.keys()) { if (key !== CACHE) await caches.delete(key); } } event.waitUntil(deleteOldCaches()); }); self.addEventListener('fetch', (event) => { // ignore POST requests etc if (event.request.method !== 'GET') return; async function respond() { const url = new URL(event.request.url); const cache = await caches.open(CACHE); // `build`/`files` can always be served from the cache if (ASSETS.includes(url.pathname)) { const response = await cache.match(url.pathname); if (response) { return response; } } // for everything else, try the network first, but // fall back to the cache if we're offline try { const response = await fetch(event.request); // if we're offline, fetch can return a value that is not a Response // instead of throwing - and we can't pass this non-Response to respondWith if (!(response instanceof Response)) { throw new Error('invalid response from fetch'); } if (response.status === 200) { cache.put(event.request, response.clone()); } return response; } catch (err) { const response = await cache.match(event.request); if (response) { return response; } // if there's no cache, then just error out throw err; } } event.respondWith(respond()); }); ``` > Be careful with caching! Stale data may be worse than unavailable data. ## Development Mode Service workers are bundled for production only. For development, only browsers supporting modules in service workers will work. ```js import { dev } from '$app/environment'; navigator.serviceWorker.register('/service-worker.js', { type: dev ? 'module' : 'classic' }); ``` > `build` and `prerendered` are empty arrays during development ## Type Safety ```js /// /// /// /// const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self)); ``` ## Alternatives - [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html) for Workbox integration - [MDN Service Worker docs](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) ## docs/kit/30-advanced/50-server-only-modules.md # Server-only modules ## Private environment variables [`$env/static/private`]($env-static-private) and [`$env/dynamic/private`]($env-dynamic-private) can only be imported into server-side modules like `hooks.server.js` or `+page.server.js`. ## Server-only utilities [`$app/server`]($app-server) module with its [`read`]($app-server#read) function can only be imported by server code. ## Your modules Make your modules server-only by: - Adding `.server` to filename: `secrets.server.js` - Placing in `$lib/server`: `$lib/server/secrets.js` ## How it works SvelteKit prevents importing server-only code in public-facing components: ```js /// file: $lib/server/secrets.js export const atlantisCoordinates = [/* redacted */]; ``` ```js /// file: src/routes/utils.js export { atlantisCoordinates } from '$lib/server/secrets.js'; export const add = (a, b) => a + b; ``` ```html /// file: src/routes/+page.svelte ``` This produces an error showing the import chain: ``` Cannot import $lib/server/secrets.js into public-facing code: src/routes/+page.svelte src/routes/utils.js $lib/server/secrets.js ``` Works with dynamic imports too, with one caveat: during development, illegal imports may not be detected on first load if there are multiple dynamic imports in the chain. > [!NOTE] Import detection is disabled during testing when `process.env.TEST === 'true'`. ## docs/kit/30-advanced/65-snapshots.md # Snapshots Preserve ephemeral DOM state (form inputs, scroll positions) between navigations. ```svelte