litestar-vite

litestar-vite is the first-party plugin that connects a Vite frontend build pipeline to a Litestar backend. It handles dev-server proxying, HMR coordination, manifest resolution for production assets, and (optionally) end-to-end type generation from Litestar OpenAPI to TypeScript.

The runtime has four canonical modes: spa, template, hybrid, and framework. htmx, inertia, ssr, and ssg are aliases that normalize to those modes. external is a fifth, permanent alias of framework; it still requires an ExternalDevServer.

The plugin pairs with the npm package litestar-vite-plugin on the JS side. Python ViteConfig is the source of truth; the generated .litestar.json bridge lets JS config normally keep only litestar({ input: [...] }).

This guidance targets litestar-vite 0.32.0. Releases 0.26.0 through 0.31.0 hardened Inertia protocol behavior, msgspec.Struct field-rename preservation, secondary HTML entry resolution (resolve_html_entry), handler-level static auth exclusion (exclude_static_from_auth), CSRF constant emission in routes.ts, Precognition validation, scaffolds, type generation, single-port HMR routing, manifest fallback, deployment, plugin activation, and lifecycle logging. 0.32.0 adds server-rendered UI component fragments (ComponentResponse, FragmentEngine, vite_fragment, render_fragment, <litestar-island>), persistent IPC SSR transports (TCPStreamIPCTransport to /__litestar_ssr__ in dev, StdioIPCTransport over stdin/stdout in prod) with circuit-breaker fallback (SSRCircuitBreaker), AsyncAPI 3.0 typed channel generation (AsyncAPIPlugin + TypeGenConfig(generate_channels=True) + createTypedChannels), a Vite >=7.0.0 peer dependency floor, and the single-port AnyIO streaming proxy (ViteProxyMiddleware + /static/vite-hmr). See Release Updates.

Code Style Rules

• Python: PEP 604 unions (T | None); consumer Litestar app modules MAY use from __future__ import annotations.
• TypeScript: strict mode; defineConfig from vite; one vite.config.ts per frontend project.
• Keep ViteConfig as the source of truth. Only duplicate bundleDir, hotFile, or assetUrl in vite.config.ts for deliberate standalone/override workflows.
• Inertia (mode="hybrid"): use msgspec.Struct(..., rename="camel") for structured page-prop returns, wire csrfHeaders() into createInertiaApp({ defaults: { visitOptions } }), use useForm for mutations, and read flash notifications from top-level usePage().flash (dict[str, list[str]]), never usePage().props.flash.