debug-svelte_skill

Overview

This skill systematically debugs Svelte applications, covering both Svelte 4 patterns and Svelte 5 runes-based reactivity. It helps identify reactivity failures, runes mistakes, store subscription leaks, SSR hydration mismatches, and compiler warnings, and points to practical tools and commands to verify fixes.

How this skill works

The skill inspects component state and reactivity usage, checks for common anti-patterns (mutating objects without reassignment, improper rune usage, circular derived/effect loops), and verifies SSR vs client-only code paths. It suggests targeted runtime helpers ($inspect(), {@debug}), lifecycle logs, svelte-check diagnostics, and isolation steps to reproduce and validate fixes in dev and production builds.

When to use it

• UI doesn't update or computed values are stale after state changes
• Console shows hydration mismatch warnings or SSR content differs from client
• You see infinite loops or repeated updates from $derived/$effect
• Store subscriptions leak or stop receiving updates
• Compiler errors about undefined variables, non-bindable props, or rune misuse

Best practices

• Use $state for Svelte 5 top-level reactivity and wrap nested objects or use immutable reassignment in Svelte 4
• Keep $derived pure and avoid mutating tracked state inside it; use $effect with untrack() for controlled side effects
• Always unsubscribe manual store subscriptions or use auto-subscription ($myStore) to let Svelte clean up
• Guard browser-only APIs (localStorage, Date) with browser checks or initialize onMount to avoid SSR mismatches
• Run npx svelte-check and test a production build (npm run build && npm run preview) before concluding a fix

Example use cases

• Diagnosing why a component prop stops updating after destructuring in Svelte 5
• Finding and breaking an infinite update loop caused by a $derived that mutates state
• Locating a memory leak from a forgotten store.unsubscribe in a long-lived page
• Resolving hydration mismatch by moving Date/localStorage access into onMount or guarding with browser
• Migrating a Svelte 4 project to Svelte 5 and fixing let -> $state, $: -> $derived/$effect, and export let -> $props() changes