Svelte

Builds, debugs, and reviews Svelte and SvelteKit apps: runes, stores, snippets, load functions, form actions, adapters. Use when the UI does not update after a state change, an effect loops forever ("effect_update_depth_exceeded"), props or bindings stop reacting, a Map or class field is not tracked, state leaks between users on the server, "window is not defined" breaks the build, markup mismatches on hydration, data stays stale after a mutation, a form action does nothing or returns 403, scoped CSS is pruned as an unused selector, transitions never fire, or a Node, Vercel, Cloudflare, or static adapter build fails. Also for migrating Svelte 4 to Svelte 5 runes, converting export let to $props, $: to $derived, createEventDispatcher to callback props, slots to snippets and on:click to onclick, typing props and route data in TypeScript, testing components with Vitest or Playwright, and cutting bundle size and rerender cost. Not for Vue or Nuxt, React, or plain browser JavaScript semantics.

User preferences and memory live in ~/Clawic/data/svelte/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/svelte/ or ~/clawic/svelte/), move it to ~/Clawic/data/svelte/.

When To Use

• Writing or reviewing Svelte components, .svelte.js state modules, or SvelteKit routes
• Reactivity failures: UI not updating, effect loops, bindings that stop propagating, stale derived values
• SvelteKit request-layer work: load functions, invalidation, form actions, hooks, +server.js endpoints
• Server-only failures: hydration mismatch, window is not defined, state shared between requests, adapter build errors
• Migrating a Svelte 4 codebase to Svelte 5 runes, or maintaining a mixed legacy/runes codebase
• Not for Vue or Nuxt (vue, nuxt), React (react), or language-level JavaScript semantics (javascript)

Quick Reference

Situation	Play
UI does not update after a change	Is the variable $state? Destructured? A Map/Set/class instance? → Reactivity Model table, then debug.md
effect_update_depth_exceeded	An effect writes state it also reads — convert to $derived, or untrack() the read (rule 2)
Value computed from other state	$derived / $derived.by; never $effect + assignment (rule 2)
Deep dive on $state, $derived, $effect, $props	runes.md
Shared state across files, context, legacy stores	stores.md
Snippets, bindings, callback props, attachments, wrapping an imperative library	components.md
Scoped CSS not applying, unused-selector warning, transitions, motion	styling.md
Typing props, snippets, route data, app.d.ts	typescript.md
Symptom-first debugging and the error-code catalog	debug.md
Svelte 4 → 5: export let, $:, slots, on:click, new Component()	migration.md
Routes, layouts, groups, param matchers, navigation, shallow routing	routing.md
load, invalidate, streaming, depends, serialization	data-loading.md
Form actions, use:enhance, validation, uploads, remote functions	forms.md
window is not defined, hydration mismatch, per-request state, env vars	ssr.md
Login, sessions, cookies, route guards, roles, CSRF, XSS, CSP, leaked secrets	security.md
Bundle size, slow lists, rerender cost, preloading	performance.md
Vitest, component tests, mocking $app/*, Playwright, svelte-check	testing.md
Adapters, prerendering, CSP, service workers, self-hosting	deployment.md
Packaging components for npm, custom elements, library API design	library.md
Anything else	Apply Core Rules; reproduce in a single component with no props before blaming the framework

Core Rules

1. Reactivity comes from $state, not from assignment. In runes mode a bare let count = 0 never re-renders no matter how you assign it — the compiler emits non_reactive_update. let count = $state(0) then count++ or obj.items.push(x) both work: $state on a plain object or array is a deep proxy.
2. $derived for values, $effect for the outside world. Decision rule: if the new value is a pure function of other state → $derived; if it touches the DOM, network, storage, or a non-Svelte library → $effect. An effect that assigns state costs an extra render pass and is the direct cause of effect_update_depth_exceeded.
3. Effects track only synchronous reads. Dependencies are collected while the effect body runs to its first await; anything read after an await, in a setTimeout, or in a .then() is invisible to the tracker and the effect will not rerun. Read your dependencies at the top, then await.
4. Module-level state on the server belongs to every user at once. A let user = $state(null) exported from a .svelte.js module is one value per Node process, not per request — request A writes it, request B renders it. Per-request data goes in event.locals (server) and setContext/props (components).
5. Key every {#each} whose items can move. {#each rows as row (row.id)}. Unkeyed, Svelte maps DOM to array index: delete row 0 and the input, focus, and component state of index 0 stay attached to what is now a different row. This is a correctness bug, not an optimization.
6. Secrets and the database live behind +page.server.js. Universal +page.js runs in the browser too, so anything it imports ships. Server load output crosses the wire through devalue serialization: Date, Map, Set, BigInt, and cycles survive; class instances and functions do not (register them with the transport hook).
7. A load function reruns only for what it read. Rerun happens when: a params or url property it accessed changes, OR an invalidate(key) matches something it depends() on or a URL it fetched, OR a parent it await parent()-ed reran, OR invalidateAll() fired. After any mutation outside use:enhance, call invalidateAll() yourself or the page keeps serving the old data.
8. Mutations go through form actions, not fetch handlers. <form method="POST" action="?/save"> works with JavaScript disabled and on the first paint; use:enhance upgrades the same form to a fetch with no reload and reinvalidates data on success. Reach for a +server.js endpoint only for non-form clients: webhooks, third parties, file streaming.
9. Guard browser APIs by phase, not by try/catch. $effect and onMount never run during SSR — that is the guard. Module scope and load functions run on the server, so window, document, localStorage, and IntersectionObserver there need import { browser } from '$app/environment' or a dynamic import().

Reactivity Model

What is tracked, and what silently is not:

Declaration	Reactive on	Rule
let x = $state(0)	reassignment	Primitives: assign to update
let o = $state({a: {b: 1}})	reassignment + deep mutation	Plain objects/arrays become recursive proxies; o.a.b = 2 and arr.push() both work
$state.raw(bigList)	reassignment only	No proxy: cheaper for large data you replace wholesale
new Map(), Set, Date, URL inside $state	nothing	Not proxied — use SvelteMap, SvelteSet, SvelteDate, SvelteURL from svelte/reactivity
Class field count = $state(0)	reassignment	Methods and get accessors stay reactive; the instance itself is not a proxy
let { a, b = 1 } = $props()	parent updates	Destructuring props IS reactive in runes mode — the compiler rewrites the reads
const { a } = someStateObject	nothing	Destructuring state reads the value once; keep the object, or wrap in $derived
Exported let x = $state(0) from a module	not across the import	Importers get a snapshot binding — export an object, a class instance, or a getter
let x = 0 in a runes file	nothing	Compiler warning non_reactive_update

Passing state to a non-Svelte library (structuredClone, IndexedDB, postMessage, charting libs) hands it a Proxy; send $state.snapshot(x) instead.

Version Gates

• svelte >=5 — runes, snippets, onclick event attributes, mount()/unmount(); $:, export let, slots, and new Component() only work in legacy mode
• svelte >=5.3 — <svelte:boundary> with failed snippet and onerror
• svelte >=5.29 — attachments ({@attach fn}) supersede actions (use:fn); actions still work
• svelte >=5.36 — experimental await inside components and $effect.pending(), behind the experimental.async compiler option
• @sveltejs/kit >=2 — error() and redirect() throw internally: call them, never throw them; cookies.set requires an explicit path
• @sveltejs/kit >=2.12 — $app/state (page, navigating, updated) replaces the $app/stores subscriptions; page.url, not $page.url
• @sveltejs/kit >=2.16 — PageProps and LayoutProps in ./$types; below it, type $props() with { data: PageData; form: ActionData }
• @sveltejs/kit >=2.27 — remote functions (query, form, command) in .remote.js, behind experimental.remoteFunctions

Where Code Runs

File	Runs	Can hold secrets	Shipped to browser
+page.svelte, +layout.svelte	SSR render, then client	No	Yes
+page.js (universal load)	Server on first load, client on navigation	No	Yes
+page.server.js (server load, actions)	Server only	Yes	No
+server.js (endpoint)	Server only	Yes	No
hooks.server.js	Server, every request	Yes	No
hooks.client.js	Browser only	No	Yes
$lib/server/**, *.server.js	Server only	Yes	Import from client code = build error

Order per request: handle hook → server loads (+layout.server.js, then +page.server.js) → universal loads → render. Loads at the same level run in parallel unless one calls await parent(), which serializes it behind the parent.

Error Codes

Code or message	Meaning	First move
state_unsafe_mutation	State written while a derived or the template was computing it	Move the write into an event handler or $effect
effect_update_depth_exceeded	An effect writes state that it (or a chained effect) reads	Convert to $derived; if the read is genuinely one-way, wrap it in untrack()
hydration_mismatch	Server HTML differs from the first client render	Remove Date.now()/Math.random()/window from render; check invalid nesting (<div> inside <p>)
rune_outside_svelte	A rune used in a .js/.ts file	Rename the file to .svelte.js / .svelte.ts
lifecycle_outside_component	onMount, setContext, or getContext called after an await or inside a callback	Call synchronously during component initialization
derived_references_self	A $derived reads its own value	Compute from source state, or keep the accumulator in $state
each_key_duplicate	Two items produced the same key	Key by a unique id; never by index or by a repeated value
bind_invalid_export / binding error	bind: to a prop the child did not declare bindable	let { value = $bindable() } = $props()
ownership_invalid_mutation (dev warning)	A child mutated an object owned by its parent	$bindable() or a callback prop
css_unused_selector (warning)	Selector matches nothing in this component's own markup	:global(...), or move the rule into the child component
403 on a form POST	Kit's CSRF origin check rejected a cross-origin submission	Submit same-origin, or set csrf.checkOrigin deliberately
Cannot import $lib/server/... into client-side code	A server-only module reached a client bundle	Import it in +page.server.js and pass the result through load

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/svelte/config.yaml.

Variable	Type	Default	Effect
syntax_mode	runes | legacy | mixed	runes	Selects the syntax of every generated component ($state/$props vs let/export let) and whether migration advice is offered at all
kit_project	bool	true	When false, drops routing, load, actions, and adapter guidance and treats the app as Svelte + Vite with client-side routing
deployment_adapter	auto | node | static | vercel | cloudflare | netlify	auto	Drives the deploy checklist, which env-var mechanism is valid, and whether prerender/SPA fallback is required
package_manager	npm | pnpm | yarn | bun	npm	Sets the command syntax in install, sv add, build, and test instructions
styling	scoped-css | tailwind | unocss | css-modules	scoped-css	Shapes generated markup and which scoped-CSS caveats apply
typescript	bool	true	Emits <script lang="ts">, typed $props(), and ./$types imports; false switches to JSDoc annotations
experimental_features	bool	false	When false, remote functions, experimental.async/$effect.pending(), and attachments-over-actions are mentioned as available but never the recommended form; when true they are written by default
check_threshold	error | warning	error	The svelte-check --threshold value in every CI recipe, and whether a warning-level finding blocks the work

Preference areas to record as the user reveals them:

• conventions — component and route file naming, folder layout, $lib structure, barrel files
• stack — form validation library, ORM or data client, auth approach, i18n, component library
• progressive enhancement — whether the app must work with JavaScript disabled; decides form-action vs client-fetch mutations
• accessibility posture — treat compiler a11y warnings as errors, or advisory
• testing strategy — component tests in browser mode vs jsdom, and the unit/e2e split
• risk posture — appetite for experimental and just-released APIs beyond experimental_features, upgrade cadence, and whether to propose a migration on a codebase that currently works
• budgets — bundle-size and first-load targets, coverage floor, and any perf number the project gates on beyond check_threshold
• output format — explanation depth (fix only vs walkthrough), full files vs diffs, comment density in generated code
• proactivity — how eagerly to flag reactivity, boundary, and bundle issues versus answering only what was asked

Output Gates

Before emitting a component or route, verify:

• Every mutable value declared with $state; no bare let expected to rerender?
• Every computed value a $derived, with $effect reserved for DOM, network, storage, or third-party libraries?
• Every {#each} over reorderable data keyed by a stable id?
• No secret, database client, or $env/static/private import reachable from +page.svelte or +page.js?
• Mutations expressed as a form action that still works with JavaScript disabled?
• Browser APIs only inside $effect/onMount or behind a browser check?
• Per-request data in event.locals or context — never a module-level variable?
• One syntax mode per file: no export let or $: in a file that uses runes?

Traps

Trap	Why it fails	Do instead
$effect used to compute derived state	Extra render pass and a loop the moment the effect reads what it writes	$derived / $derived.by
Destructuring a $state object, then mutating the copy	The destructured constants captured values, not the proxy	Keep the object and read o.a; $derived for a stable view
let count = $state(0) exported from a .svelte.js module	Importers bind to the value at import time	Export a class instance or { get count() {...} }
Per-user data in a server module variable	One value per process, shared by all concurrent requests	event.locals in hooks, setContext in components
throw redirect(...) / throw error(...) inside a try	Kit 2 helpers throw internally; your catch swallows the control flow	Call them after the try/catch block
Fetching your own +server.js from a server load	An extra HTTP hop, lost types, cookie forwarding you now own	Call the function or database directly in server load
{@html userInput}	XSS, and component-scoped styles do not apply to injected markup	Sanitize server-side; style with :global
Passing $state straight to a chart or map library	The library receives a Proxy and its identity checks fail	$state.snapshot(value)
await early in an $effect, then reading state	Reads after the await are untracked; the effect never reruns	Read every dependency synchronously first
on:click or createEventDispatcher in a runes component	Legacy syntax; the runes compiler rejects or deprecates it	onclick={...} and callback props
<svelte:component this={C}> in runes mode	Deprecated: components are already dynamic values	Capitalized variable: <C />
bind:value to a prop the child never declared bindable	Bindings are opt-in in runes mode	let { value = $bindable() } = $props()
document or window at module scope	Module bodies execute during SSR	Move into $effect/onMount, or guard with browser
Unkeyed {#each} around inputs or stateful children	DOM nodes are reused by index	Key by id (rule 5)

Where Experts Disagree

• Runes vs stores for shared state. Default: a class or object with $state fields in a .svelte.js module — plain values, no $ prefix, works outside components. Stores remain the right shape for push-based external sources (sockets, geolocation, third-party subscriptions) and for anything consuming the subscribe contract; fromStore/toStore bridge the two rather than forcing a rewrite.
• How much $effect is acceptable. The framework position is that effects are a last resort for synchronizing with systems outside Svelte; the pragmatic position accepts effects for analytics, logging, and persistence. Both agree on the hard line: an effect that assigns state which feeds back into its own dependencies is a bug, not a style choice.
• SSR by default vs SPA. Prerendering or SSR wins for public, indexable, first-paint-sensitive pages. adapter-static with ssr = false is a legitimate choice for an internal dashboard behind auth where every view needs the client anyway — the deciding factors are SEO, first paint, and no-JS support, not fashion.
• Validation libraries in form actions. Hand-rolled checks are fine for one to three fields. Once you need repopulating on failure, nested data, arrays, or multi-step wizards, a schema library plus a form helper stops the per-field boilerplate from drifting out of sync with the server.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/svelte (install if the user confirms):

• typescript — type-system depth beyond the Svelte-specific typings
• vite — dev server, plugins, and build configuration under SvelteKit
• playwright — end-to-end testing of the running app
• tailwindcss — utility styling inside Svelte components
• nodejs — running and hardening the adapter-node server

Feedback

• If useful, star it: https://clawic.com/skills/svelte
• Latest version: https://clawic.com/skills/svelte

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/svelte.