svelte-core

Svelte 5 — Core Knowledge

Authoritative reference for writing modern Svelte 5 components and reactive modules. Read this in full before touching any .svelte / .svelte.ts / .svelte.js file.

File Types

• .svelte — a component. Has <script>, markup, and <style> blocks.
• .svelte.ts / .svelte.js — a reactive module. The compiler transforms runes here too. Use these for shared reactive state and reusable reactive logic.
• .ts / .js — plain modules. Runes are NOT transformed here. Don't use $state etc. in plain .ts files; rename to .svelte.ts if you need reactivity.

Component Anatomy

<script lang="ts">
  // imports, props, state, derived, effects, functions
  let { name = 'world' }: { name?: string } = $props();
  let count = $state(0);
  let doubled = $derived(count * 2);
</script>

<h1>Hello {name}</h1>
<button onclick={() => count++}>{doubled}</button>

<style>
  h1 { color: tomato; }
</style>

A component is its file. Each .svelte file exports one component as the default export. To export named values, use <script module>:

<script module lang="ts">
  export const VERSION = '1.0';
</script>
<script lang="ts">
  // instance script
</script>

<script module> runs once when the module is first evaluated. The instance <script> runs per component instance.

Runes

Runes are compiler primitives. They look like functions but are syntax — don't import them. Always use parentheses ($state(0), not $state 0).

$state

Creates reactive state.

<script>
  let count = $state(0);
  let todos = $state([{ done: false, text: 'add more todos' }]);
</script>

• Objects and arrays are made into deeply-reactive proxies. Mutating nested properties (todos[0].done = true) and array methods (push, splice) trigger updates.
• Class instances are NOT proxied. Use $state on class fields instead:

  class Todo {
    done = $state(false);
    text = $state('');
  }
  

• Destructuring loses reactivity: let { done } = todos[0] captures the value at that moment.
• $state.raw(value) — non-reactive container. Mutations are ignored; only reassignment triggers updates. Use for large arrays/objects you replace wholesale.
• $state.snapshot(proxy) — returns a plain (non-proxy) deep clone. Use when passing state to libraries that don't expect proxies (structuredClone, JSON.stringify works without it but some APIs choke).