0025. The language server runs on Volar, with the compiler built to WebAssembly
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only)
- Planning item: D27, D28 (decision 0008)
Context
Editors need diagnostics, completion, hover, definitions, rename, quick fixes and formatting for page files, and full TypeScript intelligence inside the script block and {expressions}. Decision 0008 says the compiler compiles to WebAssembly for the language server. The brief allowed a fallback (the duolith binary in a --json mode) if WebAssembly could not be built offline, and plain vscode-languageserver if Volar's embedded-language setup was not workable.
Decision
crates/wasmexports the parser, analyzer, style resolution, formatter and the script view throughwasm-bindgen(pinned=0.2.130;--target nodejs). Every export takes text and returns JSON text in the shapes ofcrates/wasm/api.d.ts; offsets crossing the boundary are UTF-16. It builds with#![forbid(unsafe_code)]intact. Noduolith check --jsonfallback was needed, so none was added.packages/language-serveris a Volar 2.4 server. A language plugin turns each page into the page itself (answered by our Duolith service), the script view in TypeScript (answered byvolar-service-typescript) and one CSS document per style block (volar-service-css). Volar maps every embedded answer back to the page.- The server bundles its dependencies and TypeScript into one file next to the WebAssembly module, so editors need only Node. It uses its own TypeScript rather than the workspace's, so every editor sees the same behaviour.
- Editors start the project-installed server first (
node_modules/@duolith/language-server), then a bundled or global one.
Alternatives considered
| Option | Why not |
|---|---|
duolith check --json subprocess | A process per keystroke; formatting, completion data and the script view would each need a command. WebAssembly built offline, so it was not needed |
Plain vscode-languageserver with our own TypeScript service | We would rewrite Volar's source mapping for completion, hover, definitions, rename and diagnostics across embedded code |
Use the workspace's TypeScript (typescript.tsdk) | Differs between editors and projects; can be added later as an option |
Consequences
- Building the server needs Rust with the
wasm32-unknown-unknowntarget andwasm-bindgen-cli0.2.130; the TypeScript CI job installs both. tools/boundaries.yamlletswasmdepend onsyntaxandstyle(forDiagnostic,Span,Theme,closest_utility).- The analyzer is called in one function (
crates/wasm/src/analysis.rs), so a change to its entry point (such as components) touches one place. tools/boundaries.yamlletslanguage-serverdepend onclient: the server's build makes its fallback runtime declarations from client's source. It never runs client code.
Security
- Starting a language server runs its code. The VS Code extension uses a server installed in the workspace (
node_modules/@duolith/language-server) only when the workspace is trusted. Otherwise it starts the server bundled with it, and starts again once trust is granted. duolith.pathandduolith.languageServer.pathname programs to run. They aremachine-overridableand listed inrestrictedConfigurationsundercapabilities.untrustedWorkspaces(supported: "limited"), so in a workspace that is not trusted VS Code ignores the workspace's values for them.- A panic in the compiler traps the WebAssembly module. Every call into it is guarded (
packages/language-server/src/compiler.ts): the failure is logged once, answered with an empty result, and the module is loaded again, so one page cannot stop the server.