Editor support#
Zubra has a VS Code extension, and a language server that any editor with Language Server Protocol support can use.
VS Code#
Install Zubra from the Marketplace, or run code --install-extension JourneytoCode.zubra. It gives you:
- Syntax highlighting for
.zbfiles: HTML,{…}as JavaScript,<script>and<script lang="ts">as JavaScript and TypeScript,<style>and<style lang="scss">as CSS and SCSS, and the directives and event attributes. - Diagnostics as you type: the compiler's own errors and warnings, with their suggestions.
- Completion of directives, imported components, their props and events, and of props inside
{…}. - Components' types in
.tsand.tsxfiles: an import of a component (./badge.zb,./badge.zb?react,?vue,?element, or a.zb.tsxcomponent) is typed from the component itself, for VS Code's own TypeScript: errors, hover, completion and go to definition (which opens the component). Saving the component updates the files that import it. Nothing has to be built first, andallowArbitraryExtensionsisn't needed. A plain import is typed for the project's framework, as the build plugin compiles it (React or Vue whenpackage.jsonhas them). It runs in VS Code's TypeScript server (the default); the native TypeScript 7 preview doesn't load plugins yet. - Hover documentation for imported components: description, props with types and defaults, events and slots.
- Go to definition for imported components.
- Formatting: Format Document (Shift+Alt+F), or on save with
"editor.formatOnSave": true. It'szubra fmtwith your editor's indentation: the template re-indented, tags tidied, and a tag too wide for its line split one attribute per line (zubra.format.printWidth, default 100). It never changes what the component compiles to, and leaves expressions, comments,<script>,<style>,<pre>and<textarea>as written (see Formatting). The extension is the default formatter for.zb. To have<script>and<style>formatted too, there isprettier-plugin-zubra, which is experimental and not on npm yet: install it from a checkout of this repository (npm install --save-dev prettier <checkout>/prettier-plugin). Needs Zubra 5.4 or later; with an older compiler it says so once and changes nothing. - Format Selection (and
"editor.formatOnPaste": true): formats the lines the selection touches, exactly as Format Document would write them in the whole file, and nothing else. Needs a Zubra compiler withformatRange(5.5 or later). - Extract to component (select whole sibling nodes of the template; lightbulb → Extract to component, or Zubra: Extract to Component… in the command palette and the context menu, which asks for the name): moves the markup into a new
.zbfile beside this one and puts<new-tag …>in its place, with the import. What the selection reads becomes a prop, a function of the component used as a whole handler (onclick={remove}) becomes an event, and names the component imports are imported again. When it can't, the action shows disabled with the reason: a selection that starts or ends inside a tag, a comment, a{…}expression or a<textarea>; assigning to the component's state; a<zb-slot>, or content placed in a slot (slot="title"); a handler that takes the event as its argument; a function or a browser-only value the server couldn't pass as a prop; a shadow DOM component; a cutzb-if/zb-elsechain; a name that's taken. What it would write is compiled first, so it never leaves a component that compiled not compiling, or one that rendered on the server not rendering. No CSS moves: rules that match by descendant still apply, but a rule or layout that depends on the selection being a direct child (ul > li, a flex or grid container's children) now sees the new element. The action is offered to editors that can apply an edit creating a file. Needs a Zubra compiler with therefactorcommand (5.5 or later).
Highlighting works on its own. The rest needs the compiler, which the extension looks for in this order:
- The
zubra.compilersetting: a path to thezubracommand. @zubra/compiler(WebAssembly) installed in your workspace:npm i -D @zubra/compiler.zubraon yourPATH.
A project made with npm create zubra@latest already has @zubra/compiler.
In the browser: Zubra DevTools#
A pane in the Elements panel of Chrome, Edge and Firefox. Select a node: it shows the component's .zb file and line (click to open it in your editor), its props and state by name, and each binding as the DOM operation it performs, with its line and the signals it reads; and after a change, what was written and which bindings re-ran. It reads the development build @zubra/unplugin makes in Vite's dev server; production builds carry none of it. Install and details: editors/devtools.
Other editors#
The extension is a thin client for @zubra/language-server. Run it with zubra-language-server --stdio from Neovim, Helix, Zed, Sublime LSP or any other editor that speaks LSP. It uses the compiler named in initializationOptions.compiler if there is one; otherwise @zubra/compiler when it's installed, then the command in the ZUBRA_COMPILER environment variable, then (with ZUBRA_DEV_CHECKOUT=1, in a checkout of Zubra itself) the checkout's cargo build output, then zubra on the PATH.
In other editors whose TypeScript support runs tsserver (Neovim's ts_ls, Sublime's LSP-typescript, WebStorm), the same TypeScript plugin gives .ts files components' types. Install @zubra/language-server in the project and add it to tsconfig.json:
{ "compilerOptions": { "plugins": [{ "name": "@zubra/language-server/typescript-plugin" }] } }
It finds the compiler the way the language server does; "compiler": "/path/to/zubra" in that entry names one. tsc itself doesn't run plugins: for builds and CI, the typings the build plugin writes (rating.d.zb.ts) and npx zubra check --types cover it.
.html files that use Zubra elements#
zubra compile x.zb --emit html-data writes VS Code HTML custom data. Point the html.customData setting at it and the editor completes your tags and attributes in plain HTML and documents them on hover.