@azerothjs/language-server

AzerothJS language server - a Language Server Protocol front-end for .azeroth files

Part of AzerothJS - the fine-grained fullstack framework. A development-time companion to azerothjs - the editor extensions bundle it; azeroth-tsc runs it in CI.

Overview

A Language Server Protocol frontend for .azeroth files. It is a thin adapter: it owns the LSP connection and the document lifecycle and forwards every request to the ./language-service subpath of this package (guide), which contains all the intelligence (the TypeScript bridge, the markup model, and the providers).

Editors that speak LSP (the VS Code extension and the JetBrains plugin in this repository, among others) launch this server and talk to it over stdio.

Install

[!NOTE] ESM-only; requires Node >= 22. azerothjs is a peer dependency.

npm install -D @azerothjs/language-server azerothjs

The package provides three binaries: azeroth-language-server (the LSP server, run over stdio by editors), azeroth-tsc (the combined .ts + .azeroth CLI type checker), and azeroth-docgen (a Markdown/HTML API reference for .azeroth components).

Architecture

The server holds one AzerothLanguageService per workspace root (multi-root aware: each document resolves against the service whose root is its longest matching prefix - its nearest project - so files in different roots type-check against their own tsconfig; roots added/removed at runtime are tracked via workspace/didChangeWorkspaceFolders) and a document manager (vscode-languageserver's TextDocuments). Text changes are mirrored into the service with didOpen/didChange/didClose, and each LSP request handler calls the matching service method and returns the result almost unchanged, because the service's result types already mirror the LSP shapes.

editor  --LSP/stdio-->  language-server  --method calls-->  language-service
                        (this package)                      (the intelligence)

The split keeps protocol concerns (connection, capability negotiation, document sync, settings) separate from language concerns (the TypeScript bridge, the markup model). The same service instance also powers the unit test suite and can back any other host without this package.

Components

| File | Role | | --- | --- | | server.ts | LSP wiring: connection, capabilities, document sync, settings, and one handler per request. | | cli.ts | Executable entry point (azeroth-language-server); starts the server over stdio. | | tsc.ts | runTsc: the batch type-checker behind the azeroth-tsc binary. | | tsc-cli.ts | Executable entry point (azeroth-tsc); runs one check and sets the exit code. | | index.ts | Library entry point; exports startServer, the settings API (parseSettings, AzerothSettings, FeatureToggles), and the CLI helpers (runTsc, watchTsc, parseArgs, runDocgen). |

azeroth-tsc (combined command-line type checking)

tsc cannot parse .azeroth, so this package ships azeroth-tsc, the vue-tsc equivalent. It builds ONE TypeScript program containing BOTH the project's real .ts files AND every .azeroth file (compiled to its virtual TypeScript module by the language service). Because both live in the same program:

• a .ts file importing './x.component.azeroth' resolves the component's REAL default, named, and type exports - no declare module '*.azeroth' shim;
• .azeroth <-> .azeroth and .azeroth <-> .ts imports resolve both ways;
• .azeroth internals (including typed component tags) are checked;
• diagnostics map back to original .ts/.azeroth positions.

It is a --noEmit gate (the Vite plugin / compiler owns code emit) that REPLACES tsc:

npx azeroth-tsc            # check the whole project (.ts + .azeroth)
npx azeroth-tsc -p tsconfig.json
npx azeroth-tsc --watch    # re-check on change (alias: -w)

Build wiring

One checker covers the whole project, so the canonical consumer build is just the checker plus the bundler:

{
    "scripts": {
        "build": "azeroth-tsc && vite build",
        "typecheck": "azeroth-tsc",
        "dev:check": "azeroth-tsc --watch"
    }
}

With Vite installed, the consumer needs no declare module '*.azeroth' shim and no vite-env.d.ts / "types": ["vite/client"] entry: import.meta.env, *.png / ?url asset imports, and cross-file .azeroth types all resolve. @azerothjs/typescript-plugin gives the editor's TypeScript server the same .ts -> .azeroth resolution live; azeroth-tsc is the matching CI/pre-commit gate.

Settings

On initialization the server reads initializationOptions and, when the client supports it, pulls live configuration with workspace/configuration. Settings map onto the service's per-feature options (for example completion auto-imports, component snippets, and inlay-hint toggles). Clients that push configuration changes trigger a refresh and a re-publish of diagnostics.

Diagnostics

Diagnostics are pushed (textDocument/publishDiagnostics) when a document opens or changes, rather than pulled, so errors appear as the user types. Each carries its source (azeroth for markup parse errors, azeroth-ts for TypeScript errors) from the service.

Running

Editors launch the bundled binary over stdio:

azeroth-language-server --stdio

Or embed it (for example in a test or a web host):

import { startServer } from '@azerothjs/language-server';
import { createConnection } from 'vscode-languageserver/node.js';

startServer(createConnection(/* your reader/writer */));

Capabilities

Completion (with resolve), hover, definition, type-definition, references, document highlights, rename, document symbols, workspace symbols, signature help, full semantic tokens, folding ranges, selection ranges, code actions, document and on-type formatting, inlay hints, and push diagnostics. A non-standard azeroth/autoInsert request backs auto-close-tag and linked-editing behavior in clients that wire it up.

The legend for semantic tokens is component, tag, attribute, event, string, delimiter, with no modifiers. Editors must register the same legend so these token types get themed.

Formatting: the placement, stated

There is ONE formatting engine for .azeroth, and it lives here - the language-service format provider (document, range, and on-type). What it does in 1.0 is deliberate:

• TypeScript regions format through the real TypeScript formatter, mapped back through the projection - the same engine editors use for .ts.
• Markup is preserved verbatim. An edit that does not map cleanly to source is dropped, so the formatter is STRUCTURALLY incapable of mangling your markup - the failure mode that makes people turn formatters off.

Markup pretty-printing, when it comes, joins THIS engine - there will never be a second formatting implementation that could disagree with the editors.

Configuration

Configuration is supplied by the client through initializationOptions and workspace/configuration. TypeScript intelligence uses the nearest tsconfig.json in the workspace, resolved by the language service.

Related

See the monorepo README for the full framework. Related tooling:

• @azerothjs/typescript-plugin - live .ts -> .azeroth resolution inside tsserver.
• @azerothjs/eslint-plugin - reactivity lint rules and a .azeroth lint target.
• Editor extensions built on this server: VS Code, JetBrains.