Editors
Every editor gets the same language features from one language server, duolith-language-server. The editor shells (the VS Code extension, the JetBrains plugin, and the Neovim, Helix, Zed, Sublime Text and Emacs configurations) only start it.
What the language server does
| Feature | Where | What you get |
|---|---|---|
| Diagnostics | the whole page | Every compiler error with its code (such as E0103), the help line, and a link to the code's entry: the same text duolith explain E0103 prints. TypeScript errors in the script block and in {expressions} land where you wrote them. |
| Completion | markup | Element and control-flow names (show, otherwise, slot), the attributes and events each accepts (minus the ones already written), inserted in braces or quotes as the language definition says, component names (imported for you when they are not yet), and each component's props. |
class="…" | Every utility the theme makes available, with the CSS it resolves to; prefixes such as pressed:, dark: and md:, keeping the ones already typed. | |
<style> | Theme tokens after var(--, such as --color-primary, with their values; plus ordinary CSS completion. | |
script and {…} | TypeScript: names from the script block, the item (and index) of a <list> typed from what it repeats over, and each handler's value typed by what its event receives in the language definition. | |
| Hover | markup | What an element, attribute, event or prop is; for a utility, the CSS rule it becomes on the web, with the prefix's condition and the token values. Over a diagnostic, its catalogue entry and the fix. |
script and {…} | TypeScript types and documentation. | |
| Go to definition | <Card> | The component's file. In the script and expressions, TypeScript's definitions. |
| Rename | script and {…} | A script name everywhere the page uses it, including a list's as="post"; a name exported from a .ts file, in every page and component that uses it, open or not. |
| Find references | script and {…} | Every use, across the project's pages, components and .ts files. Without a tsconfig.json, the server adds every page of the open file's project, so pages you have not opened are found too. |
| Signature help | script and {…} | A function's parameters, with the one you are writing marked. |
| Go to type definition | script and {…} | The type of a value, in whichever file declares it. |
| Colour swatches | class="…", <style> | A utility that paints with a colour token (bg-brand, hover:text-ink) and var(--color-brand) show the theme's light colour. The picker keeps the token as written: change the colour in theme.yaml. |
| Code lenses | top of a page | Run tests in pages/index.test.ts for the test file beside it and any test file that renders its route, and Open a preview of /route. They run the editor commands duolith.runTests (duolith test <project> --file <path>) and duolith.preview; the VS Code extension has both. |
| Quick fixes | E0103 | Replace a misspelt class with the closest utility. |
| Formatting | the whole page | The same result as duolith fmt. A page with syntax errors is left as written. |
Diagnostics for components are the build's: a page sees the props of every component it places, and a component file is checked as a component, so <slot /> and its props are known.
Elements, attributes, events, utilities, prefixes and tokens all come from spec/language/ and spec/styling/ (and your theme.yaml), so anything added there shows up in the editor with no change to the server.
VS Code
Install the extension (editors/vscode; pnpm --filter duolith-vscode package writes dist/duolith-vscode.vsix, then code --install-extension it). It starts, in order: the server named by the duolith.languageServer.path setting, the one installed in your workspace (node_modules/@duolith/language-server), or the one bundled with the extension. Duolith: Restart Language Server restarts it. Set duolith.languageServer.enabled to false to use only highlighting, snippets and duolith fmt formatting.
The extension also has:
- Commands: Duolith: Explain a Diagnostic Code, Build for the Web, Start Dev Server, Open Preview, Run Tests and Format Project.
- Tasks:
duolithtasks for build, dev, test, check, lint and fmt, with a problem matcher, so errors land in the Problems panel. Intasks.json, write{ "type": "duolith", "job": "test", "file": "pages/index.test.ts" }. - Test explorer: your
*.test.tsfiles, with each test's result after a run. - Schema validation and completion, for
theme.yaml,duolith.yaml,permissions.yaml, the kit's part files and module manifests. This needs the Red Hat YAML extension.
JetBrains IDEs
A plugin on LSP4IJ, with highlighting from the TextMate grammar: editors/jetbrains/ (build it with ./gradlew buildPlugin; see its README).
Neovim, Helix, Zed, Sublime Text and Emacs
Configurations are in editors/others/, each folder with a README: a Neovim plugin folder (neovim/), helix/languages.toml with the tree-sitter grammar and its queries, a Zed dev extension (zed/), a Sublime Text package and LSP client settings (sublime/), and duolith-mode with eglot for Emacs (emacs/). Each runs duolith-language-server --stdio from your PATH. A project's own node_modules/.bin/duolith-language-server runs only when you opt in and consent (Neovim, Emacs), or when you name it (Helix, Zed, Sublime Text). The JetBrains plugin uses it only in a trusted project.
Plain .ts files
@duolith/ts-plugin lets .ts files import pages and components: add "plugins": [{ "name": "@duolith/ts-plugin" }] to compilerOptions in tsconfig.json and use the workspace's TypeScript.
Any other editor
Run duolith-language-server --stdio for files ending in .duo, with the project folder (the one holding pages/ or components/) as the root.
How it works
The server is built with Volar (decision 0025). For each page it makes:
- the page itself, which the Duolith service answers for, using the compiler built to WebAssembly (
crates/wasm, contract incrates/wasm/api.d.ts): the same parser, analyzer, style resolution and formatter asduolith build; - a TypeScript file standing for the script block and every
{expression}(the script view, decision 0026), which the TypeScript service answers for; - one CSS document per
<style>block, which the CSS service answers for.
Answers from the embedded TypeScript and CSS are mapped back to where you wrote the code.
Building and testing the server
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.130 --locked
pnpm --filter @duolith/language-server test # builds, then runs the LSP test harness
The harness (packages/language-server/test/harness.ts) starts the built server over stdio, as an editor does, and checks diagnostics, completion, hover, definition, rename, formatting and quick fixes against examples/social and a small project with a component. node packages/language-server/demo/editor-demo.ts <folder> renders the server's answers in an editor-like page and screenshots it.