Litestar Vite

Vite plugin for Litestar

Litestar Vite connects the Litestar backend to a Vite toolchain. It supports SPA, Template, Inertia, and meta-framework workflows, and it can proxy Vite dev traffic through your ASGI port or run Vite directly.

Features

One-port dev: proxies Vite HTTP + WS/HMR through Litestar on a single ASGI port by default.
Framework-mode support: use mode="framework" (alias mode="ssr") for Astro, Nuxt, and SvelteKit. Litestar proxies everything except your API routes.
Production assets: reads the Vite manifest from public/manifest.json (configurable) and serves under asset_url.
Type-safe frontends: optional OpenAPI/routes export plus @hey-api/openapi-ts via the Vite plugin.
Inertia support: Inertia v2/v3 protocol support with session middleware, script-element bootstrap by default, and optional SSR.

Install

pip install litestar-vite
npm install litestar-vite-plugin

Quick Start

from litestar import Litestar
from litestar_vite import VitePlugin

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

litestar assets init --template vue
litestar assets install
litestar run --reload

VitePlugin() detects development and production behavior without manual VITE_DEV_MODE parsing. The effective litestar run --host/--port values are also passed to the frontend environment and .litestar.json bridge.

Optional Granian native static serving

Granian 0.16+ can serve eligible production bundle files before the request enters Python:

from litestar import Litestar
from litestar_granian import GranianPlugin
from litestar_vite import VitePlugin

app = Litestar(
    plugins=[
        VitePlugin(),
        GranianPlugin(static="auto"),
    ]
)

This is an optimization, not a separate application configuration. The Litestar static route stays registered, so Uvicorn and other ASGI servers serve the same files. Granian automatically falls back to Litestar when assets are protected, customized, missing, or otherwise unsafe to intercept.

Native hits bypass ASGI middleware, guards, compression, custom headers, and Python access logging. Keep protected or customized assets on the Litestar fallback path. See the production guide for the server matrix and advanced configuration.

Documentation

Get started: https://litestar-org.github.io/litestar-vite/latest/usage/index.html
Framework guides: https://litestar-org.github.io/litestar-vite/latest/frameworks/index.html
Inertia: https://litestar-org.github.io/litestar-vite/latest/frameworks/inertia/index.html
API reference: https://litestar-org.github.io/litestar-vite/latest/reference/index.html
Changelog: https://litestar-org.github.io/litestar-vite/latest/changelog.html

Common Commands

litestar assets init --template <name>: scaffold a frontend or framework app
litestar assets install: install frontend dependencies with the configured executor
litestar assets build: build production assets
litestar assets serve: run the frontend toolchain directly
litestar assets generate-types: export OpenAPI, routes, and Inertia page-prop metadata
litestar assets doctor: inspect and optionally repair config drift

Development

# Install Python, docs, and JS dependencies; build package artifacts
make install && make build

# Run an example app
uv run litestar --app-dir examples/vue-inertia assets install
uv run litestar --app-dir examples/vue-inertia run

Replace vue-inertia with any other example app: vue, react, svelte, react-inertia, htmx, angular, astro, nuxt, or sveltekit.

litestar-vite now defaults Inertia apps to script-element bootstrap. Inertia v3 clients use that transport automatically; if you pin Inertia v2, keep createInertiaApp({ defaults: { future: { useScriptElementForInitialPage: true } } }) aligned in the browser entry and SSR entry when ssr=True is enabled, or opt back into the legacy data-page path with InertiaConfig(use_script_element=False).