VS Code Extension

Name: astro-doctor
Author: santi020k

The Astro Doctor VS Code extension brings the Astro Doctor language server into your editor. It activates for .astro files, reports diagnostics as you type, shows rule context on hover, and keeps the project health score visible while you work.

Install from Marketplace

Search for Astro Doctor in the VS Code Extensions view, or install it directly from the Visual Studio Marketplace.

ext install santi020k.vscode-astro-doctor

Install locally (for contributors)

The extension lives in packages/vscode-astro-doctor. To build a local installable package from this monorepo:

pnpm --filter vscode-astro-doctor package

Then run Extensions: Install from VSIX... in VS Code and selectpackages/vscode-astro-doctor/astro-doctor.vsix.

Features

Inline diagnostics for Astro Doctor rules in .astro files
Hover cards with rule names, categories, descriptions, and documentation links
Quick fixes for supported actions from the editor lightbulb menu
Status bar updates with the current health state and score
Health Report sidebar with score, grade, file count, issue count, and category breakdown

Commands

Command	Use it for
`Astro Doctor: Scan Workspace`	Run a full workspace scan through the language server
`Astro Doctor: Scan Current File`	Re-check the active Astro file
`Astro Doctor: Apply All Safe Fixes in File`	Apply every safe automatic fix available for the active file
`Astro Doctor: Restart Server`	Restart the Astro Doctor language server
`Astro Doctor: Show Output`	Open the extension output channel for logs and startup errors
`Astro Doctor: Open Documentation`	Open the rule or project documentation from VS Code

Settings

Setting	Default	Description
`astroDoctor.enable`	`true`	Enable or disable Astro Doctor extension features.
`astroDoctor.scanOnType`	`true`	Re-scan from the unsaved buffer as you type. Disable to scan only on open and save.
`astroDoctor.serverPath`	`""`	Optional path to a custom `astro-doctor` executable.
`astroDoctor.trace.server`	`"off"`	Trace language server communication. Use `"messages"` or `"verbose"` when debugging.

Language server resolution

The extension requires VS Code 1.125 or newer and a supported Node.js release available asnode: ^22.22.3 || ^24.16.0 || >=26.3.0.

The extension starts the Astro Doctor language server over stdio. An explicitastroDoctor.serverPath always wins. In local extension development, it prefers the built CLI server from the monorepo, then the workspace install atnode_modules/.bin/astro-doctor. In packaged builds, it prefers the bundled language server and falls back to the workspace install if the bundled server is unavailable. The bundled server runs with the supported node executable available in the user's environment rather than VS Code's embedded Node.js runtime.

If VS Code reports that the language server cannot be found, install@santi020k/astro-doctor in the workspace or set astroDoctor.serverPathto a known executable.

Configuration

Editor diagnostics use the same rule configuration as the CLI. Put your overrides, ignore patterns, and thresholds in doctor.config.* at the workspace root. SeeConfiguration for the full schema.

Troubleshooting

Open a .astro file to trigger extension activation.
Run Astro Doctor: Show Output to inspect startup and language server logs.
Run Astro Doctor: Restart Server after changing extension settings.
Disable astroDoctor.scanOnType if you only want diagnostics on open and save.

For Neovim, Zed, Helix, and other LSP-capable editors, connect directly to the language server with astro-doctor experimental-lsp --stdio. SeeEditor Integration for examples.