Introduction
astro-doctor is an ESLint-based quality tool for Astro projects. It ships 13 opinionated ESLint rules plus project-level audits that catch the most common mistakes developers (and AI agents) make in Astro codebases — from missing image alt text to accidental XSS vectors.
Each scan produces a health score from 0 to 100 with an S–F grade, so you always know how your codebase compares to best practice and can track improvement over time.
What it checks
| Rule | Category | Default severity |
|---|---|---|
| no-client-load-overuse | Performance | warn |
| use-astro-image | Performance | warn |
| require-image-dimensions | Performance | warn |
| no-missing-alt | Accessibility | error |
| no-set-html | Security | warn |
| no-public-secret-env | Security | warn |
| prefer-class-list | Best Practices | warn |
| no-blocking-script | Performance | warn |
| no-unprocessed-script-surprises | Performance | warn |
| no-missing-lang | Accessibility | error |
| require-island-fallback | Accessibility | warn |
| no-process-env | Best Practices | warn |
| prefer-content-collections | Best Practices | warn |
Why astro-doctor?
AI coding agents are prolific writers of Astro code — and they make the same mistakes humans do: raw <img> tags instead of <Image>, client:loadon every island, missing alt text, and so on. astro-doctor adds a fast, deterministic safety net to every commit and pull request.
It is inspired by react-doctorand follows the same philosophy: a small, focused tool that does one thing well.
Packages
The project is a monorepo with two public packages:
@santi020k/astro-doctor— the CLI. Runpnpm dlx @santi020k/astro-doctor@latestto scan any directory without any setup.@santi020k/eslint-plugin-astro-doctor— the ESLint plugin. Import and add to youreslint.config.jsfor live editor integration.
Requirements
- Node.js
^22.22.3 || ^24.16.0 || >=26.3.0 - ESLint 10 (flat config)
- Astro project with
.astrofiles