Litestar Vite

0.22.1 verified Mon Apr 27 auth: no javascript

Litestar Vite connects the Litestar Python backend to a Vite frontend toolchain. Current stable version is 0.22.1, with monthly releases. It supports SPA, Template, Inertia v2/v3, and framework-mode (Astro, Nuxt, SvelteKit) workflows. Key differentiators: one-port dev by proxying Vite through Litestar, optional type generation via OpenAPI/Inertia metadata, and a CLI for asset scaffolding. Peer dependency on Vite 7 or 8. Ships TypeScript types.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/litestar-vite-plugin/dist/index.js not supported. ↓

cause Using require() with an ESM-only package.

fix

Change to ES module import: import litestarVitePlugin from 'litestar-vite-plugin'; or use dynamic import().

error TypeError: litestarVitePlugin is not a function ↓

cause Importing default export instead of named export for ViteConfig or other named symbols.

fix

Use named import: import { ViteConfig } from 'litestar-vite-plugin'.

error Module not found: Can't resolve 'litestar-vite-plugin/inertia' ↓

cause Using an older version (<0.21.0) that doesn't have the subpath export, or incorrect import path.

fix

Upgrade to litestar-vite-plugin@^0.21 and use import { resolvePageComponent } from 'litestar-vite-plugin/inertia'.

error [vite:load-fallback] Could not load /static/vite.svg (404) ↓

cause Asset URL mismatch between Vite config base and Litestar asset_url.

fix

Set base in vite.config.ts to match Litestar's asset_url, e.g., base: '/static/'.

Warnings

breaking In v0.21.0, Inertia v3 support was added. The resolvePageComponent import moved to a subpath export. Older imports from 'litestar-vite-plugin' directly will break. ↓

fix Use import { resolvePageComponent } from 'litestar-vite-plugin/inertia'.

breaking In v0.18.0, the package switched to ESM-only. CommonJS require('litestar-vite-plugin') fails with ERR_REQUIRE_ESM. ↓

fix Use ES import syntax or dynamic import().

breaking In v0.20.0, Vite 8 support was added; Vite 6 support was dropped. Peer dep now requires ^7.0.0 || ^8.0.0. ↓

fix Upgrade Vite to version 7 or 8.

deprecated The 'ssr' mode alias was deprecated in favor of 'framework' mode. Using mode='ssr' still works but logs a deprecation warning. ↓

fix Use mode='framework' instead.

gotcha Inertia v2 apps must manually set useScriptElementForInitialPage: true in createInertiaApp when using script-element bootstrap (default since v0.18). Otherwise initial page load fails. ↓

fix Add future: { useScriptElementForInitialPage: true } to Inertia createInertiaApp options, or set InertiaConfig(use_script_element=False) in Python config.

gotcha Asset URL paths must match the 'asset_url' config (default '/static/'). Misconfiguration leads to 404s for JS/CSS files in production. ↓

fix Set ViteConfig(asset_url='/static/') and ensure Vite build base matches.

gotcha When using dev proxy (default), certain Vite plugins that modify asset paths may cause HMR to fail. Use VITE_PROXY_MODE=direct to switch to two-port mode. ↓

fix Set environment variable VITE_PROXY_MODE=direct to bypass proxy.

Install

npm install litestar-vite-plugin

yarn add litestar-vite-plugin

pnpm add litestar-vite-plugin

Imports

litestarVitePlugin

wrong

const litestarVitePlugin = require('litestar-vite-plugin')

correct

import litestarVitePlugin from 'litestar-vite-plugin'

ESM-only package since v0.18.0; CommonJS require will fail.

ViteConfig

wrong

import ViteConfig from 'litestar-vite-plugin'

correct

import { ViteConfig } from 'litestar-vite-plugin'

Named export, not default. TypeScript type available.

resolvePageComponent

wrong

import { resolvePageComponent } from 'litestar-vite-plugin'

correct

import { resolvePageComponent } from 'litestar-vite-plugin/inertia'

Inertia helper is in a subpath export; direct import from main package will fail with v0.21+.

Quickstart

Shows minimal Litestar app with Vite plugin, including backend setup, plugin config, and CLI commands for scaffolding and running.

# Install Python and JS packages
pip install litestar-vite
npm install litestar-vite-plugin@^0.22

# Python app.py
import os
from pathlib import Path
from litestar import Litestar, get
from litestar.response import Template
from litestar_vite import PathConfig, ViteConfig, VitePlugin

DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")

@get("/")
async def index() -> Template:
    return Template("index.html")

app = Litestar(
    route_handlers=[index],
    plugins=[VitePlugin(config=ViteConfig(
        dev_mode=DEV_MODE,
        paths=PathConfig(root=Path(__file__).parent / "frontend"),
    ))],
)

# Frontend setup (run these commands)
# litestar assets init --template vue
# litestar assets install
# litestar run --reload