The Astro monorepo includes a comprehensive set of language tools designed to provide a robust development experience for .astro files. These tools cover syntax highlighting, intelligent completions, type checking, and linting both inside editors and through CLI tooling in CI/CD pipelines.
They target a variety of editors but have a primary focus on Visual Studio Code via the official astro-vscode extension packages/language-tools/vscode/package.json2-4 The tools leverage a shared architecture to maximize code reuse and maintainable integration of Astro-specific language intelligence.
For an in-depth explanation of the VS Code extension and the CLI type-checking tool, see VS Code Extension and astro-check.
Astro’s language tooling architecture is layered and modular, built primarily on top of the Volar framework. This allows shared logic and services to power different editor integrations consistently, especially VS Code and other LSP clients.
@astrojs/compiler parse Astro files, and @astrojs/yaml2ts convert YAML schemas to TS types for content collection intellisense packages/language-tools/yaml2ts/package.json4Sources: packages/language-tools/language-server/package.json28-46 packages/language-tools/ts-plugin/package.json29-36 packages/language-tools/astro-check/package.json20-22 packages/language-tools/vscode/package.json37
The language tools are organized into several focused packages within packages/language-tools/. Their responsibilities are summarized below:
| Package | Responsibility | Key Technology |
|---|---|---|
astro-vscode | VS Code extension with UI, commands, snippets, grammar | VS Code API, TypeScript packages/language-tools/vscode/package.json2-43 |
@astrojs/language-server | Language Server Protocol implementation (LSP) | Volar, Astro compiler packages/language-tools/language-server/package.json28-35 |
@astrojs/ts-plugin | TypeScript language service plugin for Astro files | TypeScript Server API packages/language-tools/ts-plugin/package.json2-5 |
@astrojs/check | CLI tool for type-checking and diagnostics outside editor | CLI, Yargs, Chokidar packages/language-tools/astro-check/package.json33-37 |
@astrojs/yaml2ts | Converts YAML (content schemas) to TypeScript types | Volar VirtualCode, YAML parser packages/language-tools/yaml2ts/package.json4-24 |
This modular split enables Astro developers and users to consume only the tools needed for their workflows: editor integration, CLI checks, or plugin support.
Sources: packages/language-tools/vscode/package.json2-10 packages/language-tools/language-server/package.json2-3 packages/language-tools/ts-plugin/package.json2-4 packages/language-tools/astro-check/package.json2-3 packages/language-tools/yaml2ts/package.json2-4
Below is a diagram linking user-facing concepts to the codebases’ core entry points, filenames, and configuration files:
client.js) initializes the LSP client packages/language-tools/vscode/package.json37nodeServer.js) runs the LSP server process packages/language-tools/language-server/package.json19-21astro-check.js) provides standalone project checks packages/language-tools/astro-check/package.json20-22astro2tsx virtualizes Astro files into TSX using @astrojs/compiler/sync, enabling TypeScript-based editing features packages/language-tools/ts-plugin/src/astro2tsx.ts2-63astro-ts-plugin-bundle for VS Code integration packages/language-tools/vscode/package.json50-55Sources: packages/language-tools/vscode/package.json37 packages/language-tools/language-server/package.json19-21 packages/language-tools/astro-check/package.json20-22 packages/language-tools/ts-plugin/src/astro2tsx.ts1-63 packages/language-tools/vscode/package.json181-211 packages/language-tools/vscode/languages/astro.code-snippets1-50
Astro’s language server uses the Volar framework (~2.4.28) to provide language intelligence packages/language-tools/language-server/package.json33-35 Volar’s modular service architecture is leveraged to support Astro-specific syntax and semantics:
.astro packages/language-tools/language-server/package.json38-40prettier-plugin-astro packages/language-tools/language-server/package.json41The language server uses @astrojs/compiler to parse Astro files and create a structured AST packages/language-tools/language-server/package.json29 This parsing underpins features like diagnostics and completions.
Sources: packages/language-tools/language-server/package.json32-44 packages/language-tools/language-server/package.json29
@astrojs/ts-plugin)The TypeScript plugin complements the language server by enabling Astro support inside .ts and .js files. Its key roles:
import MyComponent from './MyComponent.astro' in TS files..astro imports.The plugin uses astro2tsx to map source offsets between the original .astro file and the generated virtual TSX for accurate navigation and semantic checks packages/language-tools/ts-plugin/src/astro2tsx.ts65-144
Sources: packages/language-tools/ts-plugin/package.json4-5 packages/language-tools/vscode/package.json50-55 packages/language-tools/ts-plugin/src/astro2tsx.ts56-144
The @astrojs/check package bundles the CLI tool astro-check for running type checking and diagnostics on an Astro project outside any editor packages/language-tools/astro-check/package.json20-22 It can be integrated into CI/CD pipelines to:
.astro files and project sources.chokidar for watch mode packages/language-tools/astro-check/package.json35Internally, it depends on @astrojs/language-server to perform a full type-check without requiring an editor packages/language-tools/astro-check/package.json34
Sources: packages/language-tools/astro-check/package.json20-47
Astro also provides specialized type support for Content Collections. The @astrojs/yaml2ts tool converts YAML content schema files into Volar VirtualCode consumable by the language server and TypeScript plugin packages/language-tools/yaml2ts/package.json4-27
astro.content-intellisense setting in the VS Code extension activates this feature (Astro 4.14+) packages/language-tools/vscode/package.json145-150yaml package to parse schemas and transform them into virtual TypeScript definitions packages/language-tools/yaml2ts/package.json24Sources: packages/language-tools/vscode/package.json145-150 packages/language-tools/yaml2ts/package.json2-27
This shows the relationship between the user’s editor environment, the VS Code extension acting as a client, the language server as the middle layer, and core compiler/utilities underpinning the tooling.
For complete details on using and configuring these language tools, see the child page:
Sources: packages/language-tools/vscode/package.json2-164 packages/language-tools/language-server/package.json2-47 packages/language-tools/ts-plugin/package.json2-50 packages/language-tools/astro-check/package.json2-49 packages/language-tools/yaml2ts/package.json2-30 packages/language-tools/language-server/CHANGELOG.md1-95
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.