![\"svelte-doctor](\"assets/logos/logo.png\"){kind=logo}
\n\n \n
\n Diagnose and fix performance, correctness, and architecture issues in your Svelte codebase\n
\n\n\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Commands](#commands)\n- [Configuration](#configuration)\n- [Plugins & Community Rules](#plugins--community-rules)\n- [Rules](#rules)\n- [Node.js API](#nodejs-api)\n- [License](#license)\n\n---\n\n## Overview\n\n`svelte-doctor` is a comprehensive diagnostic CLI for Svelte and SvelteKit projects. It analyzes your codebase for security vulnerabilities, performance bottlenecks, architectural issues, and Svelte 4-to-5 migration patterns — then reports everything as a single **0–100 health score** with actionable, line-specific diagnostics.\n\nRun one command to scan your entire project:\n\n```bash\nsvelte-doctor check\n```\n\nThe tool is designed to be **safe by default**: deterministic fixes are opt-in, AI agents run in a controlled flow, and CI integration is a first-class citizen (SARIF, GitHub annotations, baseline suppression, and PR checks).\n\n---\n\n## Key Features\n\n### Diagnostics & Scanning\n\n- **93 source diagnostic rules + 3 build artifact diagnostics** covering correctness, performance, security, architecture, SvelteKit reliability, runtime performance, hydration safety, CSS specificity, and accessibility\n- **0–100 health score** with actionable, line-specific diagnostics on every scan\n- **TypeScript AST-backed script analysis** for lower false-positive rates on security-sensitive checks\n- **Accessibility autofix and suggestions** with automatic decorative-image `alt=\"\"` fixes and contextual ARIA snippets for manual decisions\n- **Cached scans + incremental watch** for faster repeat checks and tighter feedback loops, with `watch --fix` auto-applying deterministic fixes on save\n- **Incremental checks** with `check --incremental` to scan only changed tracked and untracked files in large projects\n- **Diff-aware and workspace-aware scans** for staged files, changed files, and monorepos\n- **Parallel scanning** with `--jobs` for multi-worker file scanning in large codebases, with automatic CPU detection (`--jobs 0`)\n- **Focused scan modes** — `quick` (error-only), `audit` (security-only), `compare` (regression analysis), `stats` (project metrics), `metrics` (command durations, rule gains, technical debt)\n\n### Fixing & Migration\n\n- **Deterministic Safe Apply** via `apply` — covers CSS transitions, lodash/moment/icon imports, Svelte 4→5 migration, unnecessary `$state` wrappers, and `$effect` → `$derived` conversions\n- **Svelte 4→5 AST-backed auto-migration** with modular codemods, plan/diff/interactive modes, backups, rollback, staged commits, JSON output, and `.svelte.js` / `.svelte.ts` module file support\n- **Migration progress tracking** via `migrate-status` with migrated/pending/skipped counts, category breakdown, and ETA\n- **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\n\n### CI & Workflows\n\n- **Baseline suppression** to keep legacy issues out of new CI failures\n- **Managed Git hooks** via `install-hook` for automatic pre-commit and pre-push quality gates\n- **SARIF + GitHub annotations** for code scanning and CI integration\n- **PR Check workflow** for branch diff analysis and GitHub PR summary comments\n- **Ref comparison** via `compare` for diagnosing regressions between commits, branches, and tags\n- **Dependency health checks and upgrade planning** for ecosystem compatibility and npm registry updates\n\n### Insights & Reporting\n\n- **Component dependency graphs** via `graph` with ASCII, DOT, JSON, alias resolution, and circular dependency detection\n- **Component where-used lookup** via `where-used` with line-accurate import/render locations, `$lib` and tsconfig alias resolution, dynamic import detection, render trees, scope filtering, and reverse direction\n- **Bundle impact preview** via `bundle-impact` for estimated savings from fixable bundle-size diagnostics\n- **Dead store detection** via `dead-stores` for `writable` stores never written, with cross-file write tracking and runes migration suggestions\n- **Bundle-aware dead code detection** for unused function exports, unused components imported by `+page.svelte`, and tree-shaking compatibility risks\n- **Test coverage gap finder** via `test-gaps` for source-to-test matching and SvelteKit critical path checks\n- **Component render profiler** via `render-profile` for compile-time DOM, reactivity, hydration, and re-render cost ranking\n- **Performance budgets** with estimated LCP/CLS risk, excessive store/reactive subscription warnings, and derived-state render cost estimation\n- **Server-side code detection** for client runes in server-only routes, with universal and server-only rule filtering\n- **Score history and trends** via `trend` and live feedback via `watch`\n\n### Automation & DX\n\n- **Zero configuration** — works out of the box\n- **Interactive project bootstrap** via `init` for config, CI, scripts, baseline, and `.gitignore` setup\n- **Single-command scan + fix** via `check --fix`, with `--interactive` for step-by-step approval\n- **AI-friendly copy export** via `check --copy` with clipboard-first fallback behavior\n- **Smart ignore suggestions** via `suggest-ignore` with confidence scoring and generated config snippets\n- **Rule authoring kit** via `create-rule` for custom rule, test, and docs scaffolding\n- **Environment diagnosis** via `doctor` with `--fix` to auto-resolve config, gitignore, and dependency issues\n- **Lazy-loaded commands** — each subcommand's module loads only when invoked, keeping CLI startup fast\n- **Script-friendly output** — with `--json`, stdout carries only machine-readable JSON (human-readable logs go to stderr)\n- **Automatic `.gitignore` sync** for generated `.svelte-doctor/*` cache/history files while preserving tracked baseline negations\n- **Generated file cleanup** via `reset` to safely clear cache, baseline, and history\n\n---\n\n## Quick Start\n\nGet a health score for your project in under a minute:\n\n```bash\n# 1. Install the CLI globally (or skip this and use npx / bunx)\nbun i -g svelte-doctor # or: npm install -g svelte-doctor\n\n# 2. Scan your project\nsvelte-doctor check\n\n# 3. Bootstrap config, CI, and git hooks (recommended)\nsvelte-doctor init --yes --ci github-actions\nsvelte-doctor install-hook --mode staged --fail-on error\n```\n\nRequires **Node.js 22.18.0+** — see [Installation](#installation) for details.\n\n---\n\n## Installation\n\n**Runtime requirement:** Node.js `22.18.0+`. If you are on Node 18 or Node 20, upgrade Node before installing or building `svelte-doctor`.\n\n### Global Installation (Recommended)\n\nInstall `svelte-doctor` globally to use it from anywhere in your terminal:\n\n```bash\n# Using bun (recommended)\nbun i -g svelte-doctor\n\n# Using npm\nnpm install -g svelte-doctor\n\n# Using pnpm\npnpm add -g svelte-doctor\n```\n\n**Add to PATH (required for first-time setup):**\n\nIf you get a `command not found` error after installation, add the global bin folder to your PATH.\n\n**macOS / Linux:**\n\n```bash\n# For Bun users\necho 'export PATH=\"$HOME/.bun/bin:$PATH\"' >> ~/.zshrc # or ~/.bashrc\nsource ~/.zshrc # or source ~/.bashrc\n\n# For npm users (usually automatic, but if needed)\necho 'export PATH=\"$(npm config get prefix)/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n**Windows (PowerShell as Administrator):**\n\n```powershell\n# For Bun users\n[Environment]::SetEnvironmentVariable(\"Path\", $env:Path + \";$env:USERPROFILE\\.bun\\bin\", \"User\")\n\n# For npm users - usually automatic; if needed, add %APPDATA%\\npm to your PATH\n```\n\n### Local Installation\n\nYou can also install it locally in your project:\n\n```bash\n# Using bun\nbun i -D svelte-doctor\n\n# Using npm\nnpm install -D svelte-doctor\n\n# Using pnpm\npnpm add -D svelte-doctor\n```\n\nThen run with `npx` / `bunx` or a package script:\n\n```bash\n# Using npx / bunx\nnpx svelte-doctor\nbunx svelte-doctor\n```\n\n```json\n\"scripts\": {\n \"doctor\": \"svelte-doctor check\"\n}\n```\n\n---\n\n## Commands\n\n### Common Workflows\n\n```bash\n# First scan\nsvelte-doctor check\n\n# Bootstrap config, CI, scripts, gitignore, and baseline\nsvelte-doctor init --yes --ci github-actions\n\n# Install managed pre-commit / pre-push quality gates\nsvelte-doctor install-hook --mode staged --fail-on error\n\n# Fix issues — deterministic first, then with an AI agent\nsvelte-doctor check --fix\nsvelte-doctor fix\n\n# Gate CI on score and warning thresholds\nsvelte-doctor check --fail-on warning --min-score 80\n```\n\n### Command Index\n\n| Command | Purpose |\n| --------------------------------------------------------------------- | ------------------------------------------------------ |\n| [`init`](#svelte-doctor-init-directory-options) | Bootstrap config, CI, scripts, baseline, and gitignore |\n| [`install-hook`](#svelte-doctor-install-hook-directory-options) | Install managed pre-commit / pre-push git hooks |\n| [`pr-check`](#svelte-doctor-pr-check-directory-options) | Analyze a branch diff for PR / CI feedback |\n| [`doctor`](#svelte-doctor-doctor-directory-options) | Diagnose and fix your development environment |\n| [`reset`](#svelte-doctor-reset-directory-options) | Clean generated cache, baseline, and history files |\n| [`check`](#svelte-doctor-check-directory-options) | Scan the project and output a health score |\n| [`quick`](#svelte-doctor-quick-directory-options) | Fast error-only scan with health score |\n| [`audit`](#svelte-doctor-audit-directory-options) | Security-focused scan with a dedicated security score |\n| [`baseline`](#svelte-doctor-baseline-directory) | Create a baseline from current diagnostics |\n| [`config`](#svelte-doctor-config-directory-options) | Display the active configuration |\n| [`validate`](#svelte-doctor-validate-directory-options) | Validate the config file for errors |\n| [`suggest-ignore`](#svelte-doctor-suggest-ignore-directory-options) | Suggest likely false-positive ignores |\n| [`stats`](#svelte-doctor-stats-directory-options) | Show project metrics and statistics |\n| [`metrics`](#svelte-doctor-metrics-directory-options) | Scan phase durations, rule gains, and technical debt |\n| [`compare`](#svelte-doctor-compare-directory-options) | Compare diagnostics between two git refs |\n| [`watch`](#svelte-doctor-watch-directory-options) | Watch files and show live diagnostics |\n| [`trend`](#svelte-doctor-trend-directory-options) | Show score history and trend |\n| [`apply`](#svelte-doctor-apply-directory-options) | Apply deterministic, safe fixes |\n| [`fix`](#svelte-doctor-fix-directory-options) | Fix issues automatically with an AI agent |\n| [`migrate`](#svelte-doctor-migrate-directory-options) | Auto-migrate Svelte 4 → Svelte 5 |\n| [`migrate-status`](#svelte-doctor-migrate-status-directory-options) | Track Svelte 4 → 5 migration progress |\n| [`graph`](#svelte-doctor-graph-directory-options) | Build a component dependency graph |\n| [`where-used`](#svelte-doctor-where-used-component-directory-options) | Find every place a component is used |\n| [`dead-stores`](#svelte-doctor-dead-stores-directory-options) | Find writable stores that are never written |\n| [`test-gaps`](#svelte-doctor-test-gaps-directory-options) | Find source files without matching tests |\n| [`bundle-impact`](#svelte-doctor-bundle-impact-directory-options) | Preview bundle savings from fixable diagnostics |\n| [`render-profile`](#svelte-doctor-render-profile-directory-options) | Rank the most expensive components |\n| [`deps`](#svelte-doctor-deps-directory-options) | Check dependency health (offline) |\n| [`upgrade`](#svelte-doctor-upgrade-directory-options) | Check the npm registry for dependency upgrades |\n| [`update`](#svelte-doctor-update-options) | Update the global CLI installation |\n| [`rules`](#svelte-doctor-rules-directory) | List every rule and its category |\n| [`explain`](#svelte-doctor-explain-rule-directory-options) | Explain a rule in detail |\n| [`create-rule`](#svelte-doctor-create-rule-name-directory-options) | Scaffold a custom rule, test, and docs |\n\n### Setup, CI & Hooks\n\n#### `svelte-doctor init [directory] [options]`\n\nBootstrap 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.\n\nGenerated defaults:\n\n- `svelte-doctor.config.json`\n- `.svelte-doctor/*` entry in `.gitignore`\n- `package.json` scripts: `doctor` and `doctor:fix`\n- optional CI file for GitHub Actions, GitLab CI, or CircleCI\n- optional `.svelte-doctor/baseline.json`\n- optional direct `.git/hooks/pre-commit` hook\n\n| Option | Description |\n| --------------------------------------------- | -------------------------------------------------------------------- |\n| `--ci![\"npm](\"https://img.shields.io/npm/v/svelte-doctor.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/svelte-doctor.svg\")
\n ![\"license\"](\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\"){kind=icon}
\n