Language tools

The packages under packages/language-tools/ ship the editor experience for Astro: type checking, IntelliSense, syntax highlighting, and diagnostics.

Purpose

The Astro editor experience is a small Volar-based stack:

• @astrojs/language-server — a Volar-based language server that understands .astro files, hands off to TypeScript for the script section, to a virtual document for the template, and to CSS/HTML services for embedded blocks.
• @astrojs/check — the astro check CLI thin wrapper around the language server, used in CI for type checking.
• @astrojs/ts-plugin — a TypeScript Server plugin so editors that can't run a full language server still get cross-file type information from .astro imports.
• astro-vscode — the official VS Code extension. Bundles syntax grammars, snippets, and the language server.
• @astrojs/yaml2ts — a tiny YAML-to-TypeScript helper used by the language server for frontmatter typing.

Directory layout

packages/language-tools/
├── astro-check/          # `@astrojs/check` CLI
├── language-server/      # The Volar language server
│   └── types/astro-jsx.d.ts   # 1,497 lines of JSX type definitions
├── ts-plugin/            # TS Server plugin (also bundled into the VS Code extension)
├── vscode/               # VS Code extension
├── yaml2ts/              # YAML → TS schema generator
├── tsconfig.json         # Shared base for all sub-packages
└── CONTRIBUTING.md

The language server is the most complex piece. It uses @volar/language-server to compose:

• A TypeScript language service for the frontmatter.
• A virtual .tsx document for the template body.
• HTML service for the markup outside of expressions.
• CSS service for <style> blocks.

How it works

graph TD
    A[.astro file] --> B[Astro Volar language plugin]
    B --> C[Frontmatter virtual TS file]
    B --> D[Template virtual TSX file]
    B --> E[HTML virtual document]
    B --> F[CSS virtual document]
    C --> G[TypeScript service]
    D --> G
    E --> H[HTML service]
    F --> I[CSS service]
    G --> J[Diagnostics, completions, hovers]
    H --> J
    I --> J
    J --> K[VS Code / `astro check`]

@astrojs/check is essentially the language server running once over every file in a project, then printing diagnostics. It is what astro check (the framework CLI command) shells out to via packages/astro/src/cli/check/index.ts.

CONTRIBUTING

packages/language-tools/CONTRIBUTING.md documents how to set up the language tooling subset of the repo (it can be developed without building the whole framework). Notable: the VS Code extension uses @vscode/vsce-sign which is in the pnpm onlyBuiltDependencies allowlist.

Related pages

• packages / astro — the framework's own astro check command delegates here.
• how-to-contribute / testing — pnpm run test:language-tools runs the suite.