/litestar-vite

name: litestar-vite
description: "Use when working with litestar_vite, VitePlugin, ViteConfig, PathConfig, TypeGenConfig, vite.config.ts, InertiaConfig, component=, or @inertiajs/*. Not for plain Vite or server-only HTMX."

litestar-vite

`litestar-vite` is the first-party plugin that connects a [Vite](https://vite.dev/) 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`](https://www.npmjs.com/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.33.0. Features include server-rendered UI component fragments, persistent stdio and QuickJS WASM (`WasmIPCTransport`) SSR transports with circuit-breaker fallback, lockfile JS runtime auto-detection (`detect_runtime`), RFC 8288 `Link` preload / `103 Early Hints` / immutable cache headers, AsyncAPI 3.0 typed channel generation, Vite 7+ support, and single-port development proxying. See [Release Updates](references/release-updates.md).

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

Quick Reference

Minimal SPA setup (Python side)

from litestar import Litestar
from litestar_vite import PathConfig, ViteConfig, VitePlugin

vite_config = ViteConfig(
    mode="spa",
    enabled=True,
    paths=PathConfig(
        resource_dir="resources",
        bundle_dir="public",
        hot_file="hot",
    ),
    dev_mode=True,
)

app = Litestar(plugins=[VitePlugin(config=vite_config)])

Minimal SPA setup (JS side)

// vite.config.ts
import { defineConfig } from "vite"
import litestar from "litestar-vite-plugin"
import react from "@vitejs/plugin-react"

export default defineConfig({
  clearScreen: false,
  publicDir: "public",
  plugins: [
    react(),
    litestar({
      input: ["resources/main.tsx", "resources/main.css"],
    }),
  ],
  resolve: { alias: { "@": "/resources" } },
})

Mode Selection

| Mode | Use For | Key Setup | | --- | --- | --- | | `spa` | React, Vue, Svelte, or Analog-powered Angular SPA with a Litestar JSON API backend | `dev_mode=True` proxies to Vite; manifest in prod | | `template` (`htmx` alias) | Server-rendered Jinja2/Mako pages and HTMX with Vite-bundled assets | Use `TemplateConfig`; add `litestar-htmx` when using HTMX | | `hybrid` (`inertia` alias) | Inertia.js routes returning JS page components | Configure `ViteConfig(inertia=InertiaConfig(...))` | | `framework` (`ssr` / `ssg` aliases) | Nuxt, SvelteKit, Astro, Angular CLI, or another frontend-owned HTML server | Use the framework entry point or `ExternalDevServer` |

Decision tree:

• Need full SPA with client-side routing → **spa**
• Server-rendered HTML, sprinkle Vite-bundled JS → **template**
• HTMX-driven hypermedia with Vite assets → **template** (`htmx` alias) + `HTMXPlugin`
• Server-side routing + JS page components, shared data → **hybrid** (`inertia` alias; see [Inertia Reference](references/inertia.md))
• Nuxt, SvelteKit, or Astro owns HTML → **framework**
• Angular CLI or another non-Vite server → **framework** + `ExternalDevServer`

`VitePlugin` config (Python)

from litestar_vite import (
    PathConfig,
    RuntimeConfig,
    TypeGenConfig,
    ViteConfig,
    VitePlugin,
)

vite_config = ViteConfig(
    mode="spa",
    enabled=True,
    dev_mode=False,
    paths=PathConfig(
        root=".",
        resource_dir="src",
        bundle_dir="public",
        static_dir="src/public",
        hot_file="hot",
        asset_url="/static/",
    ),
    runtime=RuntimeConfig(
        port=5173,
        host="localhost",
        protocol="http",
        executor="bun",
    ),
    types=TypeGenConfig(
        generate_zod=False,
        generate_sdk=True,
        generate_routes=True,
        generate_schemas=True,
        generate_page_props=False,
        output="src/generated",
    ),
)

`enabled=None` auto-detects serving contexts and consults `VITE_ENABLED`. `enabled=False` leaves `VitePlugin.config` and asset CLI commands available but skips runtime routes, middleware, static routers, lifespans, and the SPA handler.

Type Generation

TypeGenConfig(
    generate_sdk=True,
    generate_routes=True,
    generate_schemas=True,
    generate_page_props=True,
    output="src/generated",
)

| Output | Path | Trigger | Frontend Use | | --- | --- | --- | --- | | `openapi.json` | `output/openapi.json` | Whenever OpenAPI schema changes | Source of truth for SDK + schemas | | `routes.json` | `output/routes.json` | Route table changes | Route metadata consumed by the JS plugin | | `routes.ts` | `output/routes.ts` | Route table or `app.csrf_config` changes | `route("name", { params })` typed URL builder + `CSRF_COOKIE_NAME` / `CSRF_HEADER_NAME` (`0.31.0+`) |