Litestar Vite
Litestar Vite connects the Litestar backend to a Vite toolchain. It supports SPA, Template, and Inertia flows, and can proxy Vite dev traffic through your ASGI port or run Vite directly.
Features
- One-port dev: proxies Vite HTTP + WS/HMR through Litestar by default; switch to two-port with
VITE_PROXY_MODE=direct. - SSR framework support: use
mode="ssr"for Astro, Nuxt, SvelteKit - proxies everything except your API routes. - Production assets: reads Vite manifest from
public/manifest.json(configurable) and serves underasset_url. - Type-safe frontends: optional OpenAPI/routes export +
@hey-api/openapi-tsvia the Vite plugin. - Inertia support: v2 protocol with session middleware and optional SPA mode.
Quick Start (SPA)
pip install litestar-vite
import os
from pathlib import Path
from litestar import Litestar
from litestar_vite import VitePlugin, ViteConfig, PathConfig
DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
app = Litestar(
plugins=[VitePlugin(config=ViteConfig(
dev_mode=DEV_MODE,
paths=PathConfig(root=Path(__file__).parent),
))]
)
litestar run --reload # Vite dev server is proxied automatically
Scaffold a frontend: litestar assets init --template vue (or react, svelte, htmx, react-inertia, vue-inertia, angular, astro, nuxt, sveltekit).
Development
To contribute or run the development project:
# Install all dependencies and build packages
make install && make build
# Install frontend dependencies for an example
uv run litestar --app-dir examples/vue-inertia assets install
# Run the development server
uv run litestar --app-dir examples/vue-inertia run
Replace vue-inertia with any other example: vue, react, svelte, react-inertia, htmx, angular, astro, nuxt, or sveltekit.
Template / HTMX
from pathlib import Path
from litestar import Litestar
from litestar.contrib.jinja import JinjaTemplateEngine
from litestar.template import TemplateConfig
from litestar_vite import VitePlugin, ViteConfig, PathConfig
here = Path(__file__).parent
app = Litestar(
template_config=TemplateConfig(directory=here / "templates", engine=JinjaTemplateEngine),
plugins=[VitePlugin(config=ViteConfig(
dev_mode=True,
paths=PathConfig(root=here),
))],
)
Inertia (v2)
Requires session middleware (32-char secret).
import os
from pathlib import Path
from litestar import Litestar
from litestar.middleware.session.client_side import CookieBackendConfig
from litestar_vite import VitePlugin, ViteConfig, PathConfig
from litestar_vite.inertia import InertiaConfig
here = Path(__file__).parent
SECRET_KEY = os.environ.get("SECRET_KEY", "development-only-secret-32-chars")
session = CookieBackendConfig(secret=SECRET_KEY.encode("utf-8"))
app = Litestar(
middleware=[session.middleware],
plugins=[VitePlugin(config=ViteConfig(
dev_mode=True,
paths=PathConfig(root=here),
inertia=InertiaConfig(root_template="index.html"),
))],
)
Meta-frameworks (Astro, Nuxt, SvelteKit)
Use mode="ssr" (or mode="framework") to proxy non-API routes to the framework's dev server:
import os
from pathlib import Path
from litestar import Litestar
from litestar_vite import VitePlugin, ViteConfig, PathConfig
here = Path(__file__).parent
DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
app = Litestar(
plugins=[
VitePlugin(config=ViteConfig(
mode="ssr",
dev_mode=DEV_MODE,
paths=PathConfig(root=here),
))
],
)
Proxy Modes
| Mode | Alias | Use Case |
|---|---|---|
vite |
- | SPAs - proxies Vite assets only (default) |
direct |
- | Two-port dev - expose Vite port directly |
proxy |
ssr |
Meta-frameworks - proxies everything except API routes |
Production Deployment
Astro (static): Astro generates static HTML by default. Build and serve with Litestar:
litestar --app-dir examples/astro assets install
litestar --app-dir examples/astro assets build
VITE_DEV_MODE=false litestar --app-dir examples/astro run
Nuxt/SvelteKit (SSR): These run their own Node servers. Deploy as two services:
# Terminal 1: SSR server
litestar --app-dir examples/nuxt assets build
litestar --app-dir examples/nuxt assets serve
# Terminal 2: Litestar API
VITE_DEV_MODE=false litestar --app-dir examples/nuxt run --port 8001
Type generation
VitePlugin(config=ViteConfig(types=True)) # enable exports
litestar assets generate-types # one-off or CI
CLI cheat sheet
litestar assets doctor— diagnose/fix configlitestar assets init --template react|vue|svelte|...— scaffold frontendlitestar assets build/serve— build or watchlitestar assets deploy --storage gcs://bucket/assets— upload via fsspeclitestar assets generate-types— OpenAPI + routes → TS typeslitestar assets install— install frontend deps with the configured executor
Doctor command highlights
- Prints Python vs Vite config snapshot (asset URLs, bundle/hot paths, ports, modes).
- Flags missing hot file (dev proxy), missing manifest (prod), type-gen exports, env/config mismatches, and plugin install issues.
--fixcan rewrite simple vite.config values (assetUrl, bundleDir, hotFile, type paths) after creating a backup.
Links
- Docs: https://litestar-org.github.io/litestar-vite/
- Examples:
examples/(react, vue, svelte, react-inertia, vue-inertia, astro, nuxt, sveltekit, htmx) - Real-world example: litestar-fullstack - Full-featured application using litestar-vite
- Issues: https://github.com/litestar-org/litestar-vite/issues/
2 maintainers
Metadata
2 maintainers
Release files for litestar-vite 0.16.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| litestar_vite-0.16.4.tar.gz | 398.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| litestar_vite-0.16.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 625.3 kB
Release files / litestar_vite-0.16.4.tar.gz
| Download URL | litestar_vite-0.16.4.tar.gz |
|---|---|
| Size | 398.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e02a111f1eb3aee4a6d808a33f9280f0be43fd1067724c70e65e59150a0a04a
|
|
BLAKE2b-256 checksum How to use checksums |
3a3fdd684c4a42f38a5689c9cebd667b1cf32c9cc933b6a65f65c9a409ce820c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 7, 2026.
Transparency logRelease files / litestar_vite-0.16.4-py3-none-any.whl
| Download URL | litestar_vite-0.16.4-py3-none-any.whl |
|---|---|
| Size | 226.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03d3a498cac61ddea49c2b3a183bd43bdbd30fb3e2b7be6020902e36fc61c74c
|
|
BLAKE2b-256 checksum How to use checksums |
5fbb6eea185da6c575ff2af24b0e0896866e1b16fa7d2bd5a3c7a09141fc8140
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 7, 2026.
Transparency log
