Duolith docs

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/wasm exports the parser, analyzer, style resolution, formatter and the script view through wasm-bindgen (pinned =0.2.130; --target nodejs). Every export takes text and returns JSON text in the shapes of crates/wasm/api.d.ts; offsets crossing the boundary are UTF-16. It builds with #![forbid(unsafe_code)] intact. No duolith check --json fallback was needed, so none was added.
  • packages/language-server is 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 by volar-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

OptionWhy not
duolith check --json subprocessA 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 serviceWe 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-unknown target and wasm-bindgen-cli 0.2.130; the TypeScript CI job installs both.
  • tools/boundaries.yaml lets wasm depend on syntax and style (for Diagnostic, 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.yaml lets language-server depend on client: 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.path and duolith.languageServer.path name programs to run. They are machine-overridable and listed in restrictedConfigurations under capabilities.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.