Registry / web-framework / litestar-vite-plugin

litestar-vite-plugin

library0.22.1jsnpmunverified

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.

web-framework devops

npm install litestar-vite-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · LITESTAR-VITE-PLUG

litestar-vite-plugin

web-frameworkjavascriptv0.22.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

litestarVitePlugin

✓ import litestarVitePlugin from 'litestar-vite-plugin'

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

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

ViteConfig

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

✗ import ViteConfig from 'litestar-vite-plugin'

Named export, not default. TypeScript type available.

resolvePageComponent

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

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

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

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

litestar --version

Debug

Known issues

breakingIn 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'.

affects: >=0.21.0

breakingIn 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().

affects: >=0.18.0

breakingIn 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.

affects: >=0.20.0

deprecatedThe '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.

affects: <0.23.0

gotchaInertia 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.

affects: >=0.18.0

gotchaAsset 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.

affects: >=0.1.0

gotchaWhen 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

Using require() with an ESM-only package.

fix

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

TypeError: litestarVitePlugin is not a function

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

fix

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

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

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'.

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

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/'.

Upgrade

Version history

0.22.1latest on npm

Audit

Dependencies

viterequiredPeer dependency required for dev server and build; version 7 or 8 is mandatory.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/litestar-org/litestar-vite ↗

packagehttps://www.npmjs.com/package/litestar-vite-plugin ↗