Debugging

Active contributors: Rich Harris, Simon H, Dominic Gannaway

Inspecting compiled output

The fastest way to understand a runtime issue is to look at what the compiler emits. From packages/svelte/:

pnpm test snapshot -t name-of-feature

Snapshot tests under packages/svelte/tests/snapshot/samples/ write .expected.js files alongside each input — these are the compiled outputs. For an ad-hoc input, write a temp file, call compile() from packages/svelte/src/compiler/index.js, and console.log(result.js.code).

A playground app (playgrounds/sandbox/) is the most ergonomic path for a real running component plus DevTools.

Tracing reactivity

The dev runtime exposes reactivity tracing through the $inspect.trace(...) rune and the underlying helpers in packages/svelte/src/internal/client/dev/tracing.js. Set tracing_mode_flag (packages/svelte/src/internal/flags/tracing.js) or use the tracing compiler option to enable it during development.

$inspect(value) itself logs each change to the console with stack traces in dev. See packages/svelte/src/internal/client/dev/inspect.js.

Error and warning sources

Error and warning text is in packages/svelte/messages/. To search:

grep -r "your message text" packages/svelte/messages

The matching code path is reachable by searching for the function name in errors.js / warnings.js (e.g., e.lifecycle_outside_component(...)).

Failing test, no obvious diff

1. Check UPDATE_SNAPSHOTS=true pnpm test ... output for unintended changes. The Lint CI job will catch generated-file drift, so commit only what you actually meant to change.
2. Scope down with -t to isolate a single case.
3. Drop into node --inspect-brk — pnpm bench:debug is the canonical example. For tests:

   pnpm exec vitest run --inspect-brk -t "your test name" tests/runtime-runes

4. Pin the runtime flags — SVELTE_NO_ASYNC=true reproduces the TestNoAsync CI job locally.

Build/types out of sync

If the Lint CI job fails on "Generated types have changed":

cd packages/svelte
pnpm build
pnpm generate:types
git add -A

Then commit the regenerated artifacts. Any actual .d.ts drift is a code-generation bug worth investigating.

Hot path: the runtime scheduler

For "why didn't my effect run?" or "why did it run twice?" issues, the most-touched files are:

• packages/svelte/src/internal/client/runtime.js — top-level update_effect, set_active_reaction, is_dirty.
• packages/svelte/src/internal/client/reactivity/batch.js — Batch, flushSync, scheduling.
• packages/svelte/src/internal/client/reactivity/effects.js — effect creation, teardown, status flags.

packages/svelte/src/internal/client/constants.js lists the bitmask constants (CLEAN, DIRTY, MAYBE_DIRTY, DERIVED, BRANCH_EFFECT, etc.) — knowing those by name makes runtime debugging much faster.

When all else fails

Open a draft PR with a failing test under packages/svelte/tests/runtime-runes/samples/<your-name>/ and ask in #contributing on Discord (link in CONTRIBUTING.md). The maintainers triage these regularly.