szweibel/svelte-5-runes

Svelte 5 Runes

Feature Status: Stable in Svelte 5.0+ (October 2024) Documentation Source: https://svelte.dev/docs/svelte/what-are-runes

Complete guide to Svelte 5's reactivity system using runes.

When to Use This Skill

Use this skill for any Svelte 5 project. Runes are the core reactivity primitives:

• Creating reactive state with $state
• Computing derived values with $derived
• Running side effects with $effect
• Defining component props with $props
• Creating bindable props with $bindable
• Debugging with $inspect

What Are Runes?

Runes are symbols prefixed with $ that control Svelte's compiler. They are:

• Built-in language keywords - No imports required
• Not functions - Cannot be assigned to variables or passed around
• Position-dependent - Only valid in specific contexts

Available Runes:

• $state - Declare reactive state
• $derived - Create computed values
• $effect - Manage side effects
• $props - Define component properties
• $bindable - Enable two-way binding on props
• $inspect - Debug tool for state inspection
• $host - Access custom element host (web components)
• $props.id() - Generate consistent component-scoped IDs

Quick Start Patterns

Reactive State ($state)

<script>
	let count = $state(0);
	let user = $state({ name: 'Ada', age: 28 });
</script>

<button onclick={() => count++}>
	Clicks: {count}
</button>

<button onclick={() => user.age++}>
	Happy birthday {user.name}! Age: {user.age}
</button>

Key features:

• Deep reactivity by default (objects/arrays)
• Mutations trigger UI updates
• Use $state.raw() for non-reactive data
• Works in class fields

Computed Values ($derived)

<script>
	let count = $state(0);
	let doubled = $derived(count * 2);

	// Complex derivations
	let status = $derived.by(() => {
		if (count < 5) return 'low';
		if (count < 10) return 'medium';
		return 'high';
	});
</script>

<p>{count} doubled is {doubled}</p>
<p>Status: {status}</p>

When to use:

• Transforming state values
• Computing aggregations
• Filtering/mapping arrays
• ANY value derived from other state

Side Effects ($effect)

<script>
	let count = $state(0);
	let canvas;

	$effect(() => {
		// Runs when count changes
		console.log('Count changed:', count);

		// Cleanup function (optional)
		return () => {
			console.log('Cleanup before re-run');
		};
	});

	$effect(() => {
		if (!canvas) return;
		const ctx = canvas.getContext('2d');
		ctx.clearRect(0, 0, 100, 100);
		ctx.fillRect(0, 0, count, count);
	});
</script>

<canvas bind:this={canvas} width="100" height="100"></canvas>

Use for:

• Canvas drawing
• Third-party library integration
• Analytics tracking
• Network requests (with caution)

DON'T use for:

• Synchronizing state (use $derived)
• Computing values (use $derived)

Component Props ($props)

<!-- Parent.svelte -->
<script>
	import Child from './Child.svelte';
</script>

<Child name="Ada" age={28} />

<!-- Child.svelte -->
<script>
	// Destructure with defaults
	let { name, age = 18 } = $props();

	// Or get all props
	let props = $props();
</script>

<p>{name} is {age} years old</p>

TypeScript:

<script lang="ts">
	interface Props {
		name: string;
		age?: number;
	}

	let { name, age = 18 }: Props = $props();
</script>

Two-Way Binding ($bindable)

<!-- TextInput.svelte -->
<script>
	let { value = $bindable(''), placeholder } = $props();
</script>

<input bind:value {placeholder} />

<!-- App.svelte -->
<script>
	import TextInput from './TextInput.svelte';

	let message = $state('');
</script>

<TextInput bind:value={message} placeholder="Type here" />
<p>You typed: {message}</p>

Common Workflows

Form with Validation

<script>
	let email = $state('');
	let password = $state('');

	let isValidEmail = $derived(email.includes('@') && email.includes('.'));
	let isValidPassword = $derived(password.length >= 8);
	let canSubmit = $derived(isValidEmail && isValidPassword);

	function handleSubmit() {
		if (!canSubmit) return;
		// Submit form
	}
</script>

<form onsubmit={handleSubmit}>
	<input bind:value={email} type="email" />
	{#if email && !isValidEmail}
		<p class="error">Invalid email</p>
	{/if}

	<input bind:value={password} type="password" />
	{#if password && !isValidPassword}
		<p class="error">Password must be 8+ characters</p>
	{/if}

	<button disabled={!canSubmit}>Submit</button>
</form>

Data Fetching with Loading States

<script>
	let userId = $state(1);
	let userData = $state(null);
	let loading = $state(false);
	let error = $state(null);

	$effect(() => {
		// Tracks userId - refetches when it changes
		loading = true;
		error = null;

		fetch(`/api/users/${userId}`)
			.then(r => r.json())
			.then(data => {
				userData = data;
				loading = false;
			})
			.catch(e => {
				error = e.message;
				loading = false;
			});
	});
</script>

{#if loading}
	<p>Loading...</p>
{:else if error}
	<p class="error">{error}</p>
{:else if userData}
	<div>
		<h2>{userData.name}</h2>
		<p>{userData.email}</p>
	</div>
{/if}

<button onclick={() => userId++}>Next User</button>

Class-Based State

<script>
	class Counter {
		count = $state(0);

		increment = () => {
			this.count++;
		}

		reset() {
			this.count = 0;
		}
	}

	let counter = new Counter();
</script>

<button onclick={counter.increment}>
	Count: {counter.count}
</button>
<button onclick={() => counter.reset()}>Reset</button>

Best Practices

1. Use $derived, Not $effect for Computed Values

❌ Don't do this:

<script>
	let count = $state(0);
	let doubled = $state(0);

	$effect(() => {
		doubled = count * 2;
	});
</script>

✅ Do this:

<script>
	let count = $state(0);
	let doubled = $derived(count * 2);
</script>

2. Understand Deep Reactivity

<script>
	let items = $state([1, 2, 3]);

	// All these trigger reactivity:
	items.push(4);          // ✅ Works
	items[0] = 10;          // ✅ Works
	items = items.filter(x => x > 1); // ✅ Works

	// Destructuring breaks reactivity:
	let [first] = items;
	items[0] = 99;          // first still has old value
</script>

3. Use $state.raw for Large Immutable Data

<script>
	// Don't need deep reactivity - performance win
	let config = $state.raw({
		apiUrl: 'https://api.example.com',
		timeout: 5000,
		// ... hundreds of properties
	});

	// Only reassign, don't mutate
	config = { ...config, timeout: 10000 };
</script>

4. Effect Dependencies Are Automatic

<script>
	let a = $state(1);
	let b = $state(2);
	let c = $state(3);

	$effect(() => {
		// Only depends on `a` and `b`
		console.log(a + b);

		// `c` is not a dependency - won't rerun when c changes
	});
</script>

5. Props Flow Down, Events Flow Up

<!-- Child.svelte -->
<script>
	let { count, onIncrement } = $props();
</script>

<button onclick={onIncrement}>
	Count: {count}
</button>

<!-- Parent.svelte -->
<script>
	import Child from './Child.svelte';

	let count = $state(0);
</script>

<Child {count} onIncrement={() => count++} />

6. Don't Mutate Props (Use $bindable)

❌ Don't:

<script>
	let { count } = $props();
</script>

<button onclick={() => count++}>
	{count}
</button>

✅ Do:

<script>
	let { count = $bindable() } = $props();
</script>

<button onclick={() => count++}>
	{count}
</button>

7. Use $inspect for Debugging

<script>
	let count = $state(0);

	$inspect(count); // Logs when count changes with stack trace

	// Custom logging
	$inspect(count).with((type, value) => {
		if (type === 'update') {
			console.log('Count updated to:', value);
		}
	});
</script>

Common Pitfalls

Async State in Effects

Issue: Async code doesn't track dependencies.

<script>
	let userId = $state(1);
	let user = $state(null);

	$effect(() => {
		// userId IS tracked (read before await)
		const id = userId;

		fetch(`/api/users/${id}`)
			.then(r => r.json())
			.then(data => {
				// This works, but any state read HERE
				// is NOT tracked as a dependency
				user = data;
			});
	});
</script>

Effect Cleanup

Always cleanup subscriptions:

<script>
	let count = $state(0);

	$effect(() => {
		const interval = setInterval(() => {
			count++;
		}, 1000);

		// Cleanup when effect re-runs or component unmounts
		return () => clearInterval(interval);
	});
</script>

Infinite Loops

Don't read and write same state in effect:

<script>
	let count = $state(0);

	// ❌ Infinite loop!
	$effect(() => {
		count = count + 1;
	});

	// ✅ Use derived instead
	let incremented = $derived(count + 1);
</script>

Migration from Svelte 4

Reactive Declarations

Svelte 4:

<script>
	let count = 0;
	$: doubled = count * 2;
	$: console.log('Count changed:', count);
</script>

Svelte 5:

<script>
	let count = $state(0);
	let doubled = $derived(count * 2);

	$effect(() => {
		console.log('Count changed:', count);
	});
</script>

Component Props

Svelte 4:

<script>
	export let name;
	export let age = 18;
</script>

Svelte 5:

<script>
	let { name, age = 18 } = $props();
</script>

Two-Way Binding

Svelte 4:

<script>
	export let value;
</script>

<input bind:value />

Svelte 5:

<script>
	let { value = $bindable() } = $props();
</script>

<input bind:value />

Detailed Documentation

For complete implementation details, read the reference files:

• references/quick-reference.md - All runes syntax at a glance
• references/state.md - Complete $state documentation (deep reactivity, classes, raw state)
• references/derived.md - $derived patterns and dependencies
• references/effect.md - $effect lifecycle, cleanup, and when NOT to use
• references/props.md - $props type safety and patterns
• references/other-runes.md - $bindable, $inspect, $host usage

Important Notes

• Runes are compile-time features - no runtime imports
• Effects run after DOM updates (use $effect.pre for before)
• Dependencies are tracked synchronously - async code won't track
• $state creates deep reactive proxies for objects/arrays
• Can't export $state directly from .svelte.js if reassigned
• Props should not be mutated unless marked with $bindable