# @takazudo/zfb-runtime > Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary. The JS-side runtime for [zfb][zfb-site]'s SSG-first build pipeline. It exposes `createPageRouter`, a Hono-backed page router whose returned fetch handler is shape-compatible with the Cloudflare Workers `(request) => Promise` model. The Rust build host drives this router at build time to emit static HTML; the same handler also serves SSR requests at the edge. Full documentation: . Source: . [zfb-site]: https://takazudomodular.com/pj/zudo-front-builder/ ## Install ```sh npm install @takazudo/zfb-runtime @takazudo/zfb # or: pnpm add @takazudo/zfb-runtime @takazudo/zfb ``` `@takazudo/zfb` is a peer dependency — `createPageRouter` shares module-level state (`ContentSnapshot`) with `@takazudo/zfb/content`, so both packages must resolve to the same instance. ## What this package does zfb's render pipeline goes: ``` user pages/ + content/ + layouts/ + components/ → esbuild bundle // single ESM file, Worker entry → embedded V8 host // same WinterCG surface as CF Workers → @takazudo/zfb-runtime // <-- this package → (request) => Promise // Worker fetch handler ``` This package supplies the page-router factory the Worker entry calls. It is built on [Hono][hono] but does not leak Hono types through the public surface — consumers import from `src/index.ts`, which re-exports the page-router types, the client-router and prefetch API, lifecycle event constants, and plugin types, none of which require Hono. [hono]: https://hono.dev/ The runtime is **JSX-runtime-agnostic**. It never imports preact or react. The caller passes a `FrameworkAdapter` that pins `renderToString` to the chosen JSX runtime; both `preact-render-to-string` and `react-dom/server` slot in. `preact/compat` is a supported target, and the `react` peer dependency is **optional** (`peerDependenciesMeta.react.optional`) — a preact-only consumer does not need `react` installed and does not need `auto-install-peers=true`. ## Public API `createPageRouter` is **server-only** — it builds a Hono app, so it lives at the `@takazudo/zfb-runtime/server` subpath. Keeping it out of the client-safe `.` barrel means an island importing the bare `@takazudo/zfb-runtime` never drags `hono` into a `--platform=browser` bundle (issue #1298). Its *types* remain importable from the root barrel (they carry no runtime). ```ts import { createPageRouter } from "@takazudo/zfb-runtime/server"; import type { CreatePageRouterOptions, PageDefinition, PageModule, PageHeading, PageRouter, FrameworkAdapter, ContentSnapshot, EntrySnapshot, } from "@takazudo/zfb-runtime"; ``` ### Client-router / view-transitions / prefetch ```ts import { ClientRouter, // framework-agnostic helper — mount it to opt a page into SPA navigation navigate, // imperative navigation supportsViewTransitions, // browser capability check transitionEnabledOnThisPage, // reads zfb-view-transitions-enabled meta prefetch, // prefetch a URL on demand prefetchInit, // bootstrap prefetch strategy (e.g. { prefetchAll: true }) TRANSITION_BEFORE_PREPARATION, TRANSITION_AFTER_PREPARATION, TRANSITION_BEFORE_SWAP, TRANSITION_AFTER_SWAP, TRANSITION_PAGE_LOAD, TRANSITION_NAVIGATION_ABORTED, swapFunctions, // swap step overrides for advanced consumers swap, } from "@takazudo/zfb-runtime"; ``` The `./snapshot` and `./client-router` subpath exports are also available for consumers that only need part of the surface: ```ts import type { ContentSnapshot } from "@takazudo/zfb-runtime/snapshot"; import { ClientRouter } from "@takazudo/zfb-runtime/client-router"; ``` The two differ in one way that matters: the root barrel is **side-effect-free** — importing anything from it, `ClientRouter` included, registers no listeners and touches no history — while evaluating the `./client-router` subpath calls `init()` and activates the router on the current page. See [Enabling SPA soft-navigation](#enabling-spa-soft-navigation-the-runtime-ships-automatically) below for how a normal zfb build gets that activation for you. #### Enabling SPA soft-navigation (the runtime ships automatically) Mounting `` in your layout `` is normally **all you need**. The build detects the usage and automatically ships the client-router runtime to the browser — you do **not** have to add a manual `"use client"` bootstrap island. ```tsx import { ClientRouter } from "@takazudo/zfb-runtime"; export default function Layout({ children }) { return ( {children} ); } ``` `ClientRouterProps`: - `fallback?: "none" | "animate" | "swap"` controls the fallback strategy when native View Transitions are unavailable. The default is `"animate"`. - `prefetchAll?: boolean` bootstraps same-origin link prefetching with the default hover strategy. Treat this as a site-wide router policy and mount the same value on every page that participates in SPA navigation. - `preserveHtmlAttrs?: string[]` emits `` so the swap step preserves runtime-owned `` attributes such as `data-theme`. Mount the same list on every soft-navigable page: the router reads the outgoing page's meta before each swap, so a page that omits a name can drop that attribute when navigating away. - `traverseRefetch?: boolean` emits `` to opt out of the same-URL Back/Forward fast path for per-request SSR pages whose content can change at the same URL. Mount the same value on every page in that SPA navigation set so traversal behavior is deterministic. **How the runtime reaches the browser.** `` itself only renders SSR `` tags, and the module it lives in is pure: importing `ClientRouter` from the `@takazudo/zfb-runtime` barrel registers nothing and runs no code on the page. Everything the router does at startup — seeding this page's history entry and scroll position, marking the scripts the initial load already ran, and registering the `popstate` / `load` / `pageshow` / scroll listeners plus the click and form-submit intercepts — happens inside a single `init()` call. `init()` is invoked as a side effect when `@takazudo/zfb-runtime/client-router` is evaluated in the browser, guarded so it never runs during SSR: ```ts // inside @takazudo/zfb-runtime — client-router.ts if (typeof document !== "undefined") { init(); } ``` `init()` is idempotent: calling it again (a second `` mount, an HMR re-run, a manual call) is a no-op for the parts already done. To get that side-effect import into the client bundle, zfb's island scanner detects when a page transitively reaches `` and injects `import "@takazudo/zfb-runtime/client-router"` into the islands asset (`assets/islands.js`) — **even when the project has no `"use client"` islands of its own**. The asset is then loaded on the page, the import runs, and `init()` fires on the client with zero boilerplate. (Auto-include added in zfb #289 / #307; the runtime is byte-for-byte absent from projects that never reach ``.) **What counts as a `ClientRouter` usage the scanner detects:** - a named `ClientRouter` import from the `@takazudo/zfb-runtime` barrel — `import { ClientRouter } from "@takazudo/zfb-runtime"` (renamed forms like `{ ClientRouter as CR }` match on the imported name), or - any import or re-export of the `@takazudo/zfb-runtime/client-router` subpath (e.g. when you only need `navigate` / `prefetch`), or - a named `ClientRouter` imported from a *local* barrel that re-exports the runtime via `export * from "@takazudo/zfb-runtime"`. The importing module has to be reachable from a page in `pages/` — that is the import graph the scanner walks. **When you need a manual side-effect import.** Detection keys off the *import* of `ClientRouter`, and a couple of shapes are deliberately **not** treated as a trigger — firing on them would ship the runtime to projects that only reference `ClientRouter` as a type or never call it: - a namespace import — `import * as rt from "@takazudo/zfb-runtime"` used as `rt.ClientRouter`, and - a type-only import — `import type { ClientRouter }` (or `{ type ClientRouter }`). When detection misses, nothing else picks up the slack: the barrel import is side-effect-free, so an undetected `` renders its meta tags into `` and no runtime is ever shipped to activate against them. If soft-navigation is not working because your reference takes one of these forms (or the mounting module is otherwise not reachable from a page), force the runtime in with an explicit side-effect import from a page-reachable `"use client"` island. The island renders nothing; running its bundle in the browser fires the same `typeof document !== "undefined"` guard (`init()` is idempotent, so reaching it again is a no-op): ```tsx // src/components/client-router-bootstrap.tsx "use client"; import "@takazudo/zfb-runtime/client-router"; export default function ClientRouterBootstrap() { return null; } // Stable marker name so the SSR marker, the scanner record, and the hydration // manifest agree under production minification. ClientRouterBootstrap.displayName = "ClientRouterBootstrap"; ``` ```tsx import { Island } from "@takazudo/zfb"; import ClientRouterBootstrap from "@/components/client-router-bootstrap"; // Mount once near the end of ; when="load" registers the intercepts as // soon as the islands runtime starts. ; ``` This is the escape hatch, not the default — prefer a plain `import { ClientRouter } from "@takazudo/zfb-runtime"`, which the scanner detects on its own. See the [Client-Side Routing concept guide](https://takazudomodular.com/pj/zudo-front-builder/docs/concepts/client-side-routing/) for the full API. #### `navigate()` needs `` mounted on the current page The root barrel exports `navigate` and `syncHistoryEntry`, but **not** `init`, and importing from that barrel installs no interception listeners. Each helper still does exactly what its own docs say when you call it — a direct `navigate()` call navigates, `syncHistoryEntry()` writes its history entry — but nothing starts intercepting the user's link clicks and form submits on your behalf. Soft navigation needs two separate things on the current page: 1. **The opt-in meta tag.** `navigate()` reaches ``, which `` renders into ``, before it will do a soft swap; with that tag absent it falls back to a full `location.href` load. 2. **An activated router.** That comes from `init()` — in a normal zfb build, from the `import "@takazudo/zfb-runtime/client-router"` the island scanner injects once it sees a page reach `` (see above). So the answer for both is the same: mount `` in the layout `` of every page that should be soft-navigable, and let the build ship the runtime. `init` itself is exported from the `@takazudo/zfb-runtime/client-router` subpath, not the root barrel, for the rare case where you want to call it directly instead of relying on the subpath's own import-time activation. #### Persisting elements and island state across navigations (`data-zfb-transition-persist`) Add `data-zfb-transition-persist=""` to an element (matched by the same `id` on both the outgoing and incoming page) to keep it alive across a soft navigation instead of letting it be discarded and re-created — the router lifts it out of the old body and reattaches it into the new one. This works on plain elements (`