hirogakatageri/svelte-build-deploy

SvelteKit — Build & Deploy

Authoritative reference for working in SvelteKit projects: project layout, routing, data loading, mutations, and getting an app to production.

Project Structure

my-app/
├─ src/
│  ├─ lib/                   # $lib alias — shared modules
│  │  └─ server/             # $lib/server — server-only code
│  ├─ params/                # custom param matchers
│  ├─ routes/                # filesystem routes (root)
│  ├─ app.html               # HTML shell
│  ├─ error.html             # static fallback error page
│  ├─ hooks.server.ts        # server hooks
│  ├─ hooks.client.ts        # client hooks
│  └─ hooks.ts               # shared (universal) hooks
├─ static/                   # served verbatim at /
├─ tests/
├─ svelte.config.js          # Kit + adapter config
├─ vite.config.ts
├─ tsconfig.json
└─ package.json

Key path aliases:

• $lib → src/lib
• $lib/server/* → server-only; importing from client code is a build error
• $app/* → SvelteKit runtime modules
• $env/static/private, $env/static/public, $env/dynamic/* → environment variables

File-based Routing

Inside src/routes/, each directory is a URL segment. Files prefixed with + are route files:

| File | Role | |------|------| | +page.svelte | Page UI | | +page.ts | Universal load (runs server + client) | | +page.server.ts | Server load and form actions | | +layout.svelte | Wraps child pages; renders {@render children()} | | +layout.ts / +layout.server.ts | Layout-level load | | +error.svelte | Error boundary | | +server.ts | API endpoint (HTTP method exports) |

Dynamic segments use brackets:

• [slug] — required parameter
• [[slug]] — optional parameter
• [...rest] — catch-all
• [id=int] — parameter matcher (custom validator in src/params/int.ts)

Rule of thumb:

• All files run on the server. All run on the client too, except +server.ts.
• +layout and +error apply to their directory and all subdirectories.

+page.svelte

<script lang="ts">
  import type { PageProps } from './$types';
  let { data, form }: PageProps = $props();
</script>

<h1>{data.title}</h1>

PageProps (since 2.16) packages data, form, and route params into one type. Use it instead of typing fields individually.

+layout.svelte

<script lang="ts">
  import type { LayoutProps } from './$types';
  let { data, children }: LayoutProps = $props();
</script>

<nav>...</nav>
{@render children()}

The layout MUST render children somewhere, or pages won't appear.

+error.svelte

<script>
  import { page } from '$app/state';
</script>

<h1>{page.status}</h1>
<p>{page.error?.message}</p>

SvelteKit walks up the tree to find the closest +error.svelte. Errors thrown from the root layout's load are caught by the static src/error.html fallback.

+server.ts (API endpoints)

import { json, error } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = ({ url }) => {
  return json({ now: Date.now() });
};

export const POST: RequestHandler = async ({ request }) => {
  const body = await request.json();
  return json({ received: body });
};

// catch-all for unhandled methods
export const fallback: RequestHandler = ({ request }) =>
  new Response(`No handler for ${request.method}`, { status: 405 });

+server.ts files are NOT wrapped by +layout files. To run logic before every request, use hooks.server.ts.

load Functions

Two flavors:

| File | Type | Runs on | |------|------|---------| | +page.ts, +layout.ts | Universal | Server (SSR + during prerender) AND client (after hydration) | | +page.server.ts, +layout.server.ts | Server-only | Server only — return value is serialized to the client |

// +page.server.ts
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';
import type { PageServerLoad } from './$types';

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

When to use which:

• Server load when you need a database, private env vars, secrets, or cookies / locals access.
• Universal load when fetching from public APIs (avoids the proxy hop), or when you must return non-serializable values (component constructors, classes).
• Both can coexist on the same route — the server load runs first; its result is the universal load's event.data.

Important load traits:

• Server returns must be devalue-serializable (JSON + BigInt, Date, Map, Set, RegExp, repeated/cyclical refs).
• fetch provided in the load event — use it instead of global fetch. It inherits cookies, supports relative URLs server-side, short-circuits internal +server.ts calls, and inlines responses into the SSR HTML to avoid double-fetches on hydration.
• Promises in the return are streamed to the browser on platforms that support streaming. Always attach a .catch(() => {}) to lazily-resolving promises so an unhandled rejection doesn't crash the server.
• await parent() lets a child load read its parent layout's data — but call it after anything independent to avoid waterfalls.
• Auth checks belong in hooks.server.ts (sets locals.user) and per-page +page.server.ts guards. Avoid relying on layout loads for auth, because layouts don't always rerun on client navigation.

Re-running: SvelteKit re-runs a load when:

• A params field it accessed changed
• A url property it accessed changed
• A searchParams key it accessed changed
• A parent it await parent()-ed re-ran
• A url it fetched or depends()-ed on was passed to invalidate(url)
• invalidateAll() was called

depends('app:custom-key') lets you create your own invalidation tokens.

Errors and Redirects

import { error, redirect } from '@sveltejs/kit';

throw_unused; // ❌ NOT needed in v2 — calling error()/redirect() throws
error(404, 'not found');
redirect(303, '/login');

In SvelteKit 2, error() and redirect() throw on your behalf — don't throw error(...). Don't call them inside a try { } catch { } block — the catch will swallow the redirect/error.

getRequestEvent

Inside server code, import { getRequestEvent } from '$app/server' lets shared helpers (auth guards, logging) reach the current request without prop-drilling the event.

Form Actions

Server-side mutations triggered by <form> submissions. Defined in +page.server.ts:

// +page.server.ts
import { fail, redirect } from '@sveltejs/kit';
import type { Actions, PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals }) => ({
  user: locals.user
});

export const actions: Actions = {
  default: async ({ request, cookies }) => {
    const data = await request.formData();
    const email = String(data.get('email') ?? '');
    if (!email) return fail(400, { email, missing: true });

    cookies.set('session', await login(email), { path: '/' });
    redirect(303, '/dashboard');
  },

  logout: async ({ cookies }) => {
    cookies.delete('session', { path: '/' });
    redirect(303, '/');
  }
};

<!-- +page.svelte -->
<script lang="ts">
  import type { PageProps } from './$types';
  import { enhance } from '$app/forms';
  let { form }: PageProps = $props();
</script>

<form method="POST" use:enhance>
  <input name="email" value={form?.email ?? ''} />
  {#if form?.missing}<p>Email required</p>{/if}
  <button>Sign in</button>
</form>

<form method="POST" action="?/logout" use:enhance>
  <button>Log out</button>
</form>

• Use fail(status, data) for validation errors — keeps user input around as form prop.
• redirect(303, ...) after a successful POST follows PRG.
• use:enhance upgrades to fetch+JS but degrades gracefully without it.
• Named actions invoked via action="?/name".

For type-safe RPC-style mutations, also see remote functions in svelte-advanced.

Page Options

Exported from +page.ts, +page.server.ts, +layout.ts, or +layout.server.ts:

export const prerender = true;       // build-time HTML, served as static
export const ssr = false;             // disable server rendering (SPA)
export const csr = false;             // disable client hydration (no JS)
export const trailingSlash = 'never'; // 'never' | 'always' | 'ignore'
export const config = { /* adapter-specific */ };

• prerender = true requires the page's data to be deterministic. For dynamic routes, also export an entries() from +page.server.ts listing the params to pre-render.
• prerender = 'auto' prerenders if possible, falls back to SSR otherwise.
• ssr = false + prerender = false produces a true SPA (page only renders on the client).
• csr = false ships zero JS for that page — useful for static content pages.

Hooks

Three files in src/:

• hooks.server.ts — server lifecycle: handle, handleError, handleFetch, init
• hooks.client.ts — client lifecycle: handleError, init
• hooks.ts — universal transport (custom de/serialization for non-default types)

// hooks.server.ts
import type { Handle } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  const session = event.cookies.get('session');
  event.locals.user = session ? await getUser(session) : null;

  const response = await resolve(event);
  response.headers.set('x-frame-options', 'DENY');
  return response;
};

Multiple handles compose with sequence from @sveltejs/kit/hooks.

Building for Production

npm run build       # → vite build
npm run preview     # local preview of the production build

Build output goes to .svelte-kit/output (universal) and the adapter writes the deployment artifact.

Adapters

Configured in svelte.config.js:

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

export default {
  preprocess: vitePreprocess(),
  kit: { adapter: adapter() }
};

| Adapter | Use when | |---------|----------| | @sveltejs/adapter-auto | Default; detects Vercel / Netlify / Cloudflare Pages from env. Fine for prototyping; pin a specific adapter for production. | | @sveltejs/adapter-node | Self-hosted Node.js server (Docker, VPS). Outputs build/index.js runnable with node build. | | @sveltejs/adapter-static | Pure static site (SSG). Requires every route to be prerenderable; set fallback for SPA mode. | | @sveltejs/adapter-vercel | Vercel — supports edge functions, ISR, image optimization. | | @sveltejs/adapter-cloudflare | Cloudflare Pages / Workers — edge runtime, KV / D1 via platform.env. | | @sveltejs/adapter-netlify | Netlify — supports functions and edge functions. |

adapter-node

Outputs a standalone Node app:

import adapter from '@sveltejs/adapter-node';
export default { kit: { adapter: adapter({ out: 'build' }) } };

Run with node build. Configurable env vars: PORT, HOST, ORIGIN, BODY_SIZE_LIMIT. Behind a reverse proxy, set ORIGIN to the public URL so SvelteKit knows the canonical host.

adapter-static

Pure static output:

import adapter from '@sveltejs/adapter-static';
export default {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: undefined,   // 'index.html' or '200.html' for SPA mode
      precompress: false
    })
  }
};

Every page must have prerender = true (or be reachable via prerendering). For SPA mode, set fallback: '200.html' and ssr = false at the root layout.

Cloudflare / Vercel / Netlify

Each platform-specific adapter wires up the platform's serverless or edge runtime. For Cloudflare, server event.platform.env exposes bindings (KV, D1, R2). For Vercel, export const config = { runtime: 'edge' } opts a route into the edge runtime. For Netlify, edge functions are similar via the edge: true option.

Environment Variables

Four imports — pick the right one:

| Module | Static (build-time) / Dynamic | Public / Private | |--------|-------------------------------|------------------| | $env/static/private | static | private (server only) | | $env/static/public | static | public (must start with PUBLIC_) | | $env/dynamic/private | dynamic (per-request) | private | | $env/dynamic/public | dynamic | public |

Static imports inline values at build time and tree-shake unused ones. Dynamic imports read from process.env (or platform equivalent) at runtime — required when the same build runs in multiple environments.

app.html

Edit src/app.html to customize the HTML shell. Required placeholders:

<!DOCTYPE html>
<html lang="en">
  <head>
    %sveltekit.head%
  </head>
  <body data-sveltekit-preload-data="hover">
    <div style="display: contents">%sveltekit.body%</div>
  </body>
</html>

data-sveltekit-preload-data and data-sveltekit-preload-code attributes on <a> or any ancestor enable preloading.

Common Mistakes

1. Importing $lib/server/* from a client component → build error. Move shared helpers out of $lib/server.
2. Calling redirect() inside a try/catch → catch swallows the redirect.
3. throw error(...) (SvelteKit 1 syntax) → in v2, just error(...) — it throws itself.
4. Using global fetch in a load → use the fetch from the load event for cookie-forwarding and SSR caching.
5. Mixing prerender and dynamic data → if prerender = true, the route's load must be deterministic at build time.
6. Forgetting entries() for prerendered dynamic routes → SvelteKit can't know the param values without it.
7. Calling invalidateAll() constantly → it re-runs every load. Prefer invalidate(url) or depends() tokens.
8. Auth checks in layout loads only → layouts don't always rerun on client nav. Pair with hooks or per-page guards.