Plugin¶

Vite Plugin for Litestar.

This module provides the VitePlugin class for integrating Vite with Litestar. The plugin handles:

Static file serving configuration
Jinja2 template callable registration
Vite dev server process management
Async asset loader initialization
Development proxies for Vite HTTP and HMR WebSockets (with hop-by-hop header filtering)

Example:

from litestar import Litestar
from litestar_vite import VitePlugin, ViteConfig

app = Litestar(
    plugins=[VitePlugin(config=ViteConfig(dev_mode=True))],
)

litestar_vite.plugin.set_environment(config: ViteConfig, asset_url_override: str | None = None) → None[source]¶

Configure environment variables for Vite integration.

Sets environment variables that can be used by both the Python backend and the Vite frontend during development.

Parameters:

config¶ – The Vite configuration.
asset_url_override¶ – Optional asset URL to force (e.g., CDN base during build).

litestar_vite.plugin.set_app_environment(app: Litestar) → None[source]¶

Set environment variables derived from the Litestar app instance.

This is called after set_environment() once the app is available, to export app-specific configuration like OpenAPI paths.

Parameters:: app¶ – The Litestar application instance.

litestar_vite.plugin.resolve_litestar_version() → str[source]¶

Return the installed Litestar version string.

Returns:: The installed Litestar version, or “unknown” when unavailable.

litestar_vite.plugin.get_litestar_route_prefixes(app: Litestar) → tuple[str, ...][source]¶

Build a cached list of Litestar route prefixes for the given app.

This function collects all registered route paths from the Litestar application and caches them for efficient lookup. The cache is stored in app.state to ensure it’s automatically cleaned up when the app is garbage collected.

Includes: - All registered Litestar route paths - OpenAPI schema path (customizable via openapi_config.path) - Common API prefixes as fallback (/api, /schema, /docs)

Parameters:: app¶ – The Litestar application instance.
Returns:: A tuple of route prefix strings (without trailing slashes).

litestar_vite.plugin.is_litestar_route(path: str, app: Litestar) → bool[source]¶

Check if a path matches a registered Litestar route.

This function determines if a request path should be handled by Litestar rather than proxied to the Vite dev server or served as SPA content.

A path matches if it equals a registered prefix or starts with prefix + “/”.

Parameters:

path¶ – The request path to check (e.g., “/schema”, “/api/users”).
app¶ – The Litestar application instance.

Returns:

True if the path matches a Litestar route, False otherwise.

class litestar_vite.plugin.ViteProxyMiddleware[source]¶

Bases: AbstractMiddleware

ASGI middleware to proxy Vite dev HTTP traffic to internal Vite server.

HTTP requests use httpx.AsyncClient with optional HTTP/2 support for better connection multiplexing. WebSocket traffic (used by Vite HMR) is handled by a dedicated WebSocket route handler created by create_vite_hmr_handler().

The middleware reads the Vite server URL from the hotfile dynamically, ensuring it always connects to the correct Vite server even if the port changes.

__init__(app: ASGIApp, hotfile_path: Path, asset_url: str | None = None, resource_dir: Path | None = None, bundle_dir: Path | None = None, root_dir: Path | None = None, http2: bool = True) → None[source]¶

Initialize the middleware.

Parameters:

app¶ – The next ASGI app to call.
exclude¶ – A pattern or list of patterns to match against a request’s path. If a match is found, the middleware will be skipped.
exclude_opt_key¶ – An identifier that is set in the route handler opt key which allows skipping the middleware.
scopes¶ – ASGI scope types, should be a set including either or both ‘ScopeType.HTTP’ and ‘ScopeType.WEBSOCKET’.

class litestar_vite.plugin.ExternalDevServerProxyMiddleware[source]¶

Bases: AbstractMiddleware

ASGI middleware to proxy requests to an external dev server (deny list mode).

This middleware proxies all requests that don’t match Litestar-registered routes to the target dev server. It supports two modes:

Static target: Provide a fixed URL (e.g., “http://localhost:4200” for Angular CLI)
Dynamic target: Leave target as None and provide hotfile_path - the proxy reads the target URL from the Vite hotfile (for SSR frameworks like Astro, Nuxt, SvelteKit)

Unlike ViteProxyMiddleware (allow list), this middleware: - Uses deny list approach: proxies everything EXCEPT Litestar routes - Supports both static and dynamic target URLs - Auto-excludes Litestar routes, static mounts, and schema paths

__init__(app: ASGIApp, target: str | None = None, hotfile_path: Path | None = None, http2: bool = False, litestar_app: Litestar | None = None) → None[source]¶

Initialize the external dev server proxy middleware.

Parameters:

app¶ – The ASGI application to wrap.
target¶ – Static target URL to proxy to (e.g., “http://localhost:4200”). If None, uses hotfile_path for dynamic target discovery.
hotfile_path¶ – Path to the Vite hotfile for dynamic target discovery. Used when target is None (SSR frameworks with dynamic ports).
http2¶ – Enable HTTP/2 for proxy connections.
litestar_app¶ – Optional Litestar app instance for route exclusion.

litestar_vite.plugin.create_vite_hmr_handler(hotfile_path: Path, hmr_path: str = '/static/vite-hmr', asset_url: str = '/static/') → Any[source]¶

Create a WebSocket route handler for Vite HMR proxy.

This handler proxies WebSocket connections from the browser to the Vite dev server for Hot Module Replacement (HMR) functionality.

Parameters:

hotfile_path¶ – Path to the hotfile written by the Vite plugin.
hmr_path¶ – The path to register the WebSocket handler at.
asset_url¶ – The asset URL prefix to strip when connecting to Vite.

Returns:

A WebsocketRouteHandler that proxies HMR connections.

litestar_vite.plugin.create_ssr_proxy_controller(target: str | None = None, hotfile_path: Path | None = None, http2: bool = True) → type[source]¶

Create a Controller that proxies to an SSR framework dev server.

This controller is used for SSR frameworks (Astro, Nuxt, SvelteKit) where all non-API requests should be proxied to the framework’s dev server for rendering.

Parameters:

target¶ – Static target URL to proxy to. If None, uses hotfile for dynamic discovery.
hotfile_path¶ – Path to the hotfile for dynamic target discovery.
http2¶ – Enable HTTP/2 for proxy connections.

Returns:

A Litestar Controller class with HTTP and WebSocket handlers for SSR proxy.

class litestar_vite.plugin.StaticFilesConfig[source]¶

Bases: object

Configuration for static file serving.

This configuration is passed to Litestar’s static files router.

__init__(after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, before_request: BeforeRequestHookHandler | None = None, cache_control: CacheControlHeader | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: list[Guard] | None = None, middleware: Sequence[Middleware] | None = None, opt: dict[str, Any] | None = None, security: Sequence[SecurityRequirement] | None = None, tags: Sequence[str] | None = None) → None¶

class litestar_vite.plugin.ViteProcess[source]¶

Bases: object

Manages the Vite development server process.

This class handles starting and stopping the Vite dev server process, with proper thread safety and graceful shutdown. It registers signal handlers for SIGTERM and SIGINT to ensure child processes are terminated even if Python is killed externally.

__init__(executor: JSExecutor) → None[source]¶

Initialize the Vite process manager.

Parameters:: executor¶ – The JavaScript executor to use for running Vite.

start(command: list[str], cwd: Path | str | None) → None[source]¶

Start the Vite process.

Parameters:

command¶ – The command to run (e.g., [“npm”, “run”, “dev”]).
cwd¶ – The working directory for the process.

If the process exits immediately, this method captures stdout/stderr and raises a ViteProcessError with diagnostic details.

Raises:: ViteProcessError – If the process fails to start.

stop(timeout: float = 5.0) → None[source]¶

Stop the Vite process and all its child processes.

Uses process groups to ensure child processes (node, astro, nuxt, vite, etc.) are terminated along with the parent npm/npx process.

Parameters:: timeout¶ – Seconds to wait for graceful shutdown before killing.
Raises:: ViteProcessError – If the process fails to stop.

class litestar_vite.plugin.VitePlugin[source]¶

Bases: InitPluginProtocol, CLIPlugin

Vite plugin for Litestar.

This plugin integrates Vite with Litestar, providing:

Static file serving configuration
Jinja2 template callables for asset tags
Vite dev server process management
Async asset loader initialization

Example:

from litestar import Litestar
from litestar_vite import VitePlugin, ViteConfig

app = Litestar(
    plugins=[
        VitePlugin(config=ViteConfig(dev_mode=True))
    ],
)

__init__(config: ViteConfig | None = None, asset_loader: ViteAssetLoader | None = None, static_files_config: StaticFilesConfig | None = None) → None[source]¶

Initialize the Vite plugin.

Parameters:

config¶ – Vite configuration. Defaults to ViteConfig() if not provided.
asset_loader¶ – Optional pre-initialized asset loader.
static_files_config¶ – Optional configuration for static file serving.

property config: ViteConfig¶

Get the Vite configuration.

Returns:: The ViteConfig instance.

property asset_loader: ViteAssetLoader¶

Get the asset loader instance.

Lazily initializes the loader if not already set.

Returns:: The ViteAssetLoader instance.

property spa_handler: AppHandler | None¶

Return the configured SPA handler when SPA mode is enabled.

Returns:: The AppHandler instance, or None when SPA mode is disabled/not configured.

on_cli_init(cli: Group) → None[source]¶

Parameters:: cli¶ – The Click command group to add commands to.

on_app_init(app_config: AppConfig) → AppConfig[source]¶

Configure the Litestar application for Vite.

This method wires up supporting configuration for dev/prod operation:

Adds types used by generated handlers to the signature namespace.
Ensures a consistent NotFound handler for asset/proxy lookups.
Registers optional Inertia and Jinja integrations.
Configures static file routing when enabled.
Configures dev proxy middleware based on proxy_mode.
Creates/initializes the SPA handler where applicable and registers lifespans.

Parameters:: app_config¶ – The Litestar application configuration.
Returns:: The modified application configuration.

server_lifespan(app: Litestar) → Iterator[None][source]¶

Server-level lifespan context manager (runs ONCE per server, before workers).

This is called by Litestar CLI before workers start. It handles: - Environment variable setup (with logging) - Vite dev server process start/stop (ONE instance for all workers) - Type export on startup

Note: SPA handler and asset loader initialization happens in the per-worker lifespan method, which is auto-registered in on_app_init.

Hotfile behavior: the hotfile is written before starting the dev server to ensure proxy middleware and SPA handlers can resolve a target URL immediately on first request.

Parameters:: app¶ – The Litestar application instance.
Yields:: None

lifespan(app: Litestar) → AsyncIterator[None][source]¶

Worker-level lifespan context manager (runs per worker process).

This is auto-registered in on_app_init and handles per-worker initialization: - Environment variable setup (silently - each worker needs process-local env vars) - Asset loader initialization - SPA handler initialization - Route metadata injection

Note: The Vite dev server process is started in server_lifespan, which runs ONCE per server before workers start.

Parameters:: app¶ – The Litestar application instance.
Yields:: None