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
.zbformat, 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.mdthat 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.mdsays 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.