How It Works

Understand the Inertia.js protocol and how it integrates with Litestar.

See also

Official Inertia.js docs: How It Works

The Inertia Protocol

Inertia.js is a protocol for building SPAs with server-side routing. Instead of returning JSON from an API, your routes return page components:

  1. Initial page load: Server renders full HTML with embedded page data

  2. Subsequent navigation: Client makes XHR request, server returns JSON

  3. Client updates: Inertia swaps page component without full reload

        sequenceDiagram
    participant Browser
    participant Server

    Note over Browser,Server: Initial Page Load
    Browser->>Server: GET /dashboard
    Server->>Browser: HTML with data-page JSON

    Note over Browser,Server: Subsequent Navigation
    Browser->>Server: XHR GET /users<br>X-Inertia: true
    Server->>Browser: JSON {component, props, url}
    Note over Browser: Swap component, update URL

Request Flow

Initial Load (Full HTML):

<!-- Server returns full HTML -->
<div id="app" data-page='{"component":"Dashboard","props":{"user":"Alice"},"url":"/dashboard"}'></div>

XHR Request (JSON):

GET /users HTTP/1.1
X-Inertia: true
X-Inertia-Version: abc123

{
  "component": "Users",
  "props": {"users": ["Alice", "Bob"]},
  "url": "/users",
  "version": "abc123"
}

Inertia Headers

The protocol uses these HTTP headers:

Header

Description

X-Inertia

Request: Client indicates Inertia request

X-Inertia-Version

Request: Asset version for cache invalidation

X-Inertia-Partial-Data

Request: Requested partial reload keys

X-Inertia-Partial-Except

Request: Keys to exclude (v2)

X-Inertia-Reset

Request: Props to reset (v2)

X-Inertia

Response: Server confirms Inertia response

X-Inertia-Location

Response: External redirect URL

Version Checking

Inertia uses asset versioning to detect outdated clients:

  1. Client sends X-Inertia-Version header

  2. Server compares with current manifest hash

  3. On mismatch, server returns 409 Conflict

  4. Client performs full page reload

Litestar-Vite automatically handles versioning using the Vite manifest.

Litestar Integration

Litestar-Vite implements the protocol through:

  • InertiaPlugin: Middleware for request/response handling

  • InertiaResponse: Response class for page data

  • InertiaMiddleware: Header parsing and validation

  • ViteAssetLoader: Asset versioning via manifest hash

# Simple Inertia route
@get("/dashboard", component="Dashboard")
async def dashboard() -> dict:
    return {"user": "Alice", "stats": {"views": 100}}

# The plugin handles:
# 1. Detecting X-Inertia header
# 2. Building PageProps object
# 3. Returning JSON or HTML based on request type
# 4. Version checking

See Also