SvelteKit 2

SvelteKit 2

Project targets SvelteKit 2 + Svelte 5. Most LLM mistakes here are SvelteKit 1 patterns. Read references/breaking-changes.md first before writing or reviewing any SvelteKit code — half the bugs are in that one file.

Quick map

If you need to …	Read
Anything (mandatory first read for SK code)	references/breaking-changes.md
Add or modify a route, layout, matcher, route group	references/routing.md
Write a load function, use parent/depends/invalidate, stream data, guard auth	references/load.md
Write or enhance form actions, handle file uploads	references/forms.md
Add hooks.server.ts, hooks.client.ts, type App.Locals, handle errors	references/hooks.md
Use environment variables, server-only modules ($lib/server)	references/env.md

File map (src/routes/<path>/)

File	Purpose
+page.svelte	Page UI
+page.ts	Universal load (SSR + browser)
+page.server.ts	Server-only load + form actions
+layout.svelte	Layout wrapping children — uses {@render children()}
+layout.ts / +layout.server.ts	Shared load for children
+server.ts	REST endpoint (GET/POST/PUT/DELETE/PATCH/OPTIONS/fallback) returning Response
+error.svelte	Local error boundary (walks up tree to find one)

Underscore-prefix folders/files (_components/, _utils.ts) are private — not routes.

Top traps (LLMs get these wrong constantly)

1. error() and redirect() are called as statements, not thrown. error(404, 'x'), NOT throw error(404, 'x'). Don't wrap in try/catch — redirect() will fall into the catch.
2. cookies.set / cookies.delete require { path: '/' } — throws otherwise.
3. <slot /> is gone in +layout.svelte → let { children } = $props() + {@render children()}.
4. $app/stores is deprecated → $app/state. No $ prefix: page.url.pathname, not $page.url.pathname.
5. Top-level promises in load are streamed, not auto-awaited. Use await to block render; leave bare to stream.
6. goto() does NOT accept external URLs → use window.location.href = ....
7. File inputs require enctype="multipart/form-data" — throws at submission otherwise.
8. use:enhance only works on +page.server.ts actions, not on +server.ts endpoints, not on GET forms.
9. Auth in +layout.server.ts is wrong — layouts don't always rerun on navigation. Use hooks.server.ts to populate locals, then guard per-route.
10. Don't throw an error() from a streamed promise — headers are already flushed; the page partially renders, then explodes.

Workflow

1. Identify the layer: page UI, server load, action, REST endpoint, layout, hook.
2. Always read breaking-changes.md first — it's short and catches most bugs.
3. Read the matching topic reference.
4. Mirror an existing route's conventions (TS/JS, validation library, auth pattern).
5. Always import types from ./$types — never hand-roll PageLoad/Actions.
6. After writing, scan for the 10 traps above.