1
# Runes System
2

3
Svelte 5 introduces runes - a powerful reactivity system that replaces the previous assignment-based reactivity. Runes provide explicit, fine-grained reactivity with better TypeScript support and more predictable behavior.
4

5
## Capabilities
6

7
### $state
8

9
Declares reactive state that triggers updates when changed.
10

11
```typescript { .api }
12
/**
13
 * Declares reactive state
14
 * @param initial - Initial value for the state
15
 * @returns Reactive state value
16
 */
17
declare function $state<T>(initial: T): T;
18
declare function $state<T>(): T | undefined;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
// Basic state
25
let count = $state(0);
26
let name = $state("Alice");
27
let items = $state([]);
28

29
// State without initial value
30
let user = $state(); // undefined initially
31

32
// Object state (deeply reactive by default)
33
let settings = $state({
34
  theme: "dark",
35
  language: "en",
36
  notifications: {
37
    email: true,
38
    push: false
39
  }
40
});
41

42
// Updating state triggers reactivity
43
count += 1; // This will trigger updates
44
settings.theme = "light"; // This will trigger updates
45
settings.notifications.email = false; // Deep updates work too
46
```
47

48
### $state.raw
49

50
Declares state that is not deeply reactive - you must reassign the entire value to trigger updates.
51

52
```typescript { .api }
53
/**
54
 * Declares state that is not made deeply reactive
55
 * @param initial - Initial value for the raw state
56
 * @returns Non-deeply reactive state value
57
 */
58
declare function raw<T>(initial: T): T;
59
declare function raw<T>(): T | undefined;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
let items = $state.raw([{ id: 1, name: "Item 1" }]);
66

67
// This won't trigger updates
68
items[0].name = "Updated Item";
69

70
// This will trigger updates
71
items = [...items, { id: 2, name: "Item 2" }];
72
items = items.map(item => 
73
  item.id === 1 ? { ...item, name: "Updated Item" } : item
74
);
75
```
76

77
### $state.snapshot
78

79
Takes a static snapshot of deeply reactive state, useful for logging or serialization.
80

81
```typescript { .api }
82
/**
83
 * Takes a static snapshot of a deeply reactive state proxy
84
 * @param state - The state to snapshot
85
 * @returns Static snapshot of the state
86
 */
87
declare function snapshot<T>(state: T): Snapshot<T>;
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
let counter = $state({ count: 0, history: [] });
94

95
function logState() {
96
  // Will log the actual object, not the Proxy
97
  console.log($state.snapshot(counter));
98
}
99

100
function saveToLocalStorage() {
101
  const snapshot = $state.snapshot(counter);
102
  localStorage.setItem("counter", JSON.stringify(snapshot));
103
}
104
```
105

106
### $derived
107

108
Creates derived state that automatically updates when its dependencies change.
109

110
```typescript { .api }
111
/**
112
 * Declares derived state that depends on other reactive values
113
 * @param expression - Expression that computes the derived value
114
 * @returns Derived reactive value
115
 */
116
declare function $derived<T>(expression: T): T;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
let count = $state(0);
123
let name = $state("Alice");
124

125
// Simple derived values
126
let doubled = $derived(count * 2);
127
let greeting = $derived(`Hello, ${name}!`);
128
let isEven = $derived(count % 2 === 0);
129

130
// Derived from multiple sources
131
let summary = $derived(`${name} has clicked ${count} times`);
132

133
// Complex derived values
134
let expensiveComputation = $derived(() => {
135
  return someHeavyCalculation(count);
136
});
137
```
138

139
### $derived.by
140

141
Creates complex derived state using a function for more elaborate computations.
142

143
```typescript { .api }
144
/**
145
 * Creates complex derived state using a function
146
 * @param fn - Function that computes the derived value
147
 * @returns Derived reactive value
148
 */
149
declare function by<T>(fn: () => T): T;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
let numbers = $state([1, 2, 3, 4, 5]);
156

157
let total = $derived.by(() => {
158
  let result = 0;
159
  for (const n of numbers) {
160
    result += n;
161
  }
162
  return result;
163
});
164

165
let filtered = $derived.by(() => {
166
  return numbers.filter(n => n > 2);
167
});
168

169
// Complex async-like patterns (though derived should be sync)
170
let processedData = $derived.by(() => {
171
  if (!rawData.length) return [];
172
  
173
  return rawData
174
    .map(item => processItem(item))
175
    .filter(item => item.isValid)
176
    .sort((a, b) => a.priority - b.priority);
177
});
178
```
179

180
### $effect
181

182
Runs side effects when reactive dependencies change.
183

184
```typescript { .api }
185
/**
186
 * Runs code when dependencies change, after DOM updates
187
 * @param fn - Function to run, can return cleanup function
188
 */
189
declare function $effect(fn: () => void | (() => void)): void;
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
let count = $state(0);
196
let name = $state("Alice");
197

198
// Basic effect
199
$effect(() => {
200
  console.log(`Count is now ${count}`);
201
});
202

203
// Effect with cleanup
204
$effect(() => {
205
  const interval = setInterval(() => {
206
    console.log(`Count: ${count}`);
207
  }, 1000);
208
  
209
  return () => clearInterval(interval);
210
});
211

212
// Effect with multiple dependencies
213
$effect(() => {
214
  document.title = `${name} - Count: ${count}`;
215
});
216

217
// Conditional effects
218
$effect(() => {
219
  if (count > 10) {
220
    console.log("Count is getting high!");
221
  }
222
});
223
```
224

225
### $effect.pre
226

227
Runs effects before DOM updates, useful for reading DOM state before changes.
228

229
```typescript { .api }
230
/**
231
 * Runs code before DOM updates when dependencies change
232
 * @param fn - Function to run, can return cleanup function
233
 */
234
declare function pre(fn: () => void | (() => void)): void;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
let items = $state([]);
241
let container;
242

243
$effect.pre(() => {
244
  if (container) {
245
    const scrollableDistance = container.scrollHeight - container.offsetHeight;
246
    const shouldAutoScroll = container.scrollTop > (scrollableDistance - 20);
247
    
248
    if (shouldAutoScroll) {
249
      // Will scroll after DOM updates
250
      $effect(() => {
251
        container.scrollTo(0, container.scrollHeight);
252
      });
253
    }
254
  }
255
});
256
```
257

258
### $effect.root
259

260
Creates a non-tracked effect scope that doesn't auto-cleanup and can be manually controlled.
261

262
```typescript { .api }
263
/**
264
 * Creates a non-tracked scope that doesn't auto-cleanup
265
 * @param fn - Function to run, can return cleanup function
266
 * @returns Cleanup function to manually destroy the effect
267
 */
268
declare function root(fn: () => void | (() => void)): () => void;
269
```
270

271
**Usage Examples:**
272

273
```typescript
274
let count = $state(0);
275

276
const cleanup = $effect.root(() => {
277
  $effect(() => {
278
    console.log(`Count: ${count}`);
279
  });
280
  
281
  return () => {
282
    console.log("Root effect cleaned up");
283
  };
284
});
285

286
// Later, manually cleanup
287
cleanup();
288
```
289

290
### $effect.tracking
291

292
Checks whether code is running inside a tracking context.
293

294
```typescript { .api }
295
/**
296
 * Checks if code is running inside a tracking context
297
 * @returns true if inside an effect or template, false otherwise
298
 */
299
declare function tracking(): boolean;
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
function myUtility() {
306
  if ($effect.tracking()) {
307
    // We're inside an effect or template, safe to read reactive state
308
    return someReactiveValue;
309
  } else {
310
    // Not in tracking context, perhaps return cached value
311
    return cachedValue;
312
  }
313
}
314
```
315

316
### $props
317

318
Declares component props with proper typing and reactivity.
319

320
```typescript { .api }
321
/**
322
 * Declares the props that a component accepts
323
 * @returns Props object with reactive properties
324
 */
325
declare function $props(): any;
326
```
327

328
**Usage Examples:**
329

330
```typescript
331
// Basic props
332
let { name, age, email } = $props();
333

334
// Props with defaults
335
let { theme = "light", size = "medium" } = $props();
336

337
// Typed props (in TypeScript)
338
interface Props {
339
  name: string;
340
  age?: number;
341
  onSubmit?: (data: any) => void;
342
}
343

344
let { name, age = 0, onSubmit }: Props = $props();
345

346
// Bindable props
347
let { value = $bindable() } = $props();
348
```
349

350
### $bindable
351

352
Declares a prop as bindable, allowing parent components to bind to it.
353

354
```typescript { .api }
355
/**
356
 * Declares a prop as bindable
357
 * @param fallback - Default value if not bound
358
 * @returns Bindable prop value
359
 */
360
declare function $bindable<T>(fallback?: T): T;
361
```
362

363
**Usage Examples:**
364

365
```typescript
366
// Child component
367
let { value = $bindable("") } = $props();
368

369
// Parent can now use bind:value
370
// <ChildComponent bind:value={parentValue} />
371

372
// With default value
373
let { isOpen = $bindable(false) } = $props();
374

375
// The parent can bind to it
376
// <Modal bind:isOpen={showModal} />
377
```
378

379
### $inspect
380

381
Development utility for inspecting reactive values and their changes.
382

383
```typescript { .api }
384
/**
385
 * Inspects reactive values and logs changes
386
 * @param values - Values to inspect
387
 * @returns Object with 'with' method for custom inspection
388
 */
389
declare function $inspect<T extends any[]>(
390
  ...values: T
391
): { with: (fn: (type: 'init' | 'update', ...values: T) => void) => void };
392
```
393

394
**Usage Examples:**
395

396
```typescript
397
let count = $state(0);
398
let name = $state("Alice");
399

400
// Basic inspection (logs to console)
401
$inspect(count);
402
$inspect(count, name);
403

404
// Custom inspection
405
$inspect(count).with((type, value) => {
406
  console.log(`${type}: count is ${value}`);
407
});
408

409
$inspect(count, name).with((type, countVal, nameVal) => {
410
  if (type === 'update') {
411
    console.log(`Update: ${nameVal} has count ${countVal}`);
412
  }
413
});
414
```
415

416
## Types
417

418
```typescript { .api }
419
type Snapshot<T> = T extends Primitive
420
  ? T
421
  : T extends Cloneable
422
    ? NonReactive<T>
423
    : T extends { toJSON(): infer R }
424
      ? R
425
      : T extends Array<infer U>
426
        ? Array<Snapshot<U>>
427
        : T extends object
428
          ? { [K in keyof T]: Snapshot<T[K]> }
429
          : never;
430

431
type Primitive = string | number | boolean | null | undefined;
432

433
type NotFunction<T> = T extends Function ? never : T;
434
```
435

436
## Migration from Svelte 4
437

438
- Replace `let count = 0` with `let count = $state(0)`
439
- Replace `$: doubled = count * 2` with `let doubled = $derived(count * 2)`
440
- Replace `$: { console.log(count); }` with `$effect(() => { console.log(count); })`
441
- Use `$props()` instead of `export let` for component props