Svelte

Svelte 5 runes + SvelteKit

Explicit, signal-based reactivity (runes) plus the SvelteKit data-loading contract: knowing where code runs and how load data reaches a page.

Two things break Svelte code more than anything else: treating $effect as the default for computed values, and confusing server-only load with universal load. This skill keeps you on the right side of both.

When to use

• Authoring or editing .svelte / .svelte.js / .svelte.ts files.
• Choosing $state vs $derived vs $effect; migrating Svelte 4 let / $: / export let to runes.
• Writing or reviewing +page.svelte, +page.ts, +page.server.ts, +layout*, +server.ts, +error.svelte, hooks.server.ts.
• load design (universal vs server), PageData typing, depends/invalidate, streaming promises, form actions with use:enhance.
• Remote functions (query/form/command/prerender in *.remote.ts).
• Adapter choice and SSR/CSR/prerender flags; hydration-mismatch debugging.

When NOT to use

• Next.js / React Server Components → ../nextjs/SKILL.md. Different reactivity model and data-loading contract. Never cross runes with RSC.
• Pure TypeScript typing (generics, mapped/conditional types) with no Svelte dimension → ../typescript/SKILL.md.
• Deploy-target specifics (env, edge, project config) → ../vercel/SKILL.md, ../netlify/SKILL.md, ../cloudflare/SKILL.md. This skill picks the adapter; those skills own the platform.
• React, Vue/Nuxt, Astro, SolidJS, Angular are not in this catalog yet — keep any framework comparison brief and inline; do not link them.

Current as of June 2026: Svelte 5.56.x, SvelteKit 2.61.x. Svelte 5 (runes) shipped Oct 2024.

First: detect Svelte 4 vs 5 — before you write a single rune

The #1 way to hand someone broken advice is to mix Svelte 4 reactivity ($:, export let) with runes in the same file. They are silently incompatible: a $: block in a runes component does nothing reactive. Detect the mode first.

1. Read package.json → dependencies/devDependencies svelte. ^5 (or 5.x) = runes era. ^4 = legacy.
2. Read svelte.config.js. compilerOptions.runes: true forces runes everywhere; absent = per-file auto-detect (a file is in runes mode iff it uses any rune).
3. Grep the target file: $state( / $props( / $derived( → runes mode. export let / $: / <slot → legacy.

Rule: never give $:/export let advice and $state/$props advice for the same component. If the codebase is Svelte 4 and the task is new work, migrate the file to runes first (see references/runes.md migration map) rather than appending runes onto legacy syntax.

Runes decision table

Pick the rune by what the value is, not by habit. Reading a rune registers a dependency; writing one schedules an update.

$effect is the escape hatch. If an effect's only job is to set state from other state, it's a $derived in disguise — and worse, writing $state inside an effect that also reads it can loop.

<!-- Bad: effect used to compute → extra render, can loop -->
<script>
  let count = $state(0);
  let doubled = $state(0);
  $effect(() => { doubled = count * 2; });
</script>

<!-- Good: derived value, no effect -->
<script>
  let count = $state(0);
  let doubled = $derived(count * 2);
</script>

Deep mutation is reactive on $state (it returns a proxy), so mutate in place — you don't need to reassign.

<script>
  let todos = $state([{ done: false }]);
  // Good: proxied, the push is tracked
  function add() { todos.push({ done: false }); }
  // Also fine: todos[0].done = true;
</script>

Props with defaults and renaming:

<script>
  // Good: default + rename a reserved-ish name + rest props
  let { title = 'Untitled', class: klass = '', ...rest } = $props();
</script>

Shared / global state across modules

Reactive shared state must live in a .svelte.js or .svelte.ts module (the .svelte part tells the compiler to process runes). A plain .js file cannot use runes.

The trap: you cannot export let count = $state(0) and reassign it elsewhere — importers get the value at import time, not the live cell, so it appears to "stop being reactive." Export a container whose identity is stable.

// counter.svelte.js
// Bad: importers bind the value, not the reactive cell
export let count = $state(0); // reassigning count elsewhere won't propagate

// Good: object identity is stable; .value stays reactive
export const counter = $state({ value: 0 });

// Good: getter/setter object
let _n = $state(0);
export const n = {
  get value() { return _n; },
  set value(v) { _n = v; },
};

// Good: a class instance (fields are reactive)
export class Counter {
  value = $state(0);
  increment() { this.value += 1; }
}

Classic writable/readable/derived stores from svelte/store are still valid and still work — prefer them when you need the $store auto-subscription sugar in templates or are integrating Svelte 4 code. For new runes-first code, the module patterns above are simpler. Depth in references/runes.md.

SvelteKit file map — what runs where