🩺 vue-doctor

Your AI agent writes bad Vue/Svelte code. This catches it.

vue-doctor is an open-source CLI tool that scans Vue 3 and Svelte files for common AI-generated code smells, anti-patterns, and quality issues. Inspired by react-doctor (8.8K+ stars on GitHub), vue-doctor brings the same quality assurance to the Vue and Svelte ecosystems.

Why vue-doctor?

AI coding assistants (Claude, Copilot, Cursor, etc.) are great at generating code fast, but they often produce code that:

• Uses Options API instead of Vue 3's Composition API
• Forgets :key in v-for loops
• Mutates props directly (runtime bugs waiting to happen)
• Loses reactivity through destructuring
• Ignores error handling in async operations
• Forgets reactive declarations ($:) in Svelte
• Misses keyboard accessibility in Svelte templates
• Leaves behind console.log statements

vue-doctor catches all of these — and more — with actionable fix hints.

Installation

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

# No dependencies! Uses only Python stdlib
# Requires Python 3.7+

# Optionally create a symlink for global use
chmod +x vuedoctor.py
ln -s "$(pwd)/vuedoctor.py" /usr/local/bin/vuedoctor

No pip install needed. Pure Python stdlib.

Usage

# Scan current directory
vuedoctor

# Scan specific directory
vuedoctor src/

# Only Vue files
vuedoctor src/ --vue-only

# Only Svelte files
vuedoctor src/ --svelte-only

# Strict mode (more rules including accessibility & magic numbers)
vuedoctor src/ --strict

# JSON output (for CI/CD integration)
vuedoctor src/ --json

# Disable colored output
vuedoctor src/ --no-color

Example Output

🩺 vue-doctor — AI Code Quality Report

Files scanned: 12 (Vue: 8, Svelte: 4)
Issues found: 4 (Errors: 2, Warnings: 1, Info: 1)

  src/components/UserList.vue
    ❌ [ERROR] Line 3: v-for without :key binding. This causes rendering bugs.
      → Fix: Add :key="item.id" or :key="index" to the v-for element
    ⚠️ [WARNING] Line 15: Options API detected: data() method. Vue 3 prefers Composition API.
      → Fix: Use reactive() or ref() instead

  src/components/Counter.svelte
    ❌ [ERROR] Line 8: {#each} block without key. Add (item) at the end for keyed each.
      → Fix: {#each items as item (item.id)}
    ℹ️ [INFO] Line 2: console.log() statement found. Remove before production.
      → Fix: Remove console statement or use a proper logger

────────────────────────────────────────────────────────────
❌ 2 error(s) need immediate attention.
⚠️ 1 warning(s) should be reviewed.
ℹ️ 1 info(s) for consideration.

Rules

Vue Rules

Svelte Rules

Common Rules

CI/CD Integration

Use --json output to integrate with CI pipelines:

# .github/workflows/vuedoctor.yml
name: Vue Doctor
on: [pull_request]
jobs:
  vue-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python vuedoctor.py src/ --json --strict > report.json
      - run: |
          ERRORS=$(python -c "import json; print(json.load(open('report.json'))['summary']['errors'])")
          if [ "$ERRORS" -gt 0 ]; then
            echo "Found $ERRORS errors!"
            exit 1
          fi

Exit Codes

• 0 — No errors found (warnings/info are non-blocking)
• 1 — One or more errors detected

Comparison with react-doctor

Contributing

Contributions welcome! Areas we'd love help with:

• More Vue 3 specific rules (Teleport misuse, Suspense patterns)
• Svelte 5 runes support ($state, $derived, $effect)
• Auto-fix mode (--fix flag implementation)
• Configuration file support (.vuedoctorrc)
• VS Code extension integration

License

MIT — see LICENSE for details.

Support

• ⭐ Star this repo if it helped you catch AI-generated bugs
• 🐛 Open an issue for false positives or missing rules
• 💡 Suggest new rules via GitHub Discussions