svelte5-runes-static_skill

Overview

This skill provides patterns for using Svelte 5 runes with SvelteKit adapter-static to build static-first apps that hydrate correctly. It documents safe hybrid approaches: keep global state in traditional Svelte stores, use runes for component-local reactivity, and bridge stores into rune state so reactivity survives prerendering.

How this skill works

The skill inspects common anti-patterns that break hydration with adapter-static and replaces them with prerender-safe alternatives. It prescribes using writable/derived stores for global serialized state, subscribing to those stores inside $effect() to populate $state() runes in components, and computing derived rune values with $derived(). It also recommends browser-guarded client-only initialization to avoid hydration mismatches.

When to use it

• Building SSG pages with adapter-static where global state must survive prerendering
• When combining shared writable stores with Svelte 5 runes inside components
• When migrating from Svelte 4 to Svelte 5 runes and preserving hydration
• When needing derived, component-local computations that must be reactive after hydration
• When implementing client-only features (websockets, localStorage) without causing hydration errors

Best practices

• Keep global/shared state in writable()/derived() stores so it serializes during SSG
• Never create runes in module scope for global state—use stores or initialize runes in component scope
• Bridge store -> rune via $effect() subscriptions that assign to $state() and return unsubscribes
• Avoid $auto-subscription ($store) inside $derived; subscribe manually in $effect() then derive from $state()
• Guard client-only side effects with browser checks or {#if browser} to prevent hydration mismatch

Example use cases

• A prerendered dashboard where user and theme are global stores and widgets use runes for local UI state
• A search component that bridges a debounced derived store into rune state for client-side filtering
• A realtime event list that uses a writable socket store and a rune-based filtered view derived from bridged events
• Migrating a Svelte 4 app: replace $: with $derived(), export props via $props(), and add store → rune bridges
• Client-only initialization like WebSocket connect or localStorage reads inside $effect() guarded by browser