1. API reference
  2. @samveys/inertia

@samveys/inertia

Inertia protocol v2: ctx.inertia, partial reloads, shared props, SSR hook

Version
1.0.3Nov 5, 2026
Install
pnpm add @samveys/inertia

This list was read from version 1.0.2; run pnpm sync to refresh it.

Import 
import { always, defer, inertia, optional } from '@samveys/inertia'

Function (4)

always Function

Loaded on every visit, also when a partial reload did not list it.

function always(value: unknown): PropMarker;

Exported from packages/inertia/src/props.ts

defer Function

Left out of the first render; the client fetches it right after (v2 deferred props), in `group`.

function defer(resolve: Resolver, group?: string): PropMarker;

Exported from packages/inertia/src/props.ts

inertia Function

The `@samveys/inertia` plugin (Inertia protocol v2). Adds `ctx.inertia.render(component, props)`: the root view (through the template engine) on the first visit, a JSON page object for `X-Inertia` requests, `409` + `X-Inertia-Location` when the client's asset version is stale, partial reloads, lazy/optional/deferred props, shared props and `303` redirects after PUT/PATCH/DELETE.

function inertia(options?: InertiaOptions): import("@samveys/core").Plugin<InertiaOptions>;

Exported from packages/inertia/src/plugin.ts

optional Function

Loaded only when a partial reload asks for it by name.

function optional(resolve: Resolver): PropMarker;

Exported from packages/inertia/src/props.ts

Interface (4)

InertiaContext Interface

Per-request API exposed as `ctx.inertia`.

interface InertiaContext {
    /** Responds with the page: HTML on the first visit, JSON for `X-Inertia` requests, 409 on a version mismatch. */
    render(component: string, props?: Readonly<Record<string, unknown>>): Promise<Response>;
    /** Adds a prop to every page rendered during this request. */
    share(key: string, value: unknown): void;
    /** Redirect that Inertia clients follow: 303 after PUT/PATCH/DELETE, else 302 (or the given status). */
    redirect(location: string, status?: 301 | 302 | 303 | 307 | 308): Response;
    /** Sends the client to an external URL: 409 + `X-Inertia-Location` for Inertia requests, else a plain redirect. */
    location(url: string): Response;
}

Exported from packages/inertia/src/contracts.ts

InertiaOptions Interface

No documentation comment.

interface InertiaOptions {
    /** Template of the root view. Default `app`. */
    readonly rootView?: string;
    /** View engine that renders the root view. Default `template`. */
    readonly engine?: string;
    /** Id of the root element. Default `app`. */
    readonly id?: string;
    /** The asset version. Default: a hash of the Vite manifest when `@samveys/vite` is installed, else `''`. */
    readonly version?: string | (() => string | Promise<string>);

Exported from packages/inertia/src/contracts.ts

InertiaPage Interface

The page object sent to the client: first as `data-page`, later as the JSON body.

interface InertiaPage {
    readonly component: string;
    readonly props: Readonly<Record<string, unknown>>;
    /** Path and query of the request. */
    readonly url: string;
    /** Asset version; a client holding another version is told to reload (409). */
    readonly version: string;
    /** Props the client fetches right after the first render, by group (`defer()`). */
    readonly deferredProps?: Readonly<Record<string, readonly string[]>>;
}

Exported from packages/inertia/src/contracts.ts

InertiaSsrResult Interface

Result of the server-side rendering hook.

interface InertiaSsrResult {
    /** Markup for `<head>` (printed by `@inertiaHead`). */
    readonly head: string;
    /** Markup placed inside the root element. */
    readonly body: string;
}

Exported from packages/inertia/src/contracts.ts