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 use the default script-element bootstrap transport:

  • Inertia v3 clients use the script-element bootstrap by default, so no extra client defaults block is required.

  • Inertia v2 clients must keep defaults.future.useScriptElementForInitialPage in the browser entry so hydration reads the initial page payload correctly instead of expecting the default data-page attribute.

  • Inertia v2 SSR entries should mirror the same option because Inertia applies the same defaults during server rendering.

  • Set use_script_element=False if you need to keep the legacy data-page attribute bootstrap.

Note

This guidance is intentionally version-scoped. Inertia v2 still uses the future namespace for script-element bootstrap, while Inertia v3 removes that extra client configuration.

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.

When command is set, the plugin spawns the Node /render server in the server lifespan (mirroring Vite process management) and tears it down on shutdown. This makes SSR examples self-contained — no second terminal needed.

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).

target_selector: str = '#app'

CSS selector for the element whose outer HTML is replaced by the SSR-rendered body.

Used by _render_template (template mode) to locate the mount point in the rendered Jinja HTML. Defaults to #app to match Inertia’s convention.

For mode="hybrid", SPAConfig.app_selector is the source of truth and this field is ignored — SPA config already governs the SPA shell selector.

command: list[str] | None = None

Command to start the Node /render server, e.g. ["npm", "run", "start:ssr"].

When set, the plugin spawns the command as a subprocess in the server lifespan and stops it on shutdown. Set to None to disable auto-start (run the SSR server manually in a separate terminal).

cwd: Path | None = None

Working directory for the SSR command. Defaults to ViteConfig.root_dir when None.

auto_start: bool = True

When True and command is set, the plugin starts the Node SSR process in lifespan.

Set to False to keep the command around for documentation but skip auto-start (useful when running under an external process manager).

health_check: bool = False

When True, poll the SSR url until it responds before completing app startup.

Default is False so the SSR process starts in the background and Litestar can serve requests immediately. Set to True if you want startup to block until /render is ready (catches misconfigured commands early at the cost of slower boot).

health_check_timeout: float = 10.0

Seconds to wait for the SSR endpoint to become reachable during startup.

Only consulted when health_check is True. On timeout the plugin logs a warning and continues — startup is not aborted.

__init__(enabled: bool = True, url: str = 'http://127.0.0.1:13714/render', timeout: float = 2.0, target_selector: str = '#app', command: list[str] | None = None, cwd: TypeAliasForwardRef('pathlib.Path') | None = None, auto_start: bool = True, health_check: bool = False, health_check_timeout: float = 10.0) → None