Skip to content

Architecture Overview

Litestar Vite bridges two runtimes with distinct responsibilities:

  • Litestar (Python ASGI) owns routing, dependency injection, authentication guards, OpenAPI/AsyncAPI schema metadata, CSRF protection, and HTML shell or JSON serialization.
  • Vite 7+ (JavaScript / TypeScript) owns ES module transformation, Hot Module Replacement (HMR), CSS/Tailwind pipelines, SSR module execution (RunnableDevEnvironment), and production Rollup/Rolldown bundling.

Use the interactive switcher below to inspect how HTML shell ownership, routing, and data transport change across the four operating modes:

SPA Mode Architecture (mode="spa") AppHandler serves a transformed index.html shell; client router owns navigation and fetches JSON from Litestar OpenAPI routes via @hey-api/openapi-ts and route(). HTML Shell Owner AppHandler (index.html) Injects window.__LITESTAR_CSRF__ Catch-all SPA fallback routes Navigation & Router Client Router React Router / Vue Router / TanStack route() & createRouteHelpers() Data Transport @hey-api/openapi-ts SDK JSON REST + csrfFetch() createTypedChannels() WS/SSE
Hybrid Inertia.js Architecture (mode="hybrid") Litestar controllers own routing and return component PageProps; Inertia.js swaps components via X-Inertia JSON and supports SSR via _InertiaSlots. HTML Shell & SSR AppHandler / Jinja + SSR data-page or <script id="app_page"> Optional Dev TCP / Prod Stdio SSR Server-Driven Routing @get(..., component="...") Python guards & DI own every route resolvePageComponent() on client Inertia.js Protocol PageProps[T] JSON defer() • merge() • lazy() • once() Generated page-props.ts types
Template + Server Islands Architecture (mode="template") Jinja2 templates render server HTML using vite() and vite_hmr(), progressively enhanced with HTMX swap="json", <litestar-stream>, and <litestar-island> fragments. Jinja2 / Server HTML {{ vite('src/main.ts') }} {{ vite_hmr() }} in development {{ vite_fragment('Chart.tsx') }} Server Fragments & Islands <litestar-island> ComponentResponse (HX-Push-Url) hydrateIslands() (React/Vue/Svelte) HTMX & Realtime Streams hx-swap="json" ls-for • ls-if • CSRF auto-header <litestar-stream> WebSocket/SSE
Meta-Framework Architecture (mode="framework" / "external") Astro, SvelteKit, or Nuxt owns its server/SSR pipeline while litestar-vite-plugin/{astro,sveltekit,nuxt} synchronizes ports, proxies /api, and runs typegen. Meta-Framework Server Astro / SvelteKit / Nuxt 4 litestar-vite-plugin/{astro,nuxt,...} Writes hotfile on server listen Proxy & Port Bridge .litestar.json + proxyMode Forwards /api/* to Litestar Routes HMR through Litestar port Shared TypeGen Output openapi.json + routes.json Typed load() / useFetch() calls Zero duplicate schema config

Operating Mode Matrix

Operating Mode HTML Shell Owner Router Owner Primary Data Transport Typical Stack
mode="spa" AppHandler (index.html) Client router @hey-api/openapi-ts + route() React Router, Vue Router, TanStack Router
mode="hybrid" AppHandler / Jinja + SSR Litestar (component=) Inertia.js PageProps JSON @inertiajs/react, @inertiajs/vue3, @inertiajs/svelte
mode="template" Jinja2 (vite(), vite_hmr()) Litestar controllers Server HTML + <litestar-island> + HTMX Jinja2, HTMX (hx-swap="json"), WebSocket/SSE
mode="framework" Meta-framework server Meta-framework router /api/* proxy + shared TypeGen Astro 5, SvelteKit, Nuxt 4

Development vs. Production Execution

During development (dev_mode=True), Litestar proxies asset and HMR WebSocket traffic to a live Vite 7+ process over a single browser origin (127.0.0.1:8000). In production (dev_mode=False), Node is not required for static assets: ViteAssetLoader resolves hashed bundles from manifest.json while Litestar serves immutable static files directly.

Development Mode vs. Production Mode Asset and SSR Execution Side-by-side comparison of Development Mode (hot file discovery, ViteProxyMiddleware streaming, unbundled ESM + HMR) and Production Mode (manifest.json resolution via ViteAssetLoader, immutable static caching, and persistent StdioIPCTransport SSR worker). Development Mode (dev_mode=True) Hot-file discovery • Live Vite ESM & HMR ViteAssetLoader (Hot-File Mode) Reads public/hot → injects @vite/client ViteProxyMiddleware (Single-Port :8000) Streams assets & /vite-hmr to Vite (:5173) Dev SSR & Fragments (TCPStreamIPCTransport) POST /__litestar_ssr__ → Vite ServerModuleRunner Production Mode (dev_mode=False) Zero Dev Server • Immutable Hashed Bundles ViteAssetLoader (Manifest Mode) Parses manifest.json → hashed CSS/JS tags Static Asset Serving Immutable caching + metadata blocking Prod SSR Worker (StdioIPCTransport) NDJSON stdin/stdout pool + SSRCircuitBreaker

Architecture Deep Dives

  • Single-Port Dev Proxy & Bridge

    How the development proxy streams HTTP/1.1 assets and tunnels HMR WebSockets without CORS overhead, coordinated by .litestar.json and the hot file.

    Explore Dev Proxy & Bridge

  • SSR, Server Fragments, & IPC Transports

    How Inertia responses and server fragments render components across Vite's dev runner in development and persistent worker pools in production with circuit-breaker fallback.

    Explore SSR & IPC

  • End-to-End TypeGen Pipeline

    How Python route and schema introspection emits deterministic OpenAPI, route, Inertia page-props, and AsyncAPI artifacts consumed by the Vite plugin.

    Explore Codegen Pipeline