The Zubra guide#
Moving from 5.x? Migrating to 6.0
Zubra compiles components written as HTML with a script and styles into standard web components: elements that work in plain HTML, in every major framework, and on the server.
Try it first: the playground compiles in your browser and runs your component in plain HTML, React and Vue side by side.
Start an app:
npm create zubra@latest my-app
It asks for a framework (none, React, Vue, Svelte, Solid, Preact, Lit, Angular or Astro, or a server-rendered app with no bundler) and whether components should be TypeScript, and writes a working app: a starter page made of small example components (a counter bound to your framework, a list, a form control, async data, slots), a dev server that updates components in place, a browser test, and an AGENTS.md that explains the app to a coding agent. The starter app says what each file is. With TypeScript (-- --typescript to skip the question) the component is <script lang="ts"> with an interface Props, and npm run check type-checks the components (zubra check --types), for CI.
The tutorial#
Each step builds on the last, in about ten minutes each.
- Your first component: props, state, events, and the dev loop.
- Templates: conditions, lists, classes and styles, event modifiers, references.
- Two-way props and events: what frameworks bind to, and why you rarely fire events by hand.
- Composition and slots: components using components, and content passed in.
- Forms: elements that are real form controls.
- Async data: loading, errors and refetching, without effects.
- Server rendering: HTML first, hydrated in place.
- Read the output: what Zubra compiles to, and the platform rule behind each part.
- Forms that post to the server:
'use server'functions, with or without JavaScript (@zubra/actions). - State that lives on the device:
'use collection', stored in the browser and shared when you want (@zubra/sync). - Motion: content that leaves and lists that glide, with CSS and
animate.
Coming from a framework#
- Zubra for Angular developers
- Zubra for React developers
- Zubra for Vue developers
- Zubra for Svelte developers
Topics#
- Who Zubra is for: where a compiled web component earns its place, and where your framework is the right tool.
- What crosses the boundary: props, events, slots and forms do; render props, framework context and Suspense don't.
- Server rendering, honestly: what renders where, without JavaScript, and the gaps that remain.
- Compared with Lit and Stencil: where each is the better choice, with measured sizes.
- TypeScript in
.zbfiles: what the compiler does with types, what it refuses and why, and what reaches the typings. - Zubra on other people's pages: embeds, extension content scripts, host isolation, tag names, and tables.
- Accessible widgets without a headless library: what Radix and shadcn/ui give React, from the platform,
@zubra/runtime/primitivesand Zag.js. - Zubra with Tailwind, shadcn/ui, MUI and Bootstrap: how components get the app's styles, light DOM and shadow DOM, with an example app for each.
Reference#
The README is the reference: every feature, option and rule. docs/ has the rest (security, browser support).