svelte-doctor

Installation • Usage • Commands • Rules • Configuration

Diagnose and fix performance, correctness, and architecture issues in your Svelte codebase

Overview

svelte-doctor is a comprehensive diagnostic tool that analyzes your Svelte projects for security vulnerabilities, performance bottlenecks, architectural issues, and Svelte 4-to-5 migration patterns.

Run a single command to scan your entire codebase and receive a 0–100 health score with actionable, line-specific diagnostics.

Key Features

69 Source Diagnostic Rules covering correctness, performance, security, architecture, SvelteKit reliability, runtime performance, hydration safety, and CSS specificity
Build Artifact Diagnostics for SvelteKit output chunks, duplicate libraries, oversized bundles, and inline base64 assets
TypeScript AST-backed script analysis for lower false-positive rates on security-sensitive checks
Deterministic Safe Apply via apply for high-confidence fixes — covers CSS transitions, lodash/moment/icon imports, Svelte 4→5 migration, unnecessary $state wrappers, and $effect to $derived conversions
Baseline Suppression to keep legacy issues out of new CI failures
Interactive Project Bootstrap via init for config, CI, scripts, baseline, and .gitignore setup
Managed Git Hooks via install-hook for automatic pre-commit and pre-push quality gates
SARIF + GitHub Annotations for code scanning and CI integration
PR Check Workflow for branch diff analysis and GitHub PR summary comments
Diff-Aware and Workspace-Aware Scans for staged files, changed files, and monorepos
Safe-by-default AI Fix flow with secure temp prompts, opt-in unsafe execution, post-fix verification, and support for Cursor, Amp, Claude Code, Codex, Copilot CLI, OpenCode, Pi, Gemini CLI, Qwen Code, Aider, and Goose
AI-Friendly Copy Export via check --copy with clipboard-first fallback behavior
Svelte 4→5 AST-backed Auto-Migration with modular codemods, plan/diff/interactive modes, backups, rollback, staged commits, and JSON output
Migration Progress Tracking via migrate-status with migrated/pending/skipped counts, category breakdown, and ETA
Smart Ignore Suggestions via suggest-ignore with confidence scoring and generated ignore config snippets
Component Dependency Graphs via graph with ASCII, DOT, JSON, alias resolution, and circular dependency detection
Component Where-Used Lookup via where-used with line-accurate import/render locations, $lib and tsconfig alias resolution, dynamic import detection, render tree, scope filtering, and reverse direction
Bundle Impact Preview via bundle-impact for estimated savings from fixable bundle-size diagnostics
Dead Store Detection via dead-stores for finding writable stores never written anywhere, with cross-file write tracking and runes migration suggestions
Test Coverage Gap Finder via test-gaps for source-to-test matching and SvelteKit critical path checks
Rule Authoring Kit via create-rule for custom rule, test, and docs scaffolding
Component Render Profiler via render-profile for compile-time DOM, reactivity, hydration, and re-render cost ranking
Cached Scans + Incremental Watch for faster repeat checks and tighter feedback loops
Automatic .gitignore Sync for generated .svelte-doctor/* cache/history files while preserving tracked baseline negations
Dependency Health Checks and Upgrade Planning for ecosystem compatibility and npm registry updates
Quick Health Check via quick for fast error-only scans with instant score feedback
Security Audit via audit for focused security-only scans with a dedicated security score
Ref Comparison via compare for diagnosing regressions between commits, branches, and tags
Project Metrics via stats for rule frequency, category breakdown, and top affected files
Config Inspection via config and validate for viewing and validating the active configuration
Environment Diagnosis via doctor with --fix to auto-resolve config, gitignore, and dependency issues
Generated File Cleanup via reset to safely clear cache, baseline, and history
Single-Command Scan + Fix via check --fix for one-step diagnostic and deterministic auto-fix, with --interactive for step-by-step approval
Zero Configuration works out of the box

Installation

Runtime Requirement: Node.js 22.18.0+

If you are on Node 18 or Node 20, upgrade Node before installing or building svelte-doctor.

Global Installation (Recommended)

Install svelte-doctor globally to use it from anywhere in your terminal.

# Using bun (recommended)
bun i -g svelte-doctor

# Using npm
npm install -g svelte-doctor

# Using pnpm
pnpm add -g svelte-doctor

Add to PATH (Required for first-time setup):

If you get a "command not found" error after installation, add the global bin folder to your PATH:

macOS / Linux:

# For Bun users
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or source ~/.bashrc

# For npm users (usually automatic, but if needed)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows:

# For Bun users - run in PowerShell as Administrator
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.bun\bin", "User")

# For npm users - usually automatic
# If needed, add: %APPDATA%\npm to your PATH

Local Installation

You can also install it locally in your project:

# Using bun
bun i -D svelte-doctor

# Using npm
npm install -D svelte-doctor

# Using pnpm
pnpm add -D svelte-doctor

Then run with:

# Using npx / bunx
npx svelte-doctor
bunx svelte-doctor

# Or via package.json scripts
"scripts": {
  "doctor": "svelte-doctor check"
}

Usage

# Scan your project
svelte-doctor check

# Bootstrap config, scripts, CI, gitignore, and baseline
svelte-doctor init

# Non-interactive bootstrap with GitHub Actions
svelte-doctor init --yes --ci github-actions

# Install a managed pre-commit hook for staged-file checks
svelte-doctor install-hook --mode staged --fail-on error

# Add a pre-push hook and require warning-free CI-quality scans
svelte-doctor install-hook --pre-push --mode full --fail-on warning --min-score 80

# Force a cold scan without cache
svelte-doctor check --no-cache

# Copy diagnostics into an AI-friendly prompt
svelte-doctor check --copy

# Just the score (useful for CI)
svelte-doctor check --score

# Scan only changed files
svelte-doctor check --changed

# Scan all workspaces in a monorepo
svelte-doctor check --all-workspaces

# Generate a baseline from current issues
svelte-doctor baseline

# Apply safe deterministic fixes
svelte-doctor apply --write

# Auto-fix issues with an AI agent
svelte-doctor fix

# Force Copilot CLI (runs: copilot -p "<prompt>")
svelte-doctor fix --agent copilot

# Generate a secure prompt without spawning an agent
svelte-doctor fix --dry-run-prompt

# Update the global CLI from npm
svelte-doctor update

# Find writable stores that are never written (runes migration helper)
svelte-doctor dead-stores

# Dead store report as JSON for CI
svelte-doctor dead-stores --json

# Check whether a newer version exists
svelte-doctor update --check

# Auto-migrate Svelte 4 → Svelte 5
svelte-doctor migrate
svelte-doctor migrate --plan
svelte-doctor migrate --dry-run --diff
svelte-doctor migrate --interactive
svelte-doctor migrate --stage export-let
svelte-doctor migrate --rollback

# Track Svelte 4 → 5 migration progress
svelte-doctor migrate-status
svelte-doctor migrate-status --json

# Suggest likely false-positive ignores
svelte-doctor suggest-ignore
svelte-doctor suggest-ignore --json

# Preview bundle savings from fixable diagnostics
svelte-doctor bundle-impact
svelte-doctor bundle-impact --json

# Build a component dependency graph
svelte-doctor graph
svelte-doctor graph --format dot
svelte-doctor graph --format json

# Find every place a component is imported or rendered
svelte-doctor where-used Button
svelte-doctor where-used src/lib/Button.svelte
svelte-doctor where-used Button --json
svelte-doctor where-used Button --tree
svelte-doctor where-used Button --scope src/routes
svelte-doctor where-used Button --direction uses

# Find writable stores that are never written (runes migration helper)
svelte-doctor dead-stores
svelte-doctor dead-stores --json

# Find source files without matching tests
svelte-doctor test-gaps
svelte-doctor test-gaps --json

# Scaffold a custom rule, test, and docs
svelte-doctor create-rule no-custom-pattern

# Rank the most expensive components before runtime
svelte-doctor render-profile
svelte-doctor render-profile --top 10
svelte-doctor render-profile --watch
svelte-doctor render-profile --json

# Watch for changes and show live score
svelte-doctor watch

# Show score history and trend
svelte-doctor trend

# Check dependency health
svelte-doctor deps

# Check npm registry for dependency upgrades without writing files
svelte-doctor upgrade --dry-run

# Analyze current branch against main for PR/CI feedback
svelte-doctor pr-check --base main --head HEAD

# List rules or explain one in detail
svelte-doctor rules
svelte-doctor explain no-unsafe-shell

# Explain a rule with fix examples and project occurrences
svelte-doctor explain no-transition-all --fix
svelte-doctor explain no-moment --fix --json

# Quick health check (errors only, fast)
svelte-doctor quick
svelte-doctor quick --score

# Security-focused audit
svelte-doctor audit
svelte-doctor audit --score

# Project metrics and statistics
svelte-doctor stats
svelte-doctor stats --top 5

# Compare diagnostics between two git refs
svelte-doctor compare --base main --head HEAD
svelte-doctor compare --base v1.0.0 --head v2.0.0

# View active configuration
svelte-doctor config
svelte-doctor config --json

# Validate config file for errors
svelte-doctor validate
svelte-doctor validate --json

# Check your development environment
svelte-doctor doctor

# Automatically fix detected environment issues
svelte-doctor doctor --fix

# Clean generated files
svelte-doctor reset
svelte-doctor reset --cache

# Scan and apply deterministic fixes in one step
svelte-doctor check --fix
svelte-doctor check --fix --dry-run
svelte-doctor check --fix --interactive
svelte-doctor check --fix --fix-ai

Commands

`svelte-doctor doctor [directory] [options]`

Check your development environment for common issues — inspired by flutter doctor. Diagnoses Node.js version, Svelte dependency presence, svelte.config.js configuration, tsconfig.json validity, node_modules installation state, svelte-doctor.config.json schema validation, .gitignore completeness, build artifact freshness, and scan cache status.

With --fix, the command automatically resolves missing or misconfigured project files: creates svelte.config.js with vitePreprocess, generates tsconfig.json with TypeScript configuration, bootstraps svelte-doctor.config.json, adds the .svelte-doctor/* entry to .gitignore, injects doctor and doctor:fix scripts into package.json, and runs the detected package manager to install node_modules when missing.

Each check returns one of four statuses: pass, warning, fail, or na (not applicable). The command exits with code 1 if any check fails, making it suitable for CI onboarding gates.

Option	Description
`--json`	Output machine-readable JSON
`--fix`	Automatically fix detected issues (config, gitignore, scripts, etc)

Examples:

svelte-doctor doctor
svelte-doctor doctor packages/app
svelte-doctor doctor --json
svelte-doctor doctor --fix

`svelte-doctor init [directory] [options]`

Bootstrap an existing Svelte project for svelte-doctor. The command probes the project with the same discovery path used by scans, writes svelte-doctor.config.json, syncs .gitignore, injects package scripts, optionally creates a CI workflow, and can create an initial diagnostic baseline.

Generated defaults:

svelte-doctor.config.json
.svelte-doctor/* entry in .gitignore
package.json scripts: doctor and doctor:fix
optional CI file for GitHub Actions, GitLab CI, or CircleCI
optional .svelte-doctor/baseline.json
optional direct .git/hooks/pre-commit hook

Option	Description
`--ci <github-actions\|gitlab-ci\|circle-ci>`	Generate CI config for the selected platform
`--force`	Overwrite existing `svelte-doctor.config.json` and generated CI file
`-y, --yes`	Accept defaults without prompts

Examples:

svelte-doctor init
svelte-doctor init --yes
svelte-doctor init --yes --ci github-actions
svelte-doctor init packages/app --ci gitlab-ci

`svelte-doctor install-hook [directory] [options]`

Install, list, or remove managed git hooks that run svelte-doctor check automatically. The command detects direct git hooks, Husky (.husky/), and Lefthook (.lefthook/ or lefthook.yml). It chooses bunx, pnpm exec, or npx from the lockfile and only updates hooks that contain the svelte-doctor managed hook signature unless --force is used.

Use this for low-friction local adoption: developers do not need to remember a scan command before committing. Pair it with CI generated by svelte-doctor init --ci github-actions or an equivalent pipeline command such as bunx svelte-doctor check --fail-on warning --min-score 80 to block PRs when warnings or score regressions appear.

Option	Description
`--pre-push`	Also manage a `pre-push` hook in addition to `pre-commit`
`--mode <staged\|changed\|full>`	Choose scan scope for the hook command
`--fail-on <never\|error\|warning>`	Control hook exit behavior
`--min-score <score>`	Fail if the scan score is below the threshold
`--force`	Overwrite an existing non-svelte-doctor hook
`--remove`	Remove svelte-doctor managed hooks
`--list`	List managed hook status
`--json`	Output machine-readable JSON

Examples:

# Pre-commit only, scans staged files
svelte-doctor install-hook

# Pre-commit and pre-push, full scan with warning gate and score floor
svelte-doctor install-hook --pre-push --mode full --fail-on warning --min-score 80

# Inspect current hook state
svelte-doctor install-hook --list
svelte-doctor install-hook --list --json

# Remove only svelte-doctor managed hooks
svelte-doctor install-hook --remove --pre-push

`svelte-doctor check [directory] [options]`

Scan your project for issues and output a health score. The scanner analyzes source files, Svelte compiler output, and existing SvelteKit build artifacts under .svelte-kit/output/ when that directory exists. Every run saves the score to .svelte-doctor/history.json, including --json and --score modes, so your CI pipeline contributes to the trend graph. When svelte-doctor first creates its local .svelte-doctor/ directory, it also ensures the scanned project's .gitignore contains a .svelte-doctor/* entry unless an equivalent .svelte-doctor or .svelte-doctor/* pattern already exists.

Option	Description
`--score`	Output only the numeric score
`--json`	Output machine-readable JSON
`--no-lint`	Skip lint rules
`--no-dead-code`	Skip dead code detection
`--no-cache`	Disable the on-disk scan cache for this run
`--copy`	Export diagnostics in an AI-friendly format
`--copy-output <clipboard\|stdout\|file>`	Choose clipboard, stdout, or file output
`--copy-file <path>`	Write export output to a file inside the scanned project root
`--copy-max <count>`	Limit how many diagnostics are included in the export
`--copy-errors-only`	Export only error-level diagnostics
`--copy-format <prompt\|raw>`	Export as a structured prompt or raw text
`--baseline`	Suppress diagnostics present in `.svelte-doctor/baseline.json`
`--sarif`	Emit SARIF output
`--sarif-file <path>`	Write SARIF output to a file
`--html`	Write an interactive HTML report to `.svelte-doctor/report.html`
`--html-file <path>`	Write HTML report to a custom file
`--junit`	Write a JUnit XML report to `.svelte-doctor/junit.xml`
`--junit-file <path>`	Write JUnit XML report to a custom file
`--markdown`	Write a Markdown report to `.svelte-doctor/report.md`
`--markdown-file <path>`	Write Markdown report to a custom file
`--github-annotations`	Emit GitHub Actions annotation commands
`--fail-on <never\|error\|warning>`	Control exit behavior
`--min-score <score>`	Fail if score is below the threshold
`--changed`	Scan files changed relative to `HEAD`
`--staged`	Scan staged files only
`--since <ref>`	Scan files changed since a git ref
`--all-workspaces`	Scan all package.json workspaces
`--workspace <name>`	Scan one workspace by name or relative path
`--fix`	Apply deterministic auto-fixes after scan
`--interactive`	With `--fix`: confirm each fix individually (`y`, `n`, `a`, `q`)
`--fix-ai`	Also run AI agent fix after deterministic fixes
`--dry-run`	With `--fix`: preview fixes without writing files
`--rules <csv>`	With `--fix`: limit deterministic fixes to comma-separated rules
`--errors-only`	With `--fix`: fix only error-severity diagnostics
`--verify-level <level>`	With `--fix-ai`: verification depth — `diagnostics`, `typecheck`, `tests`, or `full`
`--max-files <count>`	With `--fix-ai`: max diagnostics in AI agent batch (default: 50)

--copy is designed for cases where you want to paste diagnostics into a different AI agent instead of using svelte-doctor fix. The default mode tries the system clipboard first, then falls back to stdout if no clipboard integration is available. If you need deterministic output for scripts, use --copy-output file.

JSON output includes structured fix metrics:

Field	Type	Description
`fixableSummary`	object	Auto-fixable, AI-fixable, and manual-required counts
`estimatedFixTime`	string	Estimated time to fix all issues (e.g. `"3m 20s"`)
`priorityFiles`	string[]	Top 5 files ranked by weighted issue severity
`regressionRisk`	string	`low`, `medium`, `high`, or `critical` risk level

# Quick CI summary with jq
svelte-doctor check --json | jq '{score, risk: .regressionRisk, fixTime: .estimatedFixTime, autoFix: .fixableSummary.autoFixable}'

# Gate PRs by regression risk
RISK=$(svelte-doctor check --json | jq -r '.regressionRisk')
if [ "$RISK" = "high" ] || [ "$RISK" = "critical" ]; then
  echo "Block merge: regression risk too high"
  exit 1
fi

Rich reports also work with --all-workspaces and --workspace. Workspace reports aggregate diagnostics into one file and prefix paths with the workspace directory, such as packages/app/src/App.svelte.

Examples:

svelte-doctor check --copy
svelte-doctor check --copy --copy-errors-only
svelte-doctor check --copy --copy-output stdout
svelte-doctor check --copy --copy-output file --copy-file .svelte-doctor/diagnostics.txt
svelte-doctor check --changed
svelte-doctor check --sarif --sarif-file .svelte-doctor/report.sarif
svelte-doctor check --html --html-file .svelte-doctor/report.html
svelte-doctor check --junit --junit-file .svelte-doctor/junit.xml
svelte-doctor check --markdown --markdown-file .svelte-doctor/report.md
svelte-doctor check --all-workspaces --html --junit --markdown

# Scan and apply fixes in one step
svelte-doctor check --fix
svelte-doctor check --fix --dry-run
svelte-doctor check --fix --interactive
svelte-doctor check --fix --fix-ai --verify-level tests

`svelte-doctor baseline [directory]`

Create .svelte-doctor/baseline.json from the current diagnostics so future checks can suppress already-known issues with check --baseline.

Examples:

svelte-doctor baseline
svelte-doctor baseline --changed
svelte-doctor baseline --all-workspaces

`svelte-doctor apply [directory] [options]`

Apply deterministic, high-confidence fixes without launching an AI agent. This command is intentionally conservative and only rewrites patterns the tool can fix safely.

Supported fixes:

no-transition-all — replaces transition: all with explicit opacity and transform
no-full-lodash — rewrites full lodash imports to per-function paths
no-moment — replaces moment imports with dayjs
no-full-icon-import — converts namespace icon imports to named imports
Svelte 4→5 migration rules (no-legacy-reactive, no-export-let, no-legacy-slots, no-on-directive, no-event-dispatcher, no-let-directive, no-legacy-lifecycle)
no-unnecessary-state — strips $state() wrapper from values that are never mutated
no-effect-for-derived — converts $effect(() => { x = expr }) to const x = $derived(expr)

Option	Description
`--dry-run`	Preview changes without writing files
`--write`	Write changes to disk
`--json`	Output machine-readable JSON
`--rules <csv>`	Restrict fixes to specific rule names
`--changed`	Apply fixes only on files changed relative to `HEAD`
`--staged`	Apply fixes only on staged files
`--since <ref>`	Apply fixes only on files changed since a git ref

Examples:

svelte-doctor apply --write
svelte-doctor apply --dry-run
svelte-doctor apply --write --rules no-transition-all,no-full-lodash

`svelte-doctor fix [directory] [options]`

Detects installed AI coding agents (Cursor, Amp, Claude Code, Codex, Copilot CLI, OpenCode, Pi, Gemini CLI, Qwen Code, Aider, Goose) and uses the best available one to fix reported issues automatically. The flow is safe by default: privileged agent flags are disabled unless you explicitly pass --unsafe-agent-exec. Diagnostics are redacted before prompt generation, prompts are written into a secure temp directory when needed, and post-fix verification can be escalated from diagnostics-only to full typecheck/test/build smoke.

Supported agent ids for --agent are cursor, amp, claude, codex, copilot, opencode, pi, gemini, qwen, aider, and goose. Install and authenticate at least one of them first, then run svelte-doctor fix. The command uses each agent's documented non-interactive mode where available: Amp execute mode, Claude print mode, Codex exec mode, Copilot prompt mode, OpenCode run mode, Pi print mode, Gemini headless mode, Qwen headless mode, Aider message mode, and Goose run mode.

# Use the best installed agent
svelte-doctor fix

# Force a specific agent
svelte-doctor fix --agent amp
svelte-doctor fix --agent claude
svelte-doctor fix --agent codex
svelte-doctor fix --agent copilot
svelte-doctor fix --agent opencode
svelte-doctor fix --agent pi
svelte-doctor fix --agent gemini
svelte-doctor fix --agent qwen
svelte-doctor fix --agent aider
svelte-doctor fix --agent goose

# Preview the prompt if you want to paste it manually
svelte-doctor fix --dry-run-prompt

Option	Description
`--agent <name>`	Force a specific agent (cursor, amp, claude, codex, copilot, opencode, pi, gemini, qwen, aider, goose)
`--errors-only`	Fix only errors first (reduces cascade errors, run again for warnings)
`--unsafe-agent-exec`	Opt in to agent-specific privileged execution flags
`--dry-run-prompt`	Generate the secure prompt bundle without spawning an agent
`--verify-level <level>`	Verification depth: `diagnostics`, `typecheck`, `tests`, `full`
`--max-files <count>`	Limit how many diagnostics are sent in a single agent batch

Supported agents under src/agents:

Agent id	CLI command	Non-interactive mode
`cursor`	`agent`	`--print --workspace <cwd> --output-format stream-json`
`amp`	`amp`	`-x` execute mode, unsafe opt-in via `--dangerously-allow-all`
`claude`	`claude`	`-p --output-format stream-json --include-partial-messages`
`codex`	`codex`	`exec -C <cwd>`, unsafe opt-in via bypass flag
`copilot`	`copilot`	`-p`
`opencode`	`opencode`	`run`
`pi`	`pi`	`-p`
`gemini`	`gemini`	`-p`, unsafe opt-in via `--yolo`
`qwen`	`qwen`	`-p`, unsafe opt-in via `--yolo`
`aider`	`aider`	`--yes --no-auto-commits --message`
`goose`	`goose`	`run --no-session --quiet -t`

`svelte-doctor migrate [directory] [options]`

Auto-migrate Svelte 4 syntax to Svelte 5. The migration engine uses a modular codemod pipeline with Svelte parser validation and TypeScript AST-backed script transforms for safer rewrites than line-only regex replacement. Template transforms remain conservative and parser-validated; complex cases are marked for review instead of being silently rewritten.

Transformations:

$: reactive statements → $derived() / $effect()
export let props, including defaults and TypeScript annotations → let { ... } = $props()
Destructuring reactive assignments such as $: ({ value } = item) → $derived() review-safe output
createEventDispatcher → callback props review marker
<slot> and named slots → {@render children?.()} / {@render name?.()}
on:click={handler} → onclick={handler}
let: directives → snippet-prop review markers
onMount / onDestroy → $effect() review marker
beforeUpdate / afterUpdate → $effect.pre() review marker
svelte/store writable / derived usage → manual-review warning for shared stores and subscriptions
class:active={isActive} → class={isActive ? "active" : ""}
export const in instance scripts → <script module> exports
<svelte:options immutable/accessors> → modern API review marker

Option	Description
`--dry-run`	Show changes without modifying files
`--diff`	Output unified diff for proposed changes
`--interactive`	Show each file diff and ask before applying (`y`, `n`, `a`, `q`)
`--plan`	Report total files, auto-migratable files, manual-review files, and top issue categories without writing files
`--commit-stages`	Run supported migration stages and create one git commit per stage
`--rollback`	Restore files from `.svelte.bak` backups and remove the backup files
`--no-backup`	Skip creating `.svelte.bak` backup files
`--stage <name>`	Run only one stage: `reactive-statement`, `export-let`, `event-dispatcher`, `slot`, `on-directive`, `lifecycle`, `let-directive`, `store`, `class-directive`, `module-export`, `snippet`, or `svelte-options`
`--json`	Output machine-readable JSON

Examples:

# Preview all changes as a patch without writing files
svelte-doctor migrate --dry-run --diff > migration.patch

# Get a migration plan for CI or rollout estimation
svelte-doctor migrate --plan
svelte-doctor migrate --plan --json

# Review and accept each file interactively
svelte-doctor migrate --interactive

# Apply only one stage
svelte-doctor migrate --stage export-let

# Restore from backups created by the default migration mode
svelte-doctor migrate --rollback

`svelte-doctor migrate-status [directory] [options]`

Show Svelte 4 to 5 migration progress without modifying files. The command scans .svelte files for pending legacy patterns and reports migrated, pending, and skipped file counts, category-specific progress, and an estimated remaining time.

Tracked categories:

reactive statements ($:)
export let props
legacy <slot> usage
on:event directives

Option	Description
`--json`	Output machine-readable JSON

Examples:

svelte-doctor migrate-status
svelte-doctor migrate-status --json

`svelte-doctor suggest-ignore [directory] [options]`

Generate smart ignore suggestions for diagnostics that are likely false positives or low-risk noise. Each suggestion includes a confidence score, the reason it was flagged, and an ignore config snippet you can review before copying into svelte-doctor.config.json.

This is intentionally advisory. It does not write config automatically.

Option	Description
`--json`	Output machine-readable JSON with suggestions and config

Examples:

svelte-doctor suggest-ignore
svelte-doctor suggest-ignore --json

`svelte-doctor graph [directory] [options]`

Build a component dependency graph from local imports and rendered component tags. The graph helps answer which component imports or renders another component and highlights circular dependencies. Imports through SvelteKit's $lib alias and custom tsconfig.json compilerOptions.paths aliases are resolved, alongside relative and re-export specifiers.

Option	Description
`--format <ascii\|dot\|json>`	Output format, defaults to `ascii`

Examples:

svelte-doctor graph
svelte-doctor graph --format dot > graph.dot
svelte-doctor graph --format json

`svelte-doctor where-used <component> [directory] [options]`

Find every place a component is imported or rendered, with line-accurate locations and source snippets. Useful for impact analysis before refactoring or removing a component.

The <component> argument accepts a component name (Button) or a full project-relative path (src/lib/Button.svelte). Multiple components can be passed comma-separated (Button,Card,Modal).

Option	Description
`--json`	Output machine-readable JSON
`--type <import\|render>`	Restrict to import or render usages
`--scope <path>`	Restrict results to files under a subdirectory
`--direction <used-by\|uses>`	`used-by` (default) finds who uses the component; `uses` finds what it depends on
`--tree`	Render the parent render hierarchy as an ASCII tree rooted at entry points

Ambiguous component names (for example src/lib/Button.svelte and src/ui/Button.svelte) produce an error listing the candidates so you can disambiguate with the full path. Re-exports (export { default as Button } from ...) and string-literal dynamic imports (await import("...")) are reported as import usages. Imports through SvelteKit's $lib alias (default $lib -> src/lib) and custom tsconfig.json compilerOptions.paths aliases ($components/*, @/*, etc.) are resolved automatically, so SvelteKit projects report import usages the same way relative imports do.

Examples:

# who uses Button?
svelte-doctor where-used Button

# full path query
svelte-doctor where-used src/lib/Button.svelte

# CI / automation output
svelte-doctor where-used Button --json

# multiple components
svelte-doctor where-used Button,Card,Modal

# only render sites
svelte-doctor where-used Button --type render

# render tree of parents leading to Button
svelte-doctor where-used Button --tree

# scope to a subdirectory
svelte-doctor where-used Button --scope src/pages

# reverse: what does Button depend on?
svelte-doctor where-used Button --direction uses

`svelte-doctor dead-stores [directory] [options]`

Detect writable stores that are never written to anywhere in the project. A writable that is only ever read should be a readable store or migrated to Svelte 5 runes $state. This is especially useful when migrating a codebase from stores to runes: it identifies stores that can be safely converted to read-only values without changing any write sites.

The analysis is cross-file: it tracks .set(), .update(), this.store.set() in classes, and $store = auto-subscription writes in .svelte templates, resolving imports and re-exports back to the original declaration. Stores that are written in any file are reported as OK with their write sites listed.

Option	Description
`--json`	Output machine-readable JSON

Examples:

# full dead store report
svelte-doctor dead-stores

# CI / automation output
svelte-doctor dead-stores --json

# scan a specific workspace
svelte-doctor dead-stores packages/app

Sample text output:

  Dead store report: 1 never-written, 1 ok, 2 total

  Never written (candidates for readable or $state):

  user - writable - NEVER WRITTEN (src/stores/user.ts:2)
  Used in ($-auto-subscribe, 1):
    src/routes/+page.svelte:7           $currentUser
  Replace with: replace `user` with a `readable` store (read-only contract) or migrate to runes `$state` and expose via props

  Written (OK):

  counter - writable - WRITTEN (src/stores/counter.ts:2)
  Written in 2 places:
    src/routes/+page.svelte:5           $counter =
    src/stores/counter.ts:3             counter.set()

`svelte-doctor bundle-impact [directory] [options]`

Estimate potential bundle savings from fixable bundle-size diagnostics. Current estimates cover heavy imports such as moment, full lodash, and wildcard icon package imports.

Option	Description
`--json`	Output machine-readable JSON

Examples:

svelte-doctor bundle-impact
svelte-doctor bundle-impact --json

`svelte-doctor test-gaps [directory] [options]`

Find source files that do not have a nearby matching test file. It also marks critical SvelteKit paths, such as server load modules and form actions, so CI can prioritize missing tests for production-sensitive code.

Option	Description
`--json`	Output machine-readable JSON

Examples:

svelte-doctor test-gaps
svelte-doctor test-gaps --json

`svelte-doctor create-rule <name> [directory] [options]`

Scaffold a custom rule package with a rule template, test template, and docs template. Rule names must be kebab-case, for example no-custom-pattern. Existing files are never overwritten.

Generated files:

src/rules/custom/<name>/index.ts
src/rules/custom/<name>/README.md
test/<name>.test.mjs

Option	Description
`--json`	Output machine-readable JSON

Examples:

svelte-doctor create-rule no-custom-pattern
svelte-doctor create-rule no-custom-pattern --json

`svelte-doctor render-profile [directory] [options]`

Analyze Svelte components before runtime and rank the most expensive render surfaces. The profiler parses and compiles each .svelte file, then combines AST and compiled-output signals into a deterministic render cost model.

Per component metrics:

DOM node count
reactive dependency count
hydration complexity score
re-render risk factor
compiled output size
aggregate render cost

The default terminal output lists the top 10 most expensive components. --watch re-runs the profile when .svelte files change and shows cost deltas, which helps catch render-cost regressions before a build reaches production.

Option	Description
`--json`	Output machine-readable JSON
`--top <count>`	Number of expensive components to show, defaults to 10
`--watch`	Watch `.svelte` files and show render cost changes

Examples:

svelte-doctor render-profile
svelte-doctor render-profile --top 5
svelte-doctor render-profile --watch
svelte-doctor render-profile --json

`svelte-doctor watch [directory] [options]`

Watch for file changes and show live diagnostics. Runs an initial cached scan, then incrementally re-scans only changed files with 150ms debounced updates.

Option	Description
`--dead-code <mode>`	Dead-code behavior in watch mode: `off`, `lazy`, or `full`

[12:34:56] src/Component.svelte changed — Score: 82 → 78 (⚠ 2 issues)
[12:34:59] src/Layout.svelte changed — Score: 78 → 80 (✓ score improved +2)

`svelte-doctor trend [directory] [options]`

Show score history and trend over time. Every check run automatically saves the score to .svelte-doctor/history.json. The trend command visualizes this data as a terminal bar chart.

Monorepos can also query the latest trend snapshot per workspace with --all-workspaces or --workspace <name>.

`svelte-doctor rules [directory]`

List every rule with its category and whether it supports deterministic autofix. Rules are grouped by source (built-in, plugin, or local), so custom rules appear alongside the built-ins.

`svelte-doctor explain <rule> [directory] [options]`

Explain what a rule checks, why it matters, and what the safest remediation looks like. With --fix, shows before/after code examples and scans the project for occurrences that would be fixed — use it as a learning and discovery tool before running apply --write on the entire codebase.

Rules with deterministic fixes show an interactive apply prompt after listing occurrences. AI-only rules (like no-giant-component or too-many-effects) show examples but do not offer automatic apply since they require manual judgment.

Option	Description
`--fix`	Show fix examples and scan project for matching occurrences
`--json`	Output machine-readable JSON (combine with `--fix` for full fix data)

Examples:

# Basic rule explanation
svelte-doctor explain no-transition-all

# Explain with fix examples and scan
svelte-doctor explain no-transition-all --fix

# Machine-readable output with occurrence data
svelte-doctor explain no-moment --fix --json

# Scan a specific workspace
svelte-doctor explain no-full-lodash packages/app --fix

`svelte-doctor deps [directory] [options]`

Check dependency health for Svelte ecosystem compatibility. Fully offline — no network requests.

Checks:

Deprecated packages — sapper, svelte-routing, svelte-preprocess, etc.
Svelte 5 compatibility — packages not updated for runes/snippets
Risky version ranges — * or latest dependencies
Better alternatives — axios → fetch, moment → dayjs, lodash → lodash-es

Option	Description
`--json`	Output machine-readable JSON

`svelte-doctor upgrade [directory] [options]`

Check project dependencies against the npm registry and prepare safe upgrade suggestions. By default, major upgrades are excluded. Use --dry-run to report without touching package.json; without --dry-run, accepted suggestions are written atomically and the detected package manager runs install.

The upgrade plan includes current version, lockfile-resolved version when available, latest version, wanted range, dependency block, major/minor/patch classification, deprecation signal, replacement alternative when known, breaking-change flag, changelog/repository URL when available, and risk score.

Option	Description
`--dry-run`	Report upgrades without writing `package.json` or lockfile
`--interactive`	Ask before applying each package upgrade (`y`, `n`, `a`, `q`)
`--major`	Include major-version upgrades
`--json`	Output machine-readable JSON
`--all-workspaces`	Check every package.json workspace
`--workspace <name>`	Check one workspace by name or relative path

Examples:

svelte-doctor upgrade --dry-run
svelte-doctor upgrade --dry-run --major
svelte-doctor upgrade --json
svelte-doctor upgrade --all-workspaces --dry-run

`svelte-doctor pr-check [directory] [options]`

Analyze a branch diff for PR or CI feedback. The command lists files changed between --base and --head, scans isolated git worktrees for both refs, builds a Markdown PR summary, and can post that summary or review to GitHub with the gh CLI. When posting to GitHub, it also writes a svelte-doctor commit status for required-check workflows.

Option	Description
`--pr <number>`	Pull request number for comment posting
`--base <branch>`	Base branch or ref (default: `main`)
`--head <branch>`	Head branch or ref (default: `HEAD`)
`--comment`	Post a summary comment via GitHub CLI
`--inline`	Submit a GitHub PR review with the generated summary
`--fail-on <never\|error\|warning>`	Control exit behavior for new issues
`--min-score <score>`	Fail if PR score is below the threshold
`--json`	Output machine-readable JSON
`--platform <github\|gitlab\|bitbucket\|auto>`	Select PR platform adapter mode
`--token <env-var>`	Token environment variable name (default: `GITHUB_TOKEN`)

Examples:

svelte-doctor pr-check --base main --head HEAD
svelte-doctor pr-check --base origin/main --head HEAD --min-score 80
svelte-doctor pr-check --pr 42 --comment --platform github
svelte-doctor pr-check --json

`svelte-doctor update [options]`

Checks the official npm registry for the latest svelte-doctor version and updates the global CLI installation. This command does not update local project dependencies.

Option	Description
`--check`	Check for an update without installing
`--dry-run`	Print the global install command without running it
`--manager <npm	pnpm
`--tag <latest>`	Release tag to install (`latest` only)
`--json`	Output machine-readable JSON

`svelte-doctor quick [directory] [options]`

Fast error-only scan with health score. Runs a lint scan with cache enabled and dead-code detection disabled for maximum speed. Only error-level diagnostics are reported, making it ideal for quick pre-commit checks or rapid feedback during development.

Option	Description
`--json`	Output machine-readable JSON
`--score`	Output only the numeric score

Examples:

svelte-doctor quick
svelte-doctor quick --score
svelte-doctor quick packages/app --json

`svelte-doctor compare [directory] [options]`

Compare diagnostics between two git refs (commits, branches, tags). Creates temporary git worktrees for both refs, runs independent scans, and reports the score delta along with newly introduced and fixed diagnostics. The comparison is symmetric: it shows both what got worse and what improved.

Option	Description
`--base <ref>`	Base git ref (commit, branch, tag) (default: `main`)
`--head <ref>`	Head git ref (default: `HEAD`)
`--json`	Output machine-readable JSON

Git refs are validated for injection-safe characters. Temporary worktrees are created in the OS temp directory and cleaned up automatically, even on scan failure.

Examples:

svelte-doctor compare --base main --head HEAD
svelte-doctor compare --base v1.0.0 --head v2.0.0
svelte-doctor compare --base HEAD~5 --head HEAD --json
svelte-doctor compare --base origin/main --head feature/xyz

`svelte-doctor stats [directory] [options]`

Show project metrics including total diagnostics by severity, category breakdown with error/warning counts and penalty weights, most frequently triggered rules, and most affected files. Useful for identifying systemic patterns and prioritizing cleanup efforts.

Option	Description
`--json`	Output machine-readable JSON
`--top <count>`	Number of top items to show per list (default: `10`)

Examples:

svelte-doctor stats
svelte-doctor stats --top 5
svelte-doctor stats --json
svelte-doctor stats --top 3 --json

`svelte-doctor audit [directory] [options]`

Security-focused scan that runs the full lint pipeline but filters results to only the Security category. Computes a dedicated security score from the filtered diagnostics. Useful for compliance checks, security reviews, and CI gates that focus exclusively on security posture.

Option	Description
`--json`	Output machine-readable JSON
`--score`	Output only the security score

Security rules include XSS via {@html}, hardcoded secrets, eval() usage, insecure cookies, broad CORS, shell injection, server secret leaks, dangerous redirect parameters, public env secret imports, external links without rel="noopener", and raw error details exposed to clients.

Examples:

svelte-doctor audit
svelte-doctor audit --score
svelte-doctor audit --json
svelte-doctor audit packages/api --json

`svelte-doctor config [directory] [options]`

Display the active svelte-doctor configuration. Reads from svelte-doctor.config.json first, then falls back to the "svelte-doctor" key in package.json. Shows all active settings including lint, dead-code, cache, watch, fix, reports, and ignore rules.

Option	Description
`--json`	Output machine-readable JSON
`--path`	Show only the config file path

Examples:

svelte-doctor config
svelte-doctor config --json
svelte-doctor config --path

`svelte-doctor validate [directory] [options]`

Validate the svelte-doctor.config.json file for syntax and schema errors. Checks for invalid JSON syntax, unknown top-level and nested keys, type mismatches (e.g., string where boolean expected), invalid enum values (e.g., watch.deadCode, fix.verifyLevel), empty report paths, and malformed ignore lists with non-string elements.

Option	Description
`--json`	Output machine-readable JSON

Validation covers:

Unknown keys at all nesting levels
Type checks for lint, deadCode, cache, watch, fix, reports, ignore
Enum validation for watch.deadCode (off/lazy/full), fix.verifyLevel (diagnostics/typecheck/tests/full)
Numeric bounds for fix.maxFiles (must be positive)
Path validation for reports.html, reports.junit, reports.markdown (must be non-empty strings)
Array validation for ignore.rules and ignore.files (must be arrays of non-empty strings)
Symlink detection — refuses to validate symlinked config files

Examples:

svelte-doctor validate
svelte-doctor validate --json
svelte-doctor validate packages/app

`svelte-doctor reset [directory] [options]`

Clean generated files (cache, baseline, score history) inside .svelte-doctor/. Useful when cache gets corrupted, baseline becomes stale, or you want to start fresh without manually deleting files.

By default (no flags), all generated files are removed and the .svelte-doctor/ directory is cleaned up if empty afterwards.

Option	Description
`--all`	Clean everything in `.svelte-doctor/` (default if no flag)
`--cache`	Clean only scan cache
`--baseline`	Clean only baseline
`--history`	Clean only score history
`--dry-run`	Show what would be deleted without deleting
`--json`	Output machine-readable JSON

Examples:

svelte-doctor reset
svelte-doctor reset --dry-run
svelte-doctor reset --cache
svelte-doctor reset --baseline --history
svelte-doctor reset --all --json

Plugins & Community Rules

svelte-doctor is extensible. Beyond the built-in rules you can add custom rules and community plugins without forking the CLI. Every custom rule plugs into the same engine: it is linted, scored, cached, ignored, and fixed (when it exposes a fix) exactly like a built-in rule, and its origin is recorded on every diagnostic.

Full authoring guide, API reference, and the security model are in docs/plugins.md. Read the security section before adopting third-party plugins in CI.

Security model (summary)

npm plugins are not auto-executed. A svelte-doctor-plugin-* dependency is only loaded when you list it under plugins.include (or opt into plugins.autoDiscoverNpm, which is off by default). This prevents a compromised or typosquatted dependency from running code during your scan.
Local rules are trusted. Files under svelte-doctor.rules/ are auto-loaded (same trust boundary as your source) but are validated and confined to the project root.
Kill-switch: set SD_DISABLE_PLUGINS=1 (or plugins: false) for built-in rules only.
Isolation: a plugin that throws during check/fix becomes a warning and never aborts the run.
Namespacing: each custom rule gets a stable id <namespace>/<rule> (e.g. svelte-doctor-plugin-a11y-plus/no-broken-anchor), so plugins can never silently collide and every diagnostic records its exact origin.

Authoring a local rule

The fastest path is create-rule, which scaffolds a runtime-loadable rule under svelte-doctor.rules/. The folder is auto-discovered on every scan, so no wiring is required.

svelte-doctor create-rule no-custom-pattern

Generated file (svelte-doctor.rules/no-custom-pattern.mjs):

/**
 * @type {import("svelte-doctor").Rule}
 */
export default {
  name: "no-custom-pattern",
  category: "Correctness",
  severity: "warning",
  message: "Custom pattern detected",
  help: "Replace this placeholder with actionable guidance.",
  check: (ctx) => {
    const diagnostics = [];
    // ctx exposes filePath, source, lines, ast, scriptBlocks, projectInfo
    return diagnostics;
  },
  // optional: fix: (source, diagnostic) => string
};

A rule receives a RuleContext and returns Diagnostic[]. Supported export shapes: a single default-exported Rule, a default-exported plugin object { name, rules }, a named svelteDoctorPlugin export, or a default-exported array of Rule. The package exports defineRule, definePlugin, and validateRule helpers for author-time validation.

Configuration

// svelte-doctor.config.json
{
  "plugins": {
    "enabled": true,
    "include": ["svelte-doctor-plugin-a11y-plus", "@my-org/svelte-doctor-plugin-internal"],
    "exclude": ["legacy-plugin"],
    "autoDiscoverNpm": false,
    "local": ["svelte-doctor.rules/**/*.{mjs,js,cjs}"],
  },
}

enabled — set false to disable all plugins/local rules
include — npm plugin package names to load (the recommended, auditable way to adopt plugins)
exclude — package names to disable entirely
autoDiscoverNpm — when true, every svelte-doctor-plugin-* dependency is executed (off by default)
local — globs for runtime-loadable local rule files (default: svelte-doctor.rules/**/*.{mjs,js,cjs})

Rule ids are namespaced, so two plugins can never collide. Malformed plugin rules are reported as warnings and never crash a scan.

Browsing the catalog

svelte-doctor ships a central, offline catalog of community plugins. It is contributable: open a pull request to add an entry.

svelte-doctor registry list
svelte-doctor registry search a11y
svelte-doctor registry info a11y-plus
svelte-doctor registry add a11y-plus        # installs via your package manager (does not auto-enable)
svelte-doctor registry add a11y-plus --dry-run

Inspecting what is loaded

svelte-doctor plugins            # plugins + local rule folders, with source/version/entry paths
svelte-doctor plugins --json
svelte-doctor rules              # all rules, grouped by built-in / plugin / local
svelte-doctor explain <rule>     # shows the namespaced id and source plugin

Rules (69 source rules + 3 build artifact diagnostics)

Correctness (10)

Rules in this category only fire in runes-mode projects (projects that use $state, $derived, $effect, or $props). They flag Svelte 4 patterns that are broken or deprecated in Svelte 5.

Rule	Severity	Description
`no-legacy-reactive`	error	`$:` reactive statements → `$derived` / `$effect` (fixable)
`no-legacy-lifecycle`	error	`onMount`/`onDestroy` imports → `$effect` (fixable)
`no-export-let`	error	`export let` → `$props()` (fixable)
`no-event-dispatcher`	error	`createEventDispatcher` → callback props (fixable)
`no-legacy-slots`	error	`<slot>` → `{@render children()}` (fixable)
`no-let-directive`	error	`let:` directive → snippet props (fixable)
`no-on-directive`	warning	`on:event` → `onevent` attributes (fixable)
`no-$inspect-in-production`	error	`$inspect()` debug rune should not reach production
`no-$state-frozen-misuse`	warning	`.push()` or `.splice()` on `$state.frozen()` objects
`no-class-instance-as-$state`	warning	Class instance passed to `$state()` breaks fine-grained reactivity

Performance (21)

Rule	Severity	Description
`no-effect-for-derived`	warning	`$effect` used where `$derived` fits (fixable)
`each-missing-key`	warning	`{#each}` without key expression
`no-inline-object`	warning	Inline objects/arrays in template expressions
`no-transition-all`	warning	`transition: all` is expensive (fixable)
`no-large-inline-list-transform`	warning	Expensive `.filter().map().sort()` chains in template markup
`no-repeated-derived-allocation`	warning	Repeated allocations inside `$derived()`
`no-blocking-sync-fs-in-hot-cli-path`	warning	Sync fs calls in hot scan paths
`prefer-lazy-deadcode-phase`	warning	Full dead-code scans configured in fast feedback paths
`too-many-effects`	warning	Compiler output contains many reactive effects in one component
`effect-without-cleanup`	warning	`$effect` registers listeners, timers, or subscriptions without cleanup
`derived-with-side-effect`	warning	`$derived` contains DOM, storage, timer, or network side effects
`deep-template-tree`	warning	Compiled template is deeply nested and may mount/hydrate slowly
`no-hydration-mismatch-template-values`	warning	Template uses browser-only, random, or time-based values that can mismatch SSR
`no-inline-event-handler`	warning	Inline event handler creates a new function reference
`no-expensive-derived`	warning	`$derived` performs heavy parsing, sorting, regex, or repeated filtering
`no-high-specificity`	warning	CSS selector specificity is too high
`no-deep-css-nesting`	warning	CSS selector nesting is too deep
`no-id-selector`	warning	ID selector creates high specificity in component styles
`no-important-override`	warning	CSS uses `!important` override
`no-style-tag-props`	warning	Inline style attribute can conflict with CSP and maintainability
`prefer-snippet-over-passed-function`	warning	Function prop where `{#snippet}` + `{@render}` should be used

Architecture (4)

Rule	Severity	Description
`no-giant-component`	warning	Component exceeds 300 lines
`no-deep-nesting`	warning	More than 3 levels of template block nesting
`no-console`	warning	`console.*` left in components
`no-multi-script`	warning	Multiple instance `<script>` blocks

Security (11)

Rule	Severity	Description
`no-unsafe-html`	error	`{@html}` is an XSS vector
`no-secrets`	error	Hardcoded API keys / tokens
`no-eval`	error	`eval()` usage
`no-public-env-secrets`	error	Secrets imported from public `$env` modules
`no-dangerous-redirect-param`	error	Redirect target comes from untrusted query data
`cookie-missing-secure-flags`	error	`cookies.set()` missing `httpOnly` / `secure` / `sameSite`
`no-broad-cors`	error	Wildcard CORS or wildcard+credentials configuration
`no-server-secret-leak`	error	Private env vars returned from server code
`no-unsafe-shell`	error	`exec`, `execSync`, or `spawn(..., { shell: true })`
`no-plain-external-anchor`	warning	External `<a>` link missing `rel="noopener noreferrer"`
`no-exposed-error-details`	error	Raw `error.message` or `error.stack` returned to client

SvelteKit (10)

Rule	Severity	Description
`no-client-fetch`	warning	`fetch` in component scripts → use `load` functions
`load-missing-type`	warning	Load function without type annotation (TypeScript only)
`no-goto-external`	warning	`goto()` with external URLs
`form-action-no-validation`	warning	Form actions without input validation
`missing-error-page`	warning	No `+error.svelte` found
`server-load-missing-error-guard`	warning	Server load uses remote fetch without obvious error handling
`form-action-missing-auth-check`	warning	Form actions mutate without an obvious auth/session check
`no-missing-prefetch`	warning	Navigation link missing `data-sveltekit-prefetch`
`no-form-action-without-redirect`	warning	POST form action missing `redirect()` after mutation
`no-non-serializable-load-return`	error	Server load returns non-serializable value (function, class)

Bundle Size (4 source rules + 3 build artifact diagnostics)

Rule	Severity	Description
`no-barrel-import`	warning	Barrel imports prevent tree-shaking
`no-full-lodash`	warning	Full `lodash` import (~70kb) (fixable)
`no-moment`	warning	`moment.js` is heavy (~300kb) (fixable)
`no-full-icon-import`	warning	Wildcard icon imports prevent tree-shaking (fixable)
`chunk-size-limit`	warning	Build output chunk exceeds recommended size limit
`no-duplicate-lib-in-chunks`	warning	Same package appears across multiple generated chunks
`prefer-dynamic-import`	warning	Large dependency appears in an eagerly loaded build chunk
`no-base64-inline-asset`	warning	Build output contains inline base64 image data

Accessibility (3)

Rule	Severity	Description
`img-missing-alt`	warning	`<img>` without `alt` attribute
`click-needs-keyboard`	warning	Click handler on non-interactive element without keyboard support
`anchor-no-content`	warning	`<a>` without text content or `aria-label`

State & Reactivity (6)

Rule	Severity	Description
`no-unnecessary-state`	warning	`$state` wrapping a value that is never mutated (fixable)
`no-derived-side-effect`	error	Side effects inside `$derived`
`prefer-runes`	warning	`svelte/store` imports in a runes-mode project
`no-unwritten-store`	warning	`writable` store that is never written via `.set()`, `.update()` or `$store =`
`no-mixed-runes-and-stores`	warning	Both `$state`/`$derived` and `svelte/store` used in the same component
`no-unnecessary-derived-dependency`	warning	`$derived()` reads no reactive state — should be a plain `const`

Node.js API

import { diagnose } from "svelte-doctor/api";

const result = await diagnose("./path/to/your/svelte-project");

console.log(result.score); // { score: 82, label: "Good" }
console.log(result.diagnostics); // Diagnostic[]
console.log(result.project); // ProjectInfo

Configuration

Create svelte-doctor.config.json in your project root:

{
  "ignore": {
    "rules": ["no-console"],
    "files": ["src/legacy/"]
  },
  "lint": true,
  "deadCode": true,
  "cache": true,
  "watch": {
    "deadCode": "off"
  },
  "fix": {
    "verifyLevel": "diagnostics",
    "maxFiles": 50
  },
  "reports": {
    "html": ".svelte-doctor/report.html",
    "junit": ".svelte-doctor/junit.xml",
    "markdown": ".svelte-doctor/report.md"
  }
}

The reports block writes reports on every check run, even without --html, --junit, or --markdown flags. This also applies to workspace scans, where reports are written at the root project and include all prefixed workspace diagnostics. Report writes are symlink-hardened and create parent directories when needed.

Or add a "svelte-doctor" key in package.json:

{
  "svelte-doctor": {
    "ignore": {
      "rules": ["no-console"]
    }
  }
}

License

This project has been developed under the Apache License 2.0.

Built by Pimatis

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.codegraph		.codegraph
.github/workflows		.github/workflows
assets/logos		assets/logos
docs		docs
src		src
test		test
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
eslint.config.mjs		eslint.config.mjs
package.json		package.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

svelte-doctor

Overview

Key Features

Installation

Global Installation (Recommended)

Local Installation

Usage

Commands

svelte-doctor doctor [directory] [options]

svelte-doctor init [directory] [options]

svelte-doctor install-hook [directory] [options]

svelte-doctor check [directory] [options]

svelte-doctor baseline [directory]

svelte-doctor apply [directory] [options]

svelte-doctor fix [directory] [options]

svelte-doctor migrate [directory] [options]

svelte-doctor migrate-status [directory] [options]

svelte-doctor suggest-ignore [directory] [options]

svelte-doctor graph [directory] [options]

svelte-doctor where-used <component> [directory] [options]

svelte-doctor dead-stores [directory] [options]

svelte-doctor bundle-impact [directory] [options]

svelte-doctor test-gaps [directory] [options]

svelte-doctor create-rule <name> [directory] [options]

svelte-doctor render-profile [directory] [options]

svelte-doctor watch [directory] [options]

svelte-doctor trend [directory] [options]

svelte-doctor rules [directory]

svelte-doctor explain <rule> [directory] [options]

svelte-doctor deps [directory] [options]

svelte-doctor upgrade [directory] [options]

svelte-doctor pr-check [directory] [options]

svelte-doctor update [options]

svelte-doctor quick [directory] [options]

svelte-doctor compare [directory] [options]

svelte-doctor stats [directory] [options]

svelte-doctor audit [directory] [options]

svelte-doctor config [directory] [options]

svelte-doctor validate [directory] [options]

svelte-doctor reset [directory] [options]

Plugins & Community Rules

Security model (summary)

Authoring a local rule

Configuration

Browsing the catalog

Inspecting what is loaded

Rules (69 source rules + 3 build artifact diagnostics)

Correctness (10)

Performance (21)

Architecture (4)

Security (11)

SvelteKit (10)

Bundle Size (4 source rules + 3 build artifact diagnostics)

Accessibility (3)

State & Reactivity (6)

Node.js API

Configuration

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

`svelte-doctor doctor [directory] [options]`

`svelte-doctor init [directory] [options]`

`svelte-doctor install-hook [directory] [options]`

`svelte-doctor check [directory] [options]`

`svelte-doctor baseline [directory]`

`svelte-doctor apply [directory] [options]`

`svelte-doctor fix [directory] [options]`

`svelte-doctor migrate [directory] [options]`

`svelte-doctor migrate-status [directory] [options]`

`svelte-doctor suggest-ignore [directory] [options]`

`svelte-doctor graph [directory] [options]`

`svelte-doctor where-used <component> [directory] [options]`

`svelte-doctor dead-stores [directory] [options]`

`svelte-doctor bundle-impact [directory] [options]`

`svelte-doctor test-gaps [directory] [options]`

`svelte-doctor create-rule <name> [directory] [options]`

`svelte-doctor render-profile [directory] [options]`

`svelte-doctor watch [directory] [options]`

`svelte-doctor trend [directory] [options]`

`svelte-doctor rules [directory]`

`svelte-doctor explain <rule> [directory] [options]`

`svelte-doctor deps [directory] [options]`

`svelte-doctor upgrade [directory] [options]`

`svelte-doctor pr-check [directory] [options]`

`svelte-doctor update [options]`

`svelte-doctor quick [directory] [options]`

`svelte-doctor compare [directory] [options]`

`svelte-doctor stats [directory] [options]`

`svelte-doctor audit [directory] [options]`

`svelte-doctor config [directory] [options]`

`svelte-doctor validate [directory] [options]`

`svelte-doctor reset [directory] [options]`