References

A consolidated cheat-sheet for @zerotal/inertia. Each entry links to the section above where it's explained in full.

Commands

Command	Purpose
`bun zt make:page <Name>`	Scaffold a page component under your pages directory.
`bun zt make:page <Name> --layout <Layout>`	Scaffold a page wrapped in a persistent layout.
`bun zt make:page <Name> --framework <vue\|react>`	Force the frontend framework instead of auto-detecting.
`bun zt inertia:build`	Bundle the frontend — development build (external source maps).
`bun zt inertia:build -p`	Production build (minified, no source maps).

Server exports

Export	Purpose
`inertia(component, props?)`	Render an Inertia page from a controller action. See the inertia helper.
`inertia.dynamic(component, props?)`	Render a page whose name is only known at runtime — no compile-time checking. See what is not checked.
`inertiaStream(component, props?)`	Streaming SSR alternative to `inertia()`. See Streaming SSR.
`inertiaStream.dynamic(component, props?)`	The streaming counterpart of `inertia.dynamic()`.
`optional(fn)` / `lazy(fn)`	Prop sent only on a partial reload that requests it. See optional and always props.
`always(value)`	Prop always sent, even when a partial reload would exclude it.
`defer(fn, group?, opts?)`	Prop fetched in a follow-up request after first paint. See deferred props.
`merge(value)` / `deepMerge(value)`	Combine reloaded data with existing client data. See merging props.
`scroll(paginator, opts?)`	Infinite-scroll pagination wired to `<InfiniteScroll>`. See infinite scroll.
`sharedProps()`	The auto-merged `auth` / `flash` / `errors` / `old` bag. See Shared Props.
`share(key, value)` / `share(map)`	Register custom shared props. See adding custom shared props.
`setAssetVersion(v)` / `assetVersion()`	Set / read the current asset version. See asset versioning.
`generatePageRegistry(cwd?)`	Regenerate the page registry module. See page registry.
`inertiaRoute(path, component, props?, middleware?)`	The function behind the `Router.inertia()` macro. See controller-less routes.
`InertiaProvider`	Wires the middleware, template, asset version, and optional SSR endpoint. See Register the provider.
`InertiaMiddleware`	Protocol mechanics; auto-registered by the provider. See Middleware & versioning.
`PrecognitionMiddleware`	Enables precognition validation. See precognition.
`InertiaConfig(options?)`	Build a typed `config/inertia.ts` object with defaults. See Configuration.
`Inertia`	Unified facade — see below.

The Inertia facade

Method	Equivalent / purpose
`Inertia.render(component, props?)`	Same as `inertia()`.
`Inertia.stream(component, props?)`	Same as `inertiaStream()`.
`Inertia.optional(fn)` / `Inertia.lazy(fn)`	Same as `optional()`.
`Inertia.always(value)`	Same as `always()`.
`Inertia.defer(fn, group?, opts?)`	Same as `defer()`.
`Inertia.merge(value)` / `Inertia.deepMerge(value)`	Same as `merge()` / `deepMerge()`.
`Inertia.scroll(paginator, opts?)`	Same as `scroll()`.
`Inertia.share(key, value)` / `Inertia.share(map)`	Register custom shared props. See adding custom shared props.
`Inertia.location(url)`	External / full-page redirect (`409` + `X-Inertia-Location`). See external & fragment redirects.
`Inertia.encryptHistory()`	Encrypt this page's history entry. See history encryption.
`Inertia.clearHistory()`	Clear encrypted history (e.g. on logout).

Prop helpers

Helper / chain	Behaviour
`optional(fn)`	Never sent on a normal visit; only on a partial reload that asks for it.
`lazy(fn)`	Alias of `optional(fn)`.
`always(value)`	Always sent, even past a partial reload's include / exclude filter.
`defer(fn, group?, { rescue? })`	Excluded from the first render; fetched in a grouped follow-up request.
`merge(value)` / `deepMerge(value)`	Append / deep-merge reloaded data instead of replacing it.
`.append(path)`	Append merged data at `path`.
`.prepend(path?)`	Prepend merged data at the root (no arg) or at `path`.
`.matchOn(path)`	Replace items matching the key at `path`.
`.once(expiresAt?)`	Resolve a single time; the client remembers it across navigations. See once props.

Each helper returns a wrapper class — OptionalProp, AlwaysProp, DeferProp, MergeProp, InfiniteScrollProp, all extending InertiaProp. You build them through the helpers above rather than constructing them; the names matter only for annotating a variable or narrowing a union, and InertiaProp is the type to accept when a function takes "any wrapped prop".

Errors

Error	Thrown when
`InertiaError`	Base class for the rest — catch this to handle any Inertia failure.
`InvalidComponentError`	A page component name is empty or not a string.
`InertiaTemplateNotLoadedError`	The root template was never loaded, so there is no HTML shell to render a page in.

Server-side rendering

SsrHandler is the class behind InertiaConfig({ ssr: true }) — it owns the POST /__ssr route the config registers. Configure SSR through the config flag; the class is exported for tests that drive the handler directly. See SSR.

Configuration options

Set in config/inertia.ts via InertiaConfig({ … }) — every field is optional.

Option	Default	Purpose
`htmlTemplate`	`"./resources/app.html"`	Path to the root HTML template (must contain `<!-- @inertia -->`); falls back to a built-in default.
`version`	`"1"`	Asset version string embedded in every page object; bump on each deploy.
`assetsUrl`	`"/"`	Public URL prefix for built assets.
`pagesDir`	`"resources/js/pages"`	Directory where Inertia page components live.
`ssr`	`false`	Register `POST /__ssr` for endpoint SSR.
`encryptHistory`	`false`	Encrypt history state globally.

Protocol headers

Header	Direction	Used for
`X-Inertia`	request / response	Marks an Inertia XHR visit; echoed on the response.
`X-Inertia-Version`	request	Client's asset version — a mismatch triggers a `409` reload.
`X-Inertia-Partial-Data` / `X-Inertia-Partial-Except`	request	Partial-reload prop include / exclude lists.
`X-Inertia-Partial-Component`	request	The component a partial reload targets.
`X-Inertia-Reset`	request	Props to clear before merging fresh data.
`X-Inertia-Except-Once-Props`	request	Once-props the client already holds.
`X-Inertia-Error-Bag`	request	Namespaces validation errors under a named bag.
`X-Inertia-Infinite-Scroll-Merge-Intent`	request	`prepend` vs append intent when scrolling up.
`Precognition` / `Precognition-Validate-Only`	request	Precognition validation and field scoping.
`Vary: X-Inertia`	response	Keeps cached HTML and JSON variants separate.
`X-Inertia-Location`	response	`409` full-page reload / external redirect target.
`X-Inertia-Redirect`	response	`409` redirect that preserves a URL fragment.

Page object fields

See page object reference for the full table of fields — component, props, url, version, deferredProps, mergeProps, scrollProps, onceProps, and the rest — and which API sets each.

Types

Everything here is type-only, and exists so Inertia.render can be checked against the page it names. See Typed props.

Type	Purpose
`InertiaPageRegistry`	Augmentation target the generated `pages.generated.ts` fills with `{ pages: typeof pages }`. Empty until the registry is built.
`SharedProps`	Declare your own `Inertia.share()` keys here; they become optional-but-accepted in every render call.
`PageName`	Union of the generated page names (`never` before the registry exists).
`PageTarget`	What the helpers accept as a name: `PageName` once generated, `string` before that.
`PropsOf<N>`	The props page `N`'s component declares.
`PropInput<T>`	What may be passed for a prop typed `T` — the value, a factory, or a wrapper carrying it.
`RenderProps<N>`	The full props bag `Inertia.render(N, …)` accepts, shared props subtracted.
`RenderArgs<N>`	`render()`'s argument tuple; the props bag is optional only when the page requires nothing.
`PageRenderer`	The shape of `inertia` / `inertiaStream`: a checked call signature plus `.dynamic`.