Svelte Scan
svelte-scan
SvelteKit health inspector — visualize DOM mutations, catch runaway effects, detect memory leaks, and surface console errors. All in a floating toolbar while you develop.
Built for Svelte 5 with runes.
What It Does
| Observer | What it catches |
|---|---|
| DOM | Elements mutating too frequently; flashes them in the overlay |
| Effects | $effect calls exceeding thresholds (warn ≥10, critical ≥50) |
| Leaks | Uncleared event listeners, intervals, timeouts, and requestAnimationFrame loops |
| Reactivity | Signal/derived/effect counts and max dependency depth |
| Console | console.error and console.warn calls with source attribution |
The toolbar shows live stats across five tabs (DOM · Effects · Leaks · Reactivity · Console), an FPS meter color-coded by performance, and a one-click copy of the full report.
Installation
npm install @heyramzi/svelte-scan
# or
pnpm add @heyramzi/svelte-scan
Requires svelte ^5.0.0 as a peer dependency.
Usage
Add <SvelteScan /> to your root layout — dev-only:
<!-- src/routes/+layout.svelte -->
<script>
import { dev } from '$app/environment'
import { SvelteScan } from '@heyramzi/svelte-scan'
</script>
{#if dev}
<SvelteScan />
{/if}
Props
| Prop | Type | Default | Description |
|---|---|---|---|
observers |
Partial<ObserversConfig> |
all enabled | Toggle individual observers |
toolbar |
boolean |
true |
Show the floating toolbar |
overlay |
boolean |
true |
Flash overlay on DOM mutations |
position |
"bottom-left" | "bottom-right" | "top-left" | "top-right" |
"bottom-left" |
Toolbar position |
<!-- Disable specific observers -->
<SvelteScan
observers={{ leaks: false, reactivity: false }}
position="bottom-right"
/>
<!-- Overlay only, no toolbar -->
<SvelteScan toolbar={false} overlay={true} />
Ignoring Elements
Add data-svelte-scan-ignore to any element to exclude it from DOM mutation tracking:
<div data-svelte-scan-ignore>
<!-- mutations here won't be counted -->
</div>
Toolbar
The pill in the corner shows the live FPS:
- Green — ≥50 fps
- Yellow — 30–49 fps
- Red — <30 fps
Click the pill to expand the full toolbar. Right-click it to copy a full diagnostic report to the clipboard.
Programmatic API
import type { SvelteScanConfig } from '@heyramzi/svelte-scan'
SvelteScanConfig is the full config shape if you need to build tooling around it.
Structure
src/
├── SvelteScan.svelte # Root component — wires observers, overlay, toolbar
├── core/
│ ├── types.ts # All event and config types
│ ├── collector.ts # Event bus and stats aggregator
│ ├── fps.ts # rAF-based FPS meter
│ └── internals.ts # Svelte 5 internals access (effects, signals)
├── observers/
│ ├── dom.ts # MutationObserver-based DOM tracker
│ ├── effects.ts # $effect call tracker
│ ├── leaks.ts # Listener / timer leak detector
│ ├── reactivity.ts # Signal graph inspector
│ └── console.ts # console.error/warn interceptor
└── ui/
├── Toolbar.svelte # Floating toolbar with tabs
├── flash.ts # DOM mutation flash overlay
└── toolbar-styles.ts # Injected CSS
Development
pnpm install
pnpm test # Run Vitest tests
Tests are colocated next to each module (*.test.ts).
