Inertia.js Overview & Protocol Lifecycle¶

Inertia.js lets you build modern React, Vue 3, and Svelte 5 single-page applications using classic server-side routing and controllers. Instead of building a separate REST or GraphQL API for every screen, your Litestar route handlers declare component="Users/Index" and return Python dict, msgspec.Struct, dataclass, or Pydantic models directly.

How the Inertia Protocol Works in Litestar¶

1. Initial Full-Page Visit:
2. The browser sends a standard HTTP request without an X-Inertia header.
3. InertiaResponse serializes the PageProps JSON envelope into <script type="application/json" id="app_page" data-page="app"> (or the legacy data-page attribute on #app when use_script_element=False).
4. When InertiaConfig(ssr=True) is enabled, Litestar Vite pre-renders the initial HTML via the SSR IPC transport before returning the page.
5. Subsequent Client Navigation:
6. Clicking an Inertia <Link> or calling router.visit() sends an XHR/Fetch request with X-Inertia: true and X-Inertia-Version.
7. Litestar detects the Inertia visit and returns application/json containing only the PageProps envelope, swapping the page component in place without a full browser reload.
8. Deferred Props & Partial Reloads:
9. Props wrapped in defer() are omitted from the initial response and listed in deferredProps.
10. Immediately after mounting the initial page, the Inertia client fires batched background partial reloads to resolve each deferred group.
11. Mutations & Asset Version Rotation:
12. Following POST, PUT, PATCH, or DELETE requests, InertiaMiddleware converts 302 redirects into 303 See Other so the browser follows up with a GET request.
13. If the frontend bundle hash changes between deployments (X-Inertia-Version mismatch), Litestar responds with 409 Conflict and X-Inertia-Location, prompting a clean full-page reload.

Protocol Headers & Status Codes¶

The PageProps Wire Envelope¶

Optional protocol keys (flash, deferredProps, mergeProps, prependProps, deepMergeProps, matchPropsOn, scrollProps, onceProps) are omitted when empty to keep wire payloads minimal:

{
  "component": "Posts/Index",
  "props": {
    "errors": {},
    "csrf_token": "9f86d081884c7d659a2feaa0c55ad015",
    "auth": { "user": { "id": 1, "name": "Alice" } },
    "posts": [{ "id": 10, "title": "Hello Inertia" }]
  },
  "url": "/posts?page=1",
  "version": "e3b0c44298fc1c149afbf4c8996fb924",
  "encryptHistory": false,
  "clearHistory": false,
  "flash": { "success": ["Post published"] },
  "deferredProps": { "default": ["analytics"] },
  "mergeProps": ["posts"],
  "matchPropsOn": ["posts.id"]
}

Inertia Guide Directory¶