Reference
Reference
Editors
The language server, wf-lsp, and what the VS Code and Zed extensions and the Tree-sitter grammars each support.
This page is the reference for WebFluent's editor support: the language server, wf-lsp, and the three repositories built around it. It lists what each one supports and how to install it.
| Editor | Repository | Highlighting | Language server | Snippets |
|---|---|---|---|---|
| VS Code |
TextMate grammar, |
runs |
no | |
| Zed |
Tree-sitter, |
runs |
yes | |
| Any editor with Tree-sitter | the two grammars | — | — | |
| Any editor with LSP | semantic tokens from the server |
|
— |
Every finding, completion and quick fix comes from wf-lsp, which is the compiler itself: an editor reports what wf check reports.
The language server: wf-lsp
wf-lsp runs the compiler's checks as you type and answers the editor's questions about the code. Keep it at the version of your wf; wf-lsp --version prints it.
To install it, download wf-lsp-<version>-<arch>-<os> from a release and put it on your PATH, or build it from a clone of the repository:
$ cargo install --path crates/wf-lsp
Releases are built for x86_64 Linux, macOS (Apple Silicon and Intel) and x86_64 Windows. Both extensions download the server themselves when it is not on your PATH.
What it answers
| Request | What you get |
|---|---|
| Diagnostics |
Every check |
| Completion |
Components and their props, flags and parts, enum cases, events, |
| Hover | A component's documentation and signature, a name's inferred type, a field, an endpoint, a case, a keyword or a built-in function |
| Signature help | What a call takes, and which argument the cursor is on |
| Go to definition, references, highlights |
For every declaration — a component, a store, a type, a case, a field, a |
| Rename | Across the project, after the editor asks whether the name can be renamed |
| Formatting |
|
| Folding, inlay hints |
Blocks fold; an inlay hint shows the type of a |
| Semantic tokens | A name is coloured by what it resolves to: a component, a type, a store, a prop or a state |
| Document and workspace symbols | The outline, and a search over the project's declarations |
| Code actions |
The fixes the compiler attaches to a finding (quick fix), all of a file's fixes at once (fix all), and Extract component |
| Your own scripts |
In a |
In detail
What the table sums up, request by request.
- Output awareness. In a project whose
build.output_typeispdforslides, completion offers only what paper can draw — noButton, noon click, noresource. Inside aPresentationit offers slides (and the project's slide components), and inside a slide everything else. Hover says when an element is not drawn in this output, and why.pageandpagesare names inside aHeader,FooterorBackground. In a web project the paper-only elements are offered last. - Completion, from the compiler's own tables: components and their props after
(, flags and parts after., enum cases after:, events afteron,$tokens,matcharms and slot names; the fields of a record and the methods of each built-in type (due.offersplus,isBefore, …); a service's endpoints; the keywords each place allows (a store's, an action's, a test's steps); type names after:; duration units after a number;validaterules,persistsettings,formatstyles, responsive steps,Hosttags, key names inon key("…"), translation keys int("…"), publicenv.names, and lint codes in// wf-allow(. - Hover — what every name is: a component's documentation and signature, the props every element takes, a name's inferred type, a field or an endpoint, a case, a keyword, a function the language provides, an
image's size. - Signature help inside a call: what it takes and which argument the cursor is on — for an element, a component, an endpoint, an action, a project script's function or a built-in one.
- Navigation — go to definition, find references, highlight the uses in a file, and rename across the project, for every declaration (a type, an enum, a case, a field, a
const, adatafile, an animation, an endpoint) and inside a string's{…}splices. - Formatting —
wf fmt, on the open file. - Folding, inlay hints and semantic highlighting — an inlay hint shows the type of a
state,derivedvalue orletwritten without one, and a name is coloured by what it resolves to: a component, a type, a store, a prop or a state. - Your own scripts. A function a
.jsfile undersrc/declares is called from.wffiles, which no JavaScript tool reads, so to the script's editor it looks unused. The server follows each name the script declares to every page, component and store that calls it — resolved as go-to-definition resolves them, so a local of the same name is not one — and to the project's other scripts. Over each declaration a lens says where it is used (Used 3 times in WebFluent), find-references lists the pages beside the scripts, a hover names the places, and a name nothing uses is faded with a hint. A rename, from the script or from a page, changes the declaration and every call. In VS Code the script stays the TypeScript service's (its formatting and highlighting are untouched) and the lenses follow a save; Zed attaches the server to JavaScript too. - Document symbols and the outline.
- Quick fixes, from the compiler's own findings: the nearest name for a misspelt field, member, method, variable, component or flag;
?.for a value that may be null; the props a call leaves out; the arms amatchmisses; a bare word written as its flag;alt: ""for an image; an_before a name nothing reads; the type astate, a parameter or an action's return leaves unsaid (T25,T32,T26);JsonforAnyorMap(T23,T24); the 7.0 form of a removed request form (N08). Extract component turns a selection into a component.
How it finds the project
The project root is the nearest folder above the open file that holds webfluent.app.json. The server keeps the analysed project between requests and analyses it again only after a change, so a hover answers in about a tenth of a millisecond. It asks the editor to tell it when a .wf, .wfx, .md, .js, .css or .json file, a .env or a file in public/ changes on disk.
VS Code
The extension highlights .wf and .wfx files with a TextMate grammar and runs wf-lsp for everything else. It needs VS Code 1.82 or later.
To install it, download webfluent-vscode-<version>.vsix from the extension's latest release, then run Extensions: Install from VSIX and pick the file. It is not on the Marketplace yet.
The extension looks for the server in this order:
- the
webfluent.server.pathsetting; wf-lspin an absolute directory on yourPATH;target/releaseortarget/debugin the workspace, only whenwebfluent.server.useWorkspaceBuildis on in your user settings and the workspace is trusted;- the
wf-lspof the WebFluent release this version of the extension pins, downloaded for your platform and checked against that release'sSHA256SUMS. A download that does not match is refused.
| Setting | Default | What it does |
|---|---|---|
|
|
|
The |
|
|
|
Runs a |
|
|
|
Downloads the pinned release's |
This user setting runs a server you installed yourself:
{
"webfluent.server.path": "/home/me/.cargo/bin/wf-lsp"
}
Zed
The extension highlights .wf and .wfx files with the Tree-sitter grammars and runs wf-lsp. From the grammars it also has bracket matching, auto-indent, folding, the outline panel and breadcrumbs, Vim text objects, and highlighting of `wf fences in Markdown. Its snippets cover pages, components, stores, state, actions, control flow, resources, style rules, the common built-ins, persist, validate, on key, api and test.
It is not in Zed's extension registry yet. To install it, clone webfluent-zed, run zed: install dev extension and pick the clone. Zed compiles the extension and the grammars the first time, which takes about a minute.
The extension looks for the server in this order:
lsp.wf-lsp.binary.pathin your usersettings.json;wf-lspon yourPATH;- the WebFluent release this version of the extension pins, downloaded on first use and checked against the release's
SHA256SUMS; - a copy it downloaded and checked before, when the release cannot be reached.
This user setting runs a server you installed yourself:
{
"lsp": {
"wf-lsp": {
"binary": { "path": "/home/me/.cargo/bin/wf-lsp", "arguments": [] }
}
}
}
A project's own .zed/settings.json cannot choose the program: when it says anything about lsp.wf-lsp.binary, every binary setting is ignored for that project, and a binary.path must be absolute and outside the project. A project may still set lsp.wf-lsp.settings.
Tree-sitter grammars
tree-sitter-webfluent holds two grammars, generated from one source:
| Grammar | Files | Folder |
|---|---|---|
|
|
|
|
|
|
|
|
The generated src/parser.c files are committed, so an editor builds the parser without the Tree-sitter command. The Zed extension pins a commit of the repository, and the grammars are tested against every sample in this guide.
Other editors
Any editor with LSP support runs wf-lsp over standard input and output for the webfluent file type (*.wf, *.wfx), with webfluent.app.json as the root marker. For highlighting in an editor that reads Tree-sitter, use the grammars above. WebFluent Studio is an editor of its own, with the language server, a live preview and a designer in one window.
The configuration for three common editors follows.
Neovim
Neovim 0.11 or later configures the server with vim.lsp.config:
vim.filetype.add({ extension = { wf = "webfluent", wfx = "webfluent" } })
vim.lsp.config("wf_lsp", {
cmd = { "wf-lsp" },
filetypes = { "webfluent" },
root_markers = { "webfluent.app.json" },
})
vim.lsp.enable("wf_lsp")
Helix
Add the language and its server to languages.toml:
[[language]]
name = "webfluent"
scope = "source.webfluent"
file-types = ["wf", "wfx"]
roots = ["webfluent.app.json"]
comment-token = "//"
indent = { tab-width = 4, unit = " " }
language-servers = ["wf-lsp"]
[language-server.wf-lsp]
command = "wf-lsp"
Emacs
With Eglot, define a mode and register the server:
(define-derived-mode webfluent-mode prog-mode "WebFluent")
(add-to-list 'auto-mode-alist '("\\.wfx?\\'" . webfluent-mode))
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs '(webfluent-mode . ("wf-lsp"))))