Introduction

What zfb is, who it is for, the three ways to run it, and how its concepts map onto Astro and Next.js.

Almost all everyday frontend development in one CLI. zfb brings together scaffolding, development, type and content checks, builds, and previews. Author TSX, MDX, Markdown or HTML pages; add zudo-wind CSS and zudo-react interactivity as needed. Small, composable engine APIs support static sites, Workers and local apps.

Start with Your first site, then use Build with zfb to find everyday tasks.

Who this is for

Use zfb for documentation, blogs and content inside applications when you want small APIs that compose. Read Design philosophy for the rationale and Deploy & Embed for delivery choices.

What zfb provides

For the "why this shape" answer — narrow scope, recipes-over-plugins, no middleware layer — see Design philosophy.

Embedded V8 worker — pages render through a Rust-embedded V8 runtime. No separate Node process is required at build time.
Atomic writes — generated files are written atomically per file, so readers never observe a half-written HTML file. zfb build wipes the output directory before it starts writing, so a failed build does not guarantee the previous dist/ remains intact.
Per-page incremental rebuild — changing a shared layout touches only the pages that import it, not the whole site. Dev-loop latency stays in the tens of milliseconds even on large sites.
Opt-in islands — a "use client" module makes exports eligible as targets; a reachable <Island> boundary activates an island. Pages without islands can still load independent client scripts.
Frontmatter and content collections — Markdown, MDX, and TypeScript data files in a named directory become a typed collection, queryable from pages via getCollection().
Dynamic routes — pages/blog/[slug].tsx exports a paths() function; zfb evaluates it at build time to expand the route into one HTML file per slug.
MDX components — import any TSX component into .mdx content and use it as JSX.
Non-HTML pages — a page file can export a contentType to produce JSON, XML, RSS, or any other text format instead of HTML.
Content-query bridge — getCollection() is available inside MDX files and inside paths(), not only in page components.
Single-binary distribution — zfb ships as one Rust binary. No node_modules for the framework itself, no plugin registry to audit.

Familiar from Astro

If you come from Astro, the concepts map like this:

Astro concept	zfb equivalent
`src/pages/` file-system routing	`pages/` directory, same naming conventions
`.astro` components with a frontmatter fence	TSX page files with a `getStaticProps` export
Content Collections with typed schemas	`getCollection()` + schema declared in `zfb.config.ts`
`<slot />` in layouts	`children` prop — plain TSX composition
`client:load` directive	`"use client"` target inside a reachable `<Island>` boundary
`public/` for static assets	`public/` — same semantics
`astro.config.mjs`	`zfb.config.ts` (TypeScript, loaded directly)

Components use TSX with zudo-react, zfb’s owned JSX runtime. It is not drop-in React or Preact compatibility. Pages also support Markdown, MDX and HTML; see Markdown and HTML pages.

Familiar from Next.js

If you come from Next.js, the concepts map like this:

Next.js concept	zfb equivalent
`pages/` directory routing (Pages Router)	`pages/` — same file naming and nesting rules
`getStaticProps` / `getStaticPaths`	`getStaticProps` + `paths()` export, same two-function pattern
Dynamic routes `[slug].tsx`	`[slug].tsx` — identical syntax
Catch-all routes `[...slug].tsx`	`[...slug].tsx` — identical syntax
`public/` for static assets	`public/` — same semantics
Layout components wrapping pages	Layout components wrapping pages — plain TSX composition

What is different: zfb is SSG by default — every page is computed at build time into static HTML. Routes that genuinely need request-time behavior opt out with prerender = false and are served by a configured adapter (e.g. Cloudflare Workers Static Assets via @takazudo/zfb-adapter-cloudflare). SSR on Cloudflare Workers is a supported shape with stated limits: Cloudflare is the only adapter, and there is no App Router, no React Server Components, no middleware layer, and no automatic ISR. Static build stays the default.

Client router and view transitions

The @takazudo/zfb-runtime package ships a <ClientRouter /> component that intercepts same-origin navigations and replaces page content without a full reload, with optional View Transitions API support. Opt in by mounting it in your root layout — pages that do not mount it get normal link behavior.

Migration guides

Migrating from Astro — concept-by-concept map for moving an existing Astro static site to zfb.

What to read next

Installation covers building and installing the CLI. Your first site walks through scaffolding a project and running a build end to end.