VS Code Extension

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 select packages/vscode-astro-doctor/astro-doctor.vsix.

Tip: The extension activates when you open an Astro file. If you only have TypeScript, JavaScript, or Markdown files open, VS Code may not start it yet.

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: Suppress All Issues in File Add suppressions for all current diagnostics in 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 starts the Astro Doctor language server over stdio. An explicit astroDoctor.serverPath always wins. In local extension development, it prefers the built CLI server from the monorepo, then the workspace install at node_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.

If VS Code reports that the language server cannot be found, install @santi020k/astro-doctor in the workspace or set astroDoctor.serverPath to 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. See Configuration 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. See Editor Integration for examples.

Edit this page on GitHub ↗