Astro Doctor
Built a deterministic Astro health-check toolkit with a CLI, ESLint plugin, editor extension, GitHub Action, docs site, and installable agent skills.
En esta página 1 sección
Project notes
Active project
Building a health check for Astro projects
- Estimated reading time
- About 3 minutes
- In this project story
- 6 sections
I built Astro Doctor to make Astro-specific code quality visible before it reaches production. The project started from a simple problem: Astro can compile a page that still works against the reasons you chose Astro in the first place.
The tool scans .astro files and project configuration for patterns that affect performance, accessibility, security, and maintainability. It then reports actionable diagnostics, a project health score, and workflow-specific output for local development, editors, pull requests, and automation.
Outcomes
Catches Astro-specific performance, accessibility, security, and best-practice issues
Reports health scores in local, editor, and CI workflows
Installs agent skills that teach coding assistants Astro standards
Goals
Protect Astro’s performance model by catching eager hydration, raw images, blocking scripts, and missing image dimensions.
Keep accessibility checks close to the code with rules for image alt text, document language, and island fallback content.
Make adoption practical with a CLI, ESLint plugin, VS Code/Cursor extension, and GitHub Action instead of one rigid workflow.
Help AI-assisted teams by installing agent skills that teach the same Astro standards the scanner enforces.
What I built
A CLI package
(
@santi020k/astro-doctor) that scans projects, filters by category, emits JSON reports, explains individual findings, and returns a 0-100 health score.An ESLint plugin
(
@santi020k/eslint-plugin-astro-doctor) for teams that want the rules inside their existing lint setup.A VS Code and Cursor extension
with live diagnostics, hover explanations, quick fixes, status updates, and a health sidebar.
A GitHub Action
that can comment on pull requests and report only the new issues introduced by a change.
A documentation site
at doctor.santi020k.com with quick-start guides, rule docs, and setup examples.
Installable agent skills
so AI coding assistants can learn the expected Astro patterns directly from the repository.
Technical highlights
- Rule engine
TypeScript,ESLint,astro-eslint-parser, and Astro-aware rule metadata.- Developer workflows
local CLI scans,
doctor.config.ts, JSON output, score thresholds, and CI presets.- Editor integration
a language-server-backed VS Code extension with diagnostics, hovers, quick fixes, and sidebar UI.
- CI integration
GitHub Action support for changed-file scans, sticky PR comments, and configurable blocking behavior.
- Docs
an Astro documentation site with rule pages, installation guides, and generated Open Graph assets.
Results
- One rule system across multiple surfaces:CLI, ESLint, editor diagnostics, CI comments, and agent guidance all point back to the same Astro standards.
- Cleaner adoption path for existing projects:teams can start with changed-file scans and avoid turning every pull request into a legacy cleanup project.
- A stronger AI-assisted workflow:generated code can be scanned after the fact and guided before the next change is written.
Why it matters
Astro is fast by default, but defaults only help if the codebase keeps respecting them.
Astro Doctor turns the patterns I look for during Astro reviews into repeatable tooling: fast feedback, clear explanations, and standards that can live in the repository instead of only in someone’s head.
Read the Astro Doctor launch story for the reasoning behind the toolkit and the workflows it protects.
De este proyecto
Dentro del trabajo.
Project introduction
Astro Doctor: A Health Check for Astro Codebases
Why I built Astro Doctor: a CLI, ESLint plugin, editor extension, GitHub Action, and agent skill system for catching Astro anti-patterns early.
Leer artículoTool ecosystem
How I Built the santi020k Developer Tool Ecosystem
How Lumen, ESLint Config Basic, Quality, Astro Doctor, Commitprompt, Dep Beacon, OG, Theme, and Auth form one practical system for my projects.
Leer artículoComparte este artículo
Compártelo.
La copia automática no está disponible.
