{"id":21532,"library":"litestar-vite-plugin","title":"Litestar Vite","description":"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.","status":"active","version":"0.22.1","language":"javascript","source_language":"en","source_url":"https://github.com/litestar-org/litestar-vite","tags":["javascript","litestar","vite","vite-plugin","typescript"],"install":[{"cmd":"npm install litestar-vite-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add litestar-vite-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add litestar-vite-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for dev server and build; version 7 or 8 is mandatory.","package":"vite","optional":false}],"imports":[{"note":"ESM-only package since v0.18.0; CommonJS require will fail.","wrong":"const litestarVitePlugin = require('litestar-vite-plugin')","symbol":"litestarVitePlugin","correct":"import litestarVitePlugin from 'litestar-vite-plugin'"},{"note":"Named export, not default. TypeScript type available.","wrong":"import ViteConfig from 'litestar-vite-plugin'","symbol":"ViteConfig","correct":"import { ViteConfig } from 'litestar-vite-plugin'"},{"note":"Inertia helper is in a subpath export; direct import from main package will fail with v0.21+.","wrong":"import { resolvePageComponent } from 'litestar-vite-plugin'","symbol":"resolvePageComponent","correct":"import { resolvePageComponent } from 'litestar-vite-plugin/inertia'"}],"quickstart":{"code":"# Install Python and JS packages\npip install litestar-vite\nnpm install litestar-vite-plugin@^0.22\n\n# Python app.py\nimport os\nfrom pathlib import Path\nfrom litestar import Litestar, get\nfrom litestar.response import Template\nfrom litestar_vite import PathConfig, ViteConfig, VitePlugin\n\nDEV_MODE = os.getenv(\"VITE_DEV_MODE\", \"true\").lower() in (\"true\", \"1\", \"yes\")\n\n@get(\"/\")\nasync def index() -> Template:\n    return Template(\"index.html\")\n\napp = Litestar(\n    route_handlers=[index],\n    plugins=[VitePlugin(config=ViteConfig(\n        dev_mode=DEV_MODE,\n        paths=PathConfig(root=Path(__file__).parent / \"frontend\"),\n    ))],\n)\n\n# Frontend setup (run these commands)\n# litestar assets init --template vue\n# litestar assets install\n# litestar run --reload","lang":"python","description":"Shows minimal Litestar app with Vite plugin, including backend setup, plugin config, and CLI commands for scaffolding and running."},"warnings":[{"fix":"Use import { resolvePageComponent } from 'litestar-vite-plugin/inertia'.","message":"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.","severity":"breaking","affected_versions":">=0.21.0"},{"fix":"Use ES import syntax or dynamic import().","message":"In v0.18.0, the package switched to ESM-only. CommonJS require('litestar-vite-plugin') fails with ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=0.18.0"},{"fix":"Upgrade Vite to version 7 or 8.","message":"In v0.20.0, Vite 8 support was added; Vite 6 support was dropped. Peer dep now requires ^7.0.0 || ^8.0.0.","severity":"breaking","affected_versions":">=0.20.0"},{"fix":"Use mode='framework' instead.","message":"The 'ssr' mode alias was deprecated in favor of 'framework' mode. Using mode='ssr' still works but logs a deprecation warning.","severity":"deprecated","affected_versions":"<0.23.0"},{"fix":"Add future: { useScriptElementForInitialPage: true } to Inertia createInertiaApp options, or set InertiaConfig(use_script_element=False) in Python config.","message":"Inertia v2 apps must manually set useScriptElementForInitialPage: true in createInertiaApp when using script-element bootstrap (default since v0.18). Otherwise initial page load fails.","severity":"gotcha","affected_versions":">=0.18.0"},{"fix":"Set ViteConfig(asset_url='/static/') and ensure Vite build base matches.","message":"Asset URL paths must match the 'asset_url' config (default '/static/'). Misconfiguration leads to 404s for JS/CSS files in production.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set environment variable VITE_PROXY_MODE=direct to bypass proxy.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to ES module import: import litestarVitePlugin from 'litestar-vite-plugin'; or use dynamic import().","cause":"Using require() with an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/litestar-vite-plugin/dist/index.js not supported."},{"fix":"Use named import: import { ViteConfig } from 'litestar-vite-plugin'.","cause":"Importing default export instead of named export for ViteConfig or other named symbols.","error":"TypeError: litestarVitePlugin is not a function"},{"fix":"Upgrade to litestar-vite-plugin@^0.21 and use import { resolvePageComponent } from 'litestar-vite-plugin/inertia'.","cause":"Using an older version (<0.21.0) that doesn't have the subpath export, or incorrect import path.","error":"Module not found: Can't resolve 'litestar-vite-plugin/inertia'"},{"fix":"Set base in vite.config.ts to match Litestar's asset_url, e.g., base: '/static/'.","cause":"Asset URL mismatch between Vite config base and Litestar asset_url.","error":"[vite:load-fallback] Could not load /static/vite.svg (404)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}