Your agent writes
bad Astro.
This catches it.
13 opinionated ESLint rules for .astro files — performance, accessibility, security, best practices —
with a health score, CLI, and native GitHub Action.
Know exactly how healthy your codebase is
Every scan produces a 0–100 health score with a letter grade, so you can set thresholds and track improvement over time.
Score = max(0, 100 − (errors×10 + warnings×3) / files)
Everything you need to ship better Astro
One install, multiple touch points — from your editor to your CI pipeline.
ESLint Plugin
Drop-in flat-config plugin. Works with any ESLint 9 setup — standalone or alongside your existing config.
VS Code Extension
Official extension for VS Code and Cursor. Real-time inline diagnostics, hover explanations, quick fixes, and a health sidebar.
CLI Scanner
pnpm dlx @santi020k/astro-doctor — scan any directory, output JSON reports, and integrate into any CI pipeline.
Health Score
0–100 score with A–F grade. Set --fail-on thresholds. Track codebase health across PRs and releases.
GitHub Action
Composite action with PR diff mode — scan only changed files, post a sticky summary comment on every PR.
JSON Reports
Machine-readable output with --json. Pipe into other tools, dashboards, or custom notification systems.
Agent Skills
Pre-built skill files for Claude, Cursor, Copilot Workspace. Your AI agent knows the rules — and how to fix them.
13 rules. Zero excuses.
Each rule targets a specific class of mistake that agents and developers commonly make in Astro projects.
Prefer client:idle or client:visible over client:load for interactive islands.
Use <Image> from astro:assets instead of raw <img> tags.
Require dimensions for public and remote astro:assets images.
All <img>, <Image>, and <Picture> elements must include an alt attribute.
Avoid set:html to prevent cross-site scripting (XSS) vulnerabilities.
Warn when PUBLIC_ environment variables appear to contain secrets.
Use class:list directive for conditional or dynamic class names.
Disallow render-blocking <script src="..."> tags — add defer, async, or type="module".
Warn when script attributes opt out of Astro script processing.
Require a lang attribute on the <html> element.
Require fallback content for client-only and deferred server islands.
Disallow process.env in Astro files — use import.meta.env instead.
Prefer Content Collections over Astro.glob() or import.meta.glob() for Markdown and MDX files.
Up and running in 2 minutes
Install once, catch issues everywhere.
- 1
Install the package
pnpm add -D @santi020k/astro-doctor - 2
Add to your ESLint config
// eslint.config.js import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor' export default [ astroDoctorPlugin.configs.recommended, ] - 3
Scan your project
pnpm astro-doctor
PR-aware scanning with sticky comments
The composite GitHub Action scans only the files changed in a pull request and posts a sticky summary comment with the score and all diagnostics. Updated on every push, never duplicated.
- Scans only changed Astro Doctor files with diff-only: true
- Posts and updates a single sticky PR comment
- Outputs score, errors, warnings as Action step outputs
- Configurable fail-on threshold (error / warning / off)
name: Astro Doctor
on:
pull_request:
paths: ['**/*.astro']
jobs:
scan:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: santi020k/astro-doctor@v1
with:
diff-only: true
comment: true
fail-on: error
Built for the age of coding agents
Agent skills teach your AI assistant every rule — what to avoid, why, and how to fix it.
Install once with astro-doctor install.
astro-rules All 13 rules with before/after examples your agent can reference.
astro-performance Islands architecture, image optimization, View Transitions, Server Islands.
add-rule Step-by-step TDD workflow for contributing new rules to the plugin.
astro-doctor install copies skill files to .agents/skills/ in your project
Special Thanks
Astro Doctor was deeply inspired by react-doctor by Million Software, Inc. They pioneered this concept and philosophy for the React ecosystem, and we built Astro Doctor to bring the same excellent developer experience to Astro. Huge thanks to their team!
Start fixing bad Astro today
One package. 13 rules. A score your team can improve sprint over sprint.