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 under asset_url.
Type-safe frontends: optional OpenAPI/routes export + @hey-api/openapi-ts via 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 config
litestar assets init --template react|vue|svelte|... — scaffold frontend
litestar assets build / serve — build or watch
litestar assets deploy --storage gcs://bucket/assets — upload via fsspec
litestar assets generate-types — OpenAPI + routes → TS types
litestar 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.
--fix can rewrite simple vite.config values (assetUrl, bundleDir, hotFile, type paths) after creating a backup.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

litestar_vite-0.18.4.tar.gz (421.3 kB view details)

Uploaded Mar 5, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

litestar_vite-0.18.4-py3-none-any.whl (230.5 kB view details)

Uploaded Mar 5, 2026 Python 3

File details

Details for the file litestar_vite-0.18.4.tar.gz.

File metadata

Download URL: litestar_vite-0.18.4.tar.gz
Upload date: Mar 5, 2026
Size: 421.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for litestar_vite-0.18.4.tar.gz
Algorithm	Hash digest
SHA256	`b7490ef57701786f284dbbc62801061b398b8bfb6c73e69bcced1d2e2f456b25`
MD5	`43db82f55908f7fab7f3d10c0d66b71e`
BLAKE2b-256	`867895c6b539caf2743f0bfca0f4523353a031f31f8abb5a3732b0b0e00f19c8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for litestar_vite-0.18.4.tar.gz:

Publisher: publish.yml on litestar-org/litestar-vite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: litestar_vite-0.18.4.tar.gz
- Subject digest: b7490ef57701786f284dbbc62801061b398b8bfb6c73e69bcced1d2e2f456b25
- Sigstore transparency entry: 1045506919
- Sigstore integration time: Mar 5, 2026
Source repository:
- Permalink: litestar-org/litestar-vite@aac37ca8ef81c6879c41db952a1d77bd1758543d
- Branch / Tag: refs/tags/v0.18.4
- Owner: https://github.com/litestar-org
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@aac37ca8ef81c6879c41db952a1d77bd1758543d
- Trigger Event: release