Healthier Astro.
One check at a time.
Astro Doctor catches common mistakes in your Astro project, explains what matters, and helps you fix them. Start with a scan. Build better habits from there.
Start in your terminal
Run this from your Astro project. No configuration or installation is required.
pnpm dlx @santi020k/astro-doctor@latestnpx @santi020k/astro-doctor@latestyarn dlx @santi020k/astro-doctor@latestbunx @santi020k/astro-doctor@latestRead the health score
The report includes file locations, diagnostics, and an S–F health grade. Each file starts at 100: errors cost 25 points and warnings cost 10, with a minimum score of zero per file. File scores are then averaged. Unresolved errors cap the score at 89; security errors cap it at 74. Workspace scans use the lowest project score.
Find your next step
- Run your first checkInstall, scan, and make the results part of your workflow.
- Understand a findingSee why a check matters, with examples of what to change.
- Check every pull requestReport new findings in CI and set a passing threshold.
- Bring it into your editorGet diagnostics and a project health panel in VS Code.
What it looks for
From eager island hydration to missing image descriptions and exposed secrets, the checks focus on mistakes that affect real pages. The CLI combines Astro Doctor rules witheslint-plugin-astro and audits relationships across project files.
Choose how you work
- CLI
@santi020k/astro-doctorscans projects, scores findings, and exports reports.- ESLint plugin
@santi020k/eslint-plugin-astro-doctoradds Astro checks to your flat config.- Oxlint config
@santi020k/oxlint-config-astro-doctorenables the built-in Oxlint checks that overlap with Astro Doctor.
Before you begin
- Node.js
^22.22.3 || ^24.16.0 || >=26.3.0 - An Astro project with
.astrofiles - ESLint 10 with flat config when using the plugin directly
Inspired by react-doctor, Astro Doctor brings the same focused approach to Astro: deterministic checks for developers and coding agents.