Upgrade Guide¶

Move existing Litestar-Vite Inertia apps from Inertia v2 to Inertia v3 without losing compatibility for projects that stay on v2.

Version Support¶

litestar-vite supports Inertia v2 and v3.

Generated templates and examples now target Inertia v3.
Existing Inertia v2 projects remain supported.
The main version-specific difference in this repository is script-element bootstrap configuration.

What Changes In This Repository¶

litestar-vite now defaults Inertia apps to script-element bootstrap:

Inertia v3 clients use the script-element bootstrap by default.
Inertia v2 clients must still enable defaults.future.useScriptElementForInitialPage in createInertiaApp(...).
If InertiaConfig(ssr=True) is enabled, Inertia v2 SSR entries must mirror that same setting.

The generated page-props.ts contract now also matches runtime behavior for non-mapping handler returns by nesting those payloads under content.

Upgrade Steps¶

Bump your frontend adapter package to Inertia v3.
- React: @inertiajs/react@3
- Vue: @inertiajs/vue3@3
- Svelte: @inertiajs/svelte@3
Remove explicit use_script_element=True if you previously added it just to enable the default transport.
Remove the Inertia v2-only client opt-in:
```
defaults: {
  future: {
    useScriptElementForInitialPage: true,
  },
}
```
In Inertia v3, that transport is already the default.
If you use an SSR entry (resources/ssr.tsx / resources/ssr.ts), remove the same defaults.future.useScriptElementForInitialPage block there too.
Reinstall dependencies and regenerate package lockfiles so the adapter upgrade is reflected in committed manifests.

Framework Notes¶

React projects in this repository already use React 19, which matches Inertia v3 requirements.
Vue projects in this repository already use Vue 3 and only need the adapter bump.
Svelte Inertia scaffolds in this repository already use Svelte 5, which matches Inertia v3 support.

Staying On Inertia v2¶

If you are not ready to upgrade yet, keep your current Inertia v2 adapter package and retain the defaults.future.useScriptElementForInitialPage client configuration while using the default script-element transport, or set InertiaConfig(use_script_element=False) to stay on the legacy data-page bootstrap.