How the Astro Language Server Enhances IDE Support and Type Checking

The Astro language server delivers real-time type checking, autocomplete, and refactoring across multiple editors by implementing the Language Server Protocol (LSP) and synchronizing a shared TypeScript program that mirrors the exact Astro build environment.

Located in the packages/language-server directory of the withastro/astro monorepo, the Astro language server powers the core IDE experience for Astro projects. It bridges the Astro compiler with editor tooling to ensure that IntelliSense, diagnostics, and navigation operate with complete fidelity to production build behavior.

Core IDE Features Powered by the Astro Language Server

Real-Time Type Checking with Build-Time Parity

In packages/language-server/src/diagnostics.ts, the server parses .astro files by running the Astro compiler in-process. It reuses the same TypeScript program that powers the runtime, reporting errors as you type. This architecture guarantees that diagnostics seen during development are identical to those encountered during production builds, eliminating drift between editor warnings and build failures.

Intelligent Autocomplete and IntelliSense

The src/completion.ts module generates context-aware suggestions for component props, frontmatter keys, and Tailwind utilities. By querying the TypeScript type system and component metadata AST, it provides accurate completions without requiring manual type annotations in every file.

Navigation and Refactoring Tools

For code navigation, src/definition.ts enables Go to Definition and Hover information by delegating to both the TypeScript language service and the Astro AST. When refactoring, src/rename.ts leverages TypeScript's underlying APIs to rename components, props, or variables across .astro, .ts, and .js files while strictly preserving type safety and import references.

Frontmatter and Configuration Validation

The server validates frontmatter schemas—including layout, prerender, and hydrate—against your Astro configuration via src/frontmatter.ts. Additionally, src/project.ts auto-detects the nearest astro.config.mjs (or .ts/.js variants), loading Vite plugins and tsconfig paths to ensure the language server mirrors your exact build environment.

Architectural Implementation

LSP Handlers and Workspace Initialization

The entry point at src/server.ts registers Language Server Protocol handlers and initializes a Project instance. This Project class, defined in src/project.ts, manages the shared TypeScript program and coordinates between the Astro compiler and the editor client.

Vite Integration for Accurate Module Resolution

To resolve imports exactly as they would during a real build, src/vite.ts starts a headless Vite server in "serverless" mode. This allows the language server to handle alias paths, CSS modules, and other Vite plugin resolutions without launching a full development server, ensuring import suggestions and type resolutions remain accurate.

Synchronized Compilation Pipeline

When a .astro file changes, the server parses it using src/parser.ts and updates the internal AST cache. All LSP features—including completions, diagnostics, and hover information—delegate to the centralized ts.LanguageService built from your merged tsconfig.json and Astro's internal typings defined in src/types.ts.

Configuration and Usage Examples

VS Code Integration

The VS Code extension located at packages/vscode/src/extension.ts automatically spawns the astro-language-server binary. No additional configuration is required beyond standard TypeScript settings:

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "typescript.tsdk": "node_modules/typescript/lib"
}

When you open an .astro file, the language server automatically reports errors such as missing component props or invalid frontmatter values.

CLI Usage for Custom Editors

For editors like Neovim or Emacs that support LSP, start the server manually:

npx astro-language-server --stdio

The --stdio flag enables standard I/O communication, compatible with any LSP client configuration.

Programmatic Diagnostics Access

You can reuse the server's type-checking logic in custom tooling or CI pipelines:

import { createProject } from '@astrojs/language-server';

async function getDiagnostics(filePath: string) {
  const project = await createProject(process.cwd());
  const diagnostics = await project.getDiagnostics(filePath);
  console.log(diagnostics);
}

This createProject helper mirrors the internal initialization flow used by the LSP server itself.

Summary

• The Astro language server implements the Language Server Protocol to provide cross-editor support for VS Code, Neovim, WebStorm, and others.
• By maintaining a shared TypeScript program in src/project.ts, it ensures diagnostics and type checking match the exact Astro build output.
• Features like autocomplete (src/completion.ts), refactoring (src/rename.ts), and navigation (src/definition.ts) leverage both the TypeScript service and Astro-specific AST parsing.
• The integration with Vite via src/vite.ts guarantees accurate module resolution, including alias paths and CSS preprocessors.
• Frontmatter validation and automatic configuration detection reduce runtime errors by catching configuration issues during development.

Frequently Asked Questions

Which editors are compatible with the Astro language server?

Any editor that implements the Language Server Protocol can connect to the Astro language server. This includes VS Code via the official extension in packages/vscode, Neovim using nvim-lspconfig, Emacs with lsp-mode, and JetBrains WebStorm. The server communicates via standard I/O or TCP, making it universally compatible with modern development environments.

How does the Astro language server ensure diagnostics match the build output?

The server achieves parity by reusing the same compiler pipeline as the Astro runtime. Located in src/diagnostics.ts, it runs the Astro compiler in-process and maintains a ts.LanguageService that shares the TypeScript program with the build system. Because both the language server and the production build consume identical type definitions and Vite configurations from src/project.ts, errors reported in the editor never drift from build-time diagnostics.

Can I use the Astro language server without installing the VS Code extension?

Yes. The core server is available as the astro-language-server package and can be invoked via CLI with the --stdio flag for any LSP-compliant client. Additionally, you can import @astrojs/language-server programmatically in Node.js scripts to access createProject and other internal APIs for custom tooling or automated testing pipelines.

Does the language server support refactoring across multiple file types?

Absolutely. The src/rename.ts module implements rename refactoring that operates across .astro, .ts, and .js files simultaneously. By delegating to TypeScript's refactoring APIs while accounting for Astro's component metadata, it safely renames components, props, and variables throughout your entire project without breaking type safety or import references.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}