litestar-org/litestar-skills/litestar-vite

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.33.0. Features include server-rendered UI component fragments, persistent IPC SSR transports with circuit-breaker fallback, AsyncAPI 3.0 typed channel generation, Vite 7+ support, and single-port development proxying. 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.

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

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)
• 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",
)

CLI:

litestar assets generate-types          # one-off generation
litestar assets export-routes           # routes.json metadata (--only, --except, --include-components)
litestar assets export-routes --typescript  # routes.ts only
litestar --app app:app run              # generates on startup if enabled

Frontend consumption:

// routes + CSRF constants (0.31.0+)
import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, route } from "@/generated/routes"
import { csrfFetch, csrfHeaders, getCsrfHeaderName, getCsrfToken } from "litestar-vite-plugin/helpers"
const url = route("users:get", { id: 123 })
await csrfFetch(url, { method: "POST" }, { headerName: CSRF_HEADER_NAME, cookieName: CSRF_COOKIE_NAME })
// hey-api output
import type { User } from "@/generated/api"
// ergonomic route helpers
import type { FormInput } from "@/generated/schemas"
type LoginInput = FormInput<"auth:login">

ViteAssetLoader, Secondary HTML Entries, and Component Fragments

Auto-registered Jinja2 globals when a template engine is configured:

Minimal base template:

<!DOCTYPE html>
<html>
<head>
  {{ vite_hmr() }}
  {{ vite('resources/main.tsx') }}
</head>
<body>
  <div id="app"></div>
</body>
</html>

For programmatic asset loading (ViteAssetLoader, resolve_html_entry) or server-rendered <litestar-island> UI component fragments (ComponentResponse(..., mode="island")), see Modes and Config.

CLI

litestar assets init             # Scaffold vite.config.ts and package.json
litestar assets install          # Run npm/pnpm/bun install
litestar assets update           # Update within package.json semver ranges
litestar assets serve            # Start Vite dev server (also auto-started when `dev_mode=True`)
litestar assets build            # Production build (emits manifest.json + hashed bundles)
litestar assets deploy --dry-run # Build and preview an fsspec-backed deployment
litestar assets deploy           # Build and sync to DeployConfig.storage_backend
litestar assets generate-types   # TypeScript type generation
litestar assets export-routes    # routes.json metadata
litestar assets doctor           # Diagnose integration health
litestar assets status           # Read-only status summary

assets init --template accepts react, react-router, react-tanstack, react-inertia, react-inertia-jinja, vue, vue-inertia, vue-inertia-ssr, vue-inertia-jinja, vue-inertia-jinja-ssr, svelte, svelte-inertia, svelte-inertia-jinja, sveltekit, nuxt, astro, htmx, jinja-htmx, htmx-no-jinja, angular, and angular-cli.

HMR & Production Build

• Dev Mode (Single-Port Proxy): Vite runs on runtime.port and writes paths.hot_file; Litestar proxies asset HTTP and the HMR WebSocket (/static/vite-hmr) so the browser uses a single public origin. In Vite 8.1+, place explicit HMR network overrides under server.ws (not server.hmr). See HMR Reference.
• Production Build: Run litestar assets build (or litestar assets deploy) with dev_mode=False. Asset loading checks <bundle_dir>/<manifest_name> then <bundle_dir>/.vite/<manifest_name>. See Deployment Reference.

Inertia & HTMX Integration

• Inertia (`mode="hybrid"`): Configure ViteConfig(mode="hybrid", inertia=InertiaConfig(...)) on a single VitePlugin. Return msgspec.Struct(..., rename="camel") prop bags from @get(..., component="...") handlers (field renames are preserved at top level). Stage share(), flash(), error(), and clear_history() in InertiaTransientState, wire csrfHeaders() into createInertiaApp({ defaults: { visitOptions } }), read flash messages from top-level usePage().flash, and pass uninvoked callables to defer / lazy / optional / once. See Inertia Reference, Deferred & Merge Props, and Advanced Inertia Patterns.
• HTMX (`mode="template"`): Pair ViteConfig(mode="template") with TemplateConfig and HTMXPlugin().

<workflow>

Workflow