Zubra docs

Stability: what may change, and how#

Zubra moved fast on purpose before 6.0, and this page says what that means from 6.0 on rather than leaving it to the version numbers. It also lists everything the project maintains, with a tier for each, so you can tell what you can build on and what may still go.

The 6.x long-term-support line#

6.0.0 starts a long-term-support line. For all of 6.x:

  • Everything Stable is frozen. Every row marked Stable below: the .zb format, the compiled ABI (abi: 5), the CLI's commands, flags and exit codes, the typings and Custom Elements Manifest the compiler writes, the hydration markers, and every Stable npm entry. These change only in a major, and not before 7.0.
  • Patch releases (6.0.x) are bug and security fixes only.
  • Minor releases (6.x.0) add things, or change something Supported, each with a written reason and an entry in CHANGELOG.md that says what to do. A minor may not break a Stable contract.
  • Experimental pieces may change in any release: signals mode, @zubra/runtime/track, @zubra/runtime/outlet, @zubra/unplugin/rspack, and the other rows marked Experimental below.
  • A Stable item that 7.0 removes is deprecated first, with a warning in at least two 6.x minors before 7.0.
  • 6.x gets security and critical fixes for 18 months after 6.0.0, in its latest release (SECURITY.md says how to report one).
  • Every major ships with a migration guide, and with an automatic migration where the change is mechanical. 6.0's is Migrating to 6.0.

Before 6.0: pre-adoption#

Until 6.0, nobody depended on Zubra in production, so it followed the platform as soon as the platform moved: a new standard landed, and Zubra used it in the next release. That meant majors close together (1.0 to 5.x in its first week; CHANGELOG.md has each). Within a major nothing Stable broke, and every change was in CHANGELOG.md. The 5.x line left out migration guides and a zubra migrate command, since there was no one to migrate; 6.0 brings back the guide (Migrating to 6.0), and the long-term-support line above keeps one for every major.

This stage ends with 6.0.0.

Tiers#

Tier What it promises
Stable Breaks only in a major.
Supported Tested in CI on every change, and kept. May change in a minor; the changelog entry says what to do.
Experimental May change or go in any release. Use it to try an idea, not to ship.

Every npm package entry and command below has a tier; docs/test/stability.test.js fails when one is added without a row here, or a row names one that no longer exists. "Tested by" names the CI job (.github/workflows/ci.yml); "Used by" names an example or app that depends on it, which is the reason it exists.

Contracts#

Contract Tier Notes
The .zb format and .zb.jsx / .zb.tsx front ends Stable The reference's rules are the contract
The compiled ABI (abi: 5) Stable The runtime still runs abi: 2 and abi: 3 output (through $define) and abi: 4 output (through $element), filling in what they don't name; since-4.test.js runs 5.18.0's output
CLI commands, flags and exit codes Stable Both CLIs, native and npm, from one table (src/cli.rs); exit codes 0, 1 and 2 as in the reference. Except the commands marked below
Diagnostic codes (ZB2001) Stable docs/diagnostics.md lists every one; a code is never reused or renumbered
The Custom Elements Manifest and typings the compiler writes Stable
Hydration markers (processing instructions) Stable The runtime still reads 4.x comment markers
The zubra request / zubra serve JSON protocol Supported What the server clients speak
The compiler's error and warning text Supported Tools should read the codes (--format json's code, the language server's Diagnostic.code), not the prose

The compiled ABI runs one way: a runtime runs what its own and older compilers wrote, not what a later one writes. So an app's @zubra/compiler is never a later release than its @zubra/runtime; install the two, and @zubra/server, at one version. From the release after 5.19.0 npm enforces it: @zubra/compiler has an optional peer on @zubra/runtime no older than itself, so installing a compiler ahead of the runtime is refused (ERESOLVE) where it used to succeed, and the compiler alone still installs no runtime. 5.19.0 and earlier have no such peer (pinning the runtime alone leaves the compiler on the latest), which is what @zubra/server's warning at start is for.

npm packages#

@zubra/runtime#

Entry Tier Tested by Used by
@zubra/runtime Stable Runtime (unit, browser, tools); engines Every example
@zubra/runtime/signal Stable Runtime Examples that share state
@zubra/runtime/effect Stable Runtime Examples
@zubra/runtime/spread Stable Runtime Registry, converted React components
@zubra/runtime/core Supported Runtime (production.test.js); Server (preload.test.js, bundle.test.js) @zubra/server, which maps @zubra/runtime to it: the runtime without zb-await's binder, the slot router and $define
@zubra/runtime/when Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: zb-if's binder, for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/each Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: zb-each's binder, for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/await Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: zb-await's binder, for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/slots Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: light-DOM slots and the slot router's binder, for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/modifiers Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: a listener with modifiers (.prevent, .self, a key)'s binder, for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/form Supported Runtime (production.test.js); Server (preload.test.js) The compiled-code interface: a form-associated component's API and callbacks (forming: $form), for modules compiled with --binder-entries (what @zubra/server asks for)
@zubra/runtime/zag Stable Runtime; registry Registry combo-box
@zubra/runtime/primitives Stable Runtime; registry Registry menus, tabs
@zubra/runtime/motion Supported Runtime (both outputs) Zubra UI motion components
Signals mode (engine: 'signals' in @zubra/unplugin, @zubra/server and buildRuntime(): signal-tc39.js as the engine; signals: true is its 6.0.0-rc.0 name) Experimental Runtime in signals mode (unit, browser, production, Sync); Plugin (plugin.test.js, options.test.js); Server (signals.test.js) Nothing yet: for interoperating with other Signals libraries and tools
@zubra/runtime/track Experimental Runtime (unit, browser) Async resource() fetchers in .zb scripts; nothing outside its tests yet
@zubra/runtime/react Stable Framework and meta-framework examples React and Next.js examples
@zubra/runtime/vue Stable Framework and meta-framework examples Vue and Nuxt examples
@zubra/runtime/angular Stable Framework examples Angular booking
@zubra/runtime/server Stable Runtime; meta-framework examples Next.js, Nuxt, SvelteKit, SolidStart
@zubra/runtime/bridge Supported Runtime (React 19, 18, Vue 3) Nothing outside its tests yet
@zubra/runtime/context Supported Runtime (plain HTML, React 19, 18, Vue 3) Nothing outside its tests yet
@zubra/runtime/parts Supported Runtime (since-4.test.js, every class, style, window-listener and URL test) The compiled-code interface: window listeners, class lists and toggles, style properties and URL checks (binder: $classes, url: $url), for modules compiled with --binder-entries
@zubra/runtime/shadow Supported Runtime (every shadow-DOM test) The compiled-code interface: a shadow component's root, sheets and slot following (shadowing: $shadow), for modules compiled with --binder-entries
@zubra/runtime/hydrate Supported Runtime (client-only.test.js, every hydration test); Server (preload.test.js) The compiled-code interface: taking over server markup (hydrating: $hydrate), which every component compiled without --client-only imports; its own entry for modules compiled with --binder-entries
@zubra/runtime/forms Supported Runtime (four form libraries) Nothing outside its tests yet
@zubra/runtime/navigation Supported Runtime (React Router, Vue Router) Nothing outside its tests yet
@zubra/runtime/testing Supported WebAssembly compiler (examples/testing-vitest) examples/testing-vitest
@zubra/runtime/outlet Experimental Runtime (React 19, 18) Nothing; React only, client only
@zubra/runtime/modules Supported Runtime (the build's --check); Server (preload.test.js, bundle.test.js, edge.test.js) @zubra/server and @zubra/server/edge, for a page's preload links; bundled is the same for dist/bundled, and split for dist/split, with the file that has each name the base doesn't

@zubra/compiler#

Entry Tier Tested by Used by
@zubra/compiler Stable WebAssembly compiler; plugin The bundler plugin, @zubra/server
@zubra/compiler/wasm Stable WebAssembly compiler Edge servers, the playground
@zubra/compiler/zubra.wasm Stable WebAssembly compiler Same
@zubra/compiler/library Stable Framework examples (zubra build --lib) examples/frameworks/ui
@zubra/compiler/embed Supported WebAssembly compiler (embed.test.js) Nothing yet; not tried on a live WordPress site or Shopify store
@zubra/compiler/mcp Supported WebAssembly compiler (npm test) Nothing yet
@zubra/compiler/typecheck Supported WebAssembly compiler (typecheck.test.js) zubra check --types; the language server's type errors
bin zubra Stable Compiler (Rust) Everything

@zubra/server#

Entry Tier Tested by Used by
@zubra/server Stable Plugin job (server/) Help desk, meta-framework examples
@zubra/server/express Stable Plugin job; server example Help desk
@zubra/server/fastify Stable Plugin job Its tests
@zubra/server/hono Stable Plugin job; hypermedia examples Hono bike shop
@zubra/server/build Experimental Server (build.test.js, Chromium) buildRuntime(), buildApp() and createZubra({ runtime }): an app's own build of the runtime, or of the runtime with its components and page scripts as one module. Needs esbuild, installed by the app
@zubra/server/edge Supported WebAssembly compiler (edge.test.js); edge jobs Worker examples
@zubra/server/hono-edge Supported Hono bike shop on a Cloudflare Worker examples/edge/hono-bikes-worker

@zubra/unplugin#

Entry Tier Tested by Used by
@zubra/unplugin Stable Plugin job Every bundled example
@zubra/unplugin/vite Stable Plugin job; framework examples Most examples
@zubra/unplugin/rollup Stable Plugin job Its tests
@zubra/unplugin/webpack Stable Plugin job Its tests
@zubra/unplugin/esbuild Stable Plugin job Its tests
@zubra/unplugin/loader Stable Meta-framework examples Next.js conference (Turbopack)
@zubra/unplugin/astro Stable Meta-framework examples; demo gallery Astro examples
@zubra/unplugin/astro/server Stable Same Same
@zubra/unplugin/astro/client Stable Same Same
@zubra/unplugin/client Stable Type declarations only Vite apps' .zb imports
@zubra/unplugin/rspack Experimental No test Nothing. One line over unplugin; promoted when a test builds with Rspack

@zubra/actions#

A sibling: needed only for 'use server' functions.

Entry Tier Tested by Used by
@zubra/actions Supported Plugin job (actions/, with and without JavaScript in Chromium) Standup, Tailgate
@zubra/actions/client Supported Same Same
@zubra/actions/enhance-forms Experimental Actions (enhance-forms.test.js, Chromium) Plain form posts without the reload: data-zb-updates, the updated event, actions.formsScript()
@zubra/actions/build Supported Same; Sync and Actions on a Cloudflare Worker Standup worker
@zubra/actions/edge Supported Sync and Actions on a Cloudflare Worker Standup worker
@zubra/actions/express Supported Plugin job Its tests
@zubra/actions/fastify Supported Plugin job Its tests
@zubra/actions/hono Supported Plugin job Its tests
bin zubra-actions Supported Sync and Actions on a Cloudflare Worker Standup worker

@zubra/sync#

A sibling: needed only for 'use collection' state.

Entry Tier Tested by Used by
@zubra/sync Supported Plugin job (sync/, and against the zubra-sync binary); local-first example Standup, Tailgate, CineStack
@zubra/sync/connect Supported Same Same
@zubra/sync/follow Experimental Sync (browser.test.js, the follow: tests) A read-only connection: connect()'s reading half without the outbox, pushes, presence or peers
@zubra/sync/server Supported Same Same
@zubra/sync/sqlite Supported Same Standup
@zubra/sync/durable Supported Sync and Actions on a Cloudflare Worker Standup worker, Tailgate's Worker deploy

@zubra/router#

A sibling: needed only for 'use route' and 'use layout' components, in an app with no host framework. On npm since 5.17, and Supported, so its options may still move in a minor (with a changelog entry that says what to do).

Entry Tier Tested by Used by
@zubra/router Supported Plugin job (router/, with and without JavaScript in Chromium) Its tests
@zubra/router/table Experimental Same The router itself: the table's rules without files or a compiler

Tooling packages#

Entry Tier Tested by Used by
bin create-zubra Stable Framework examples (every template, and the first ten minutes scripted) npm create zubra
@zubra/language-server Supported Editor support The VS Code extension
@zubra/language-server/analysis Supported Editor support Same
bin zubra-language-server Supported Editor support Same
prettier-plugin-zubra Experimental Prettier plugin Not published: not on npm yet; install it from the repository (prettier-plugin/)

Everything else Zubra maintains#

Not npm entries, so not checked by the test above; listed so the whole surface is in one place.

Piece Tier Tested by Used by
zubra crate (the compiler as a Rust library) Supported Compiler (Rust) The CLI, the WebAssembly build. Not published to crates.io yet
include_zb! (macros/, zubra-macros) Experimental Compiler (cargo test --workspace); non-JS backend examples (Axum garden) examples/backends/axum-garden. Not published
zubra-sync binary (sync-server/) Supported Plugin job (npm run test:binary) The Sync tests against a non-Node server
The release binaries Stable Compiler (scripts/package-binary.test.sh) @zubra/compiler's fallback, non-JS servers
Python package zubra (Jinja, Django) Supported Python package Flask garden
Ruby gem zubra (Rails helpers) Supported Ruby and PHP packages Nothing yet
PHP package zubra/zubra Supported Ruby and PHP packages Nothing yet
Its Laravel service provider and Blade directives Experimental Not executed in CI (no Laravel install) Nothing
Phoenix helpers — Not built —
The component registry (zubra add) Supported Runtime (registry, both outputs, three browsers) Copied into projects, which then own them
Skills (skills/) Supported Skills npm create zubra, agents
npx zubra mcp Supported WebAssembly compiler Coding agents
zubra build --embed (WordPress plugin, Shopify extension, snippets) Supported WebAssembly compiler (embed.test.js, the plugin run under PHP, Liquid rendered) Nothing yet
VS Code extension (Marketplace JourneytoCode) Supported Editor support Editors
DevTools browser extension Supported Editor support Browsers
Playground and demo gallery (GitHub Pages) Supported WebAssembly compiler; demo gallery The site

Supported framework versions#

The adapters are tested against these, in the framework and meta-framework example jobs. A version outside this table may work; it isn't tested.

Framework Tested
React 19 and 18
Vue 3
Angular 22
Svelte 5 (SvelteKit 3)
Solid 1 (SolidStart 2)
Lit 3
Preact 10
Next.js 16
Nuxt 4
React Router 8
Astro 7 (the npm create zubra template)
Eleventy 3
FAST Element 3 (examples/frameworks/fast-orders)

Exact versions are in each example's package.json and lockfile; docs/framework-matrix.md has what each adapter does.

Edit this page on GitHub · Zubra 6.0.4