Installation

CLI only (no config required)

Run astro-doctor without installing it at all:

pnpm dlx @santi020k/astro-doctor@latest

npx @santi020k/astro-doctor@latest

yarn dlx @santi020k/astro-doctor@latest

bunx @santi020k/astro-doctor@latest

This scans the current directory and prints a health report with score.

Install as a dev dependency

Add to your project so it's always available and pinned to a version:

pnpm add -D @santi020k/astro-doctor

npm install --save-dev @santi020k/astro-doctor

yarn add -D @santi020k/astro-doctor

bun add -D @santi020k/astro-doctor

VS Code extension

For the best experience in VS Code or Cursor, install the official Astro Doctor extension from theMarketplace:

ext install santi020k.vscode-astro-doctor

This provides live diagnostics, hovers, quick fixes, and a visual health score sidebar. SeeVS Code Extension for full features.

ESLint plugin

For live in-editor diagnostics (VS Code, Neovim, WebStorm, etc.), install the ESLint plugin and add it to your flat config:

pnpm add -D @santi020k/eslint-plugin-astro-doctor

npm install --save-dev @santi020k/eslint-plugin-astro-doctor

yarn add -D @santi020k/eslint-plugin-astro-doctor

bun add -D @santi020k/eslint-plugin-astro-doctor

// eslint.config.js
import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'

export default [
  astroDoctorPlugin.configs.recommended,
  // Add your other config here
]

The recommended config includes astro-eslint-parser as the parser for*.astro files and enables all rules at their default severities.

Agent skills

Install the portable Astro Doctor skill so your coding agent can reference the checks and their code examples:

astro-doctor install

This writes skills/astro-doctor.md in your project root. Add--agent-hooks for optional Claude Code and Cursor copies. SeeAgent skills for destinations and setup options.

GitHub Action

See GitHub Action for full setup instructions. No extra installation is required — the action runs astro-doctor internally.

Works alongside eslint-plugin-astro

astro-doctor is designed to complementeslint-plugin-astro(the official community plugin), not replace it. The two cover different ground:

If you already use eslint-plugin-astro (e.g. viaeslint-config-basic), add astro-doctor on top for performance scanning, health scoring, and AI context.