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

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

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

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.

class litestar_vite.plugin.ViteProxyMiddleware

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

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

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

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.

class litestar_vite.plugin.StaticFilesConfig

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

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.

__init__(executor: JSExecutor) → None

Initialize the Vite process manager.

Parameters:

executor – The JavaScript executor to use for running Vite.

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

Start the Vite process.

Parameters:

• command – The command to run (e.g., [“npm”, “run”, “dev”]).

• cwd – The working directory for the process.

Raises:

ViteProcessError – If the process fails to start.

stop(timeout: float = 5.0) → None

Stop the Vite process.

Parameters:

timeout – Seconds to wait for graceful shutdown before killing.

Raises:

ViteProcessError – If the process fails to stop.

class litestar_vite.plugin.VitePlugin

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

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.

property asset_loader: ViteAssetLoader

Get the asset loader instance.

Lazily initializes the loader if not already set.

on_cli_init(cli: Group) → None

Register CLI commands.

Parameters:

cli – The Click command group to add commands to.

on_app_init(app_config: AppConfig) → AppConfig

Configure the Litestar application for Vite.

This method: - Registers Jinja2 template callables (if Jinja2 is installed and template mode) - Configures static file serving - Sets up SPA handler if in SPA mode - Sets up the server lifespan hook if enabled

Parameters:

app_config – The Litestar application configuration.

Returns:

The modified application configuration.

server_lifespan(app: Litestar) → Iterator[None]

Synchronous context manager for Vite server lifecycle.

Manages the Vite dev server process during the application lifespan.

Parameters:

app – The Litestar application instance.

Yields:

None

async_server_lifespan(app: Litestar) → AsyncIterator[None]

Async context manager for Vite server lifecycle.

This is the preferred lifespan manager for async applications. It initializes the asset loader asynchronously for non-blocking I/O.

Parameters:

app – The Litestar application instance.

Yields:

None