@healerlab/vue-doctor

Vue Doctor

🩺 Diagnose and fix issues in your Vue.js app.

One command scans your codebase for security, performance, correctness, and architecture issues, then outputs a 0–100 health score with actionable diagnostics.

Demo

Vue Doctor detects your framework (Nuxt, Vite, Vue CLI), Vue version, and project setup, then runs four analysis engines in parallel:

Quick Start

npx @healerlab/vue-doctor@latest .

Verbose mode (show file + line per issue):

npx @healerlab/vue-doctor@latest . --verbose

Install as Coding Agent Skill

Teach your AI coding agent (Cursor, Claude Code, Antigravity, Windsurf, etc.) Vue best practices.

Via skills.sh (the agent-skill registry):

npx skills add healerlab/vue-doctor

Or with the built-in installer (auto-detects your agents and writes the skill to the right directory):

npx @healerlab/vue-doctor install-skill

Alternatively, pipe the install script:

curl -fsSL https://raw.githubusercontent.com/healerlab/vue-doctor/main/scripts/install-skill.sh | bash

Usage

# Full scan with summary
npx @healerlab/vue-doctor .

# Verbose — show file + line per issue
npx @healerlab/vue-doctor . --verbose

# Diff mode — scan only changed files vs main
npx @healerlab/vue-doctor . --diff

# Diff vs specific branch
npx @healerlab/vue-doctor . --diff develop

# Fix mode — human-readable structured output for AI agents
npx @healerlab/vue-doctor . --fix

# JSON mode — machine-readable output for AI agents, coding agents & CI
npx @healerlab/vue-doctor . --json

# Score only (for CI gates)
npx @healerlab/vue-doctor . --score

# CI gate — exit 1 if the health score drops below a threshold
npx @healerlab/vue-doctor . --min-score 80

# Skip dead code analysis
npx @healerlab/vue-doctor . --no-dead-code

Options

Usage: vue-doctor [options] [command] [directory]

Arguments:
  directory            project directory to scan (default: ".")

Options:
  -v, --version        output the version number
  --no-lint            skip linting
  --no-dead-code       skip dead code detection
  --verbose            show file details per rule
  --score              output only the score
  --diff [base]        scan only files changed vs base branch (default: main)
  --fix                output diagnostics for AI agents to auto-fix
  --json               output the full diagnosis as JSON (agents & CI)
  --min-score <number> exit 1 if the health score is below this threshold
  -h, --help           display help for command

Commands:
  install-skill        install vue-doctor skill for your AI coding agents

JSON output (--json)

Built for AI agents, coding agents, and CI: a stable, color-free document on stdout (schema: "vue-doctor/diagnosis@1") with score, project, summary, and a diagnostics[] array where each item carries file, line, column, severity, category, rule, message, and a fix hint.

Exit codes

Custom Rules

14 rules that catch Vue-specific anti-patterns:

GitHub Actions

# .github/workflows/vue-doctor.yml
name: Vue Doctor
on:
  pull_request:
    branches: [main]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx @healerlab/vue-doctor@latest . --diff main --verbose

See more examples.

Configuration

Create a .vue-doctorrc in your project root:

{
  "ignore": {
    "rules": ["vue/no-v-html", "knip/exports"],
    "files": ["src/generated/**"]
  }
}

Node.js API

import { diagnose } from "@healerlab/vue-doctor/api";

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

console.log(result.score);       // { score: 82, label: "Great" }
console.log(result.diagnostics); // Array<Diagnostic>
console.log(result.project);     // { framework: "nuxt3", vueVersion: "^3.4.0", ... }

Contributing

Contributions are welcome! Here's how to get started:

# Clone the repo
git clone https://github.com/healerlab/vue-doctor.git
cd vue-doctor

# Install dependencies
pnpm install

# Build
pnpm run build

# Run locally
node packages/vue-doctor/dist/cli.mjs . --verbose

# Run docs site
pnpm run docs:dev

Pull Request Guidelines

• Fork the repo and create your branch from main
• If you've added a new rule, add documentation in docs/rules/
• Make sure the build passes (pnpm run build)
• Keep PRs focused — one feature or fix per PR

Project Structure

vue-doctor/
├── packages/vue-doctor/src/   # Core source code
│   ├── cli.ts                 # CLI entry point
│   ├── index.ts               # Public API
│   └── utils/                 # Analysis engines & helpers
├── docs/                      # VitePress documentation
├── scripts/                   # Install scripts
└── skills/                    # AI agent skill definitions

License

MIT © HealerLab