Svelte

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

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. `` 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:

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 — `` 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

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

Configuration

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

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

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.