Skip to content
Inertia

Requests & responses

Detecting an Inertia request

Section titled “Detecting an Inertia request”

InertiaManager.isInertiaRequest(request) is true when the request has an X-Inertia header (any value). The official clients send X-Inertia: true.

First visit → HTML

Section titled “First visit → HTML”
  • Status 200
  • Content-Type HTML
  • Body: root Crema view or rootHtml
  • View data: page (raw JSON), pageAttr (HTML-escaped for attributes), vite (script/link tags)
  • No X-Inertia response header on the plain HTML shell

Default root HTML (when Crema is unused) embeds @page inside data-page='…'.

Inertia visit → JSON

Section titled “Inertia visit → JSON”
  • Body: JSON map of the page object
  • X-Inertia: true
  • Vary: X-Inertia
  • X-Inertia-Version when the manager version is non-empty

Decoration

Section titled “Decoration”

After the route handler runs, middleware calls manager.decorate(response). If the response already has X-Inertia: true or X-Inertia-Location, and a version is set, X-Inertia-Version is added.

Explicit request render

Section titled “Explicit request render”
Inertia.render(request, "Pages/Show", mapOf("id" to 42))

Use this from code paths that are not under HandleInertiaRequests, or when you want a different request object than the ThreadLocal current.

Status codes you will see

Section titled “Status codes you will see”
Status Meaning
200 HTML shell or JSON page
302 / 303 Ordinary redirect (non-Inertia clients); Inertia adapters follow or convert
409 Asset version mismatch, or Inertia.location for Inertia clients (Redirects)

Content negotiation summary

Section titled “Content negotiation summary”

You always call Inertia.render the same way. The manager inspects the request:

X-Inertia present?
  ├─ no  → HTML (root_view / root_html) + data-page
  └─ yes → version OK? → JSON page
                      └─ no → 409
Section titled “Related”