Inertia SSR (JS)

Server-side rendering settings for Inertia.js responses (Node SSR server).

InertiaConfig(ssr=True) enables a separate Node SSR server for initial HTML responses. Litestar sends the full Inertia page object to that server, then injects the rendered head tags and body markup back into the HTML response.

This SSR path is distinct from framework proxy mode:

  • Inertia SSR: InertiaConfig(ssr=True)

  • Meta-framework proxy mode: ViteConfig(mode="framework") or alias mode="ssr"

Typical file layout:

  • Browser entry: resources/main.tsx or resources/main.ts

  • Node SSR entry: resources/ssr.tsx or resources/ssr.ts

When you also enable use_script_element=True for an Inertia v2 client:

  • Keep defaults.future.useScriptElementForInitialPage in the browser entry so hydration reads the initial page payload correctly instead of expecting the default data-page attribute.

  • Mirror the same option in the Node SSR entry because Inertia applies the same defaults during server rendering.

Note

This guidance is intentionally scoped to current Inertia v2 clients. The official v3 upgrade guide removes the future config namespace and changes the bootstrap default.

Selector behavior follows SPAConfig.app_selector. If you render into #root instead of #app, keep the browser template, SSR output, and app selector aligned so Litestar can replace the correct wrapper element during the initial SSR response.

class litestar_vite.config.InertiaSSRConfig[source]

Bases: object

Server-side rendering settings for Inertia.js.

Inertia SSR runs a separate Node server that renders the initial HTML for an Inertia page object. Litestar sends the page payload to the SSR server (by default at http://127.0.0.1:13714/render) and injects the returned head tags and body markup into the HTML response.

Notes

  • This is not Litestar-Vite’s framework proxy mode (mode="framework"; aliases: mode="ssr" / mode="ssg").

  • When enabled, failures to contact the SSR server are treated as errors (no silent fallback).

__init__(enabled: bool = True, url: str = 'http://127.0.0.1:13714/render', timeout: float = 2.0) → None