# How the Astro Language Server Enhances IDE Support and Type Checking

> Discover how the Astro language server boosts IDE support with real-time type checking, autocomplete, and refactoring for a better developer experience.

- Repository: [Astro/astro](https://github.com/withastro/astro)
- Tags: internals
- Published: 2026-03-06

---

**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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/src/frontmatter.ts). Additionally, [`src/project.ts`](https://github.com/withastro/astro/blob/main/src/project.ts) auto-detects the nearest `astro.config.mjs` (or [`.ts/.js`](https://github.com/withastro/astro/blob/main/.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`](https://github.com/withastro/astro/blob/main/src/server.ts) registers Language Server Protocol handlers and initializes a `Project` instance. This `Project` class, defined in [`src/project.ts`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/tsconfig.json) and Astro's internal typings defined in [`src/types.ts`](https://github.com/withastro/astro/blob/main/src/types.ts).

## Configuration and Usage Examples

### VS Code Integration

The VS Code extension located at [`packages/vscode/src/extension.ts`](https://github.com/withastro/astro/blob/main/packages/vscode/src/extension.ts) automatically spawns the `astro-language-server` binary. No additional configuration is required beyond standard TypeScript settings:

```json
// .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:

```bash
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:

```ts
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`](https://github.com/withastro/astro/blob/main/src/project.ts), it ensures diagnostics and type checking match the exact Astro build output.
- Features like autocomplete ([`src/completion.ts`](https://github.com/withastro/astro/blob/main/src/completion.ts)), refactoring ([`src/rename.ts`](https://github.com/withastro/astro/blob/main/src/rename.ts)), and navigation ([`src/definition.ts`](https://github.com/withastro/astro/blob/main/src/definition.ts)) leverage both the TypeScript service and Astro-specific AST parsing.
- The integration with Vite via [`src/vite.ts`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/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.