Config¶

Litestar-Vite Configuration.

This module provides the configuration dataclasses for the Vite integration. The configuration is split into logical groups:

PathConfig: File system paths
RuntimeConfig: Execution settings
TypeGenConfig: Type generation settings
ViteConfig: Root configuration combining all sub-configs

Example usage:

# Minimal - SPA mode with defaults
VitePlugin(config=ViteConfig())

# Development mode
VitePlugin(config=ViteConfig(dev_mode=True))

# With type generation
VitePlugin(config=ViteConfig(dev_mode=True, types=True))

# Template mode for HTMX
VitePlugin(config=ViteConfig(mode="template", dev_mode=True))

class litestar_vite.config.DeployConfig[source]¶

Bases: object

CDN deployment configuration.

enabled¶

Enable deployment features.

Type:: bool

storage_backend¶

fsspec URL for the target location (e.g., gcs://bucket/path).

Type:: str | None

storage_options¶

Provider options forwarded to fsspec (credentials, region, etc.).

Type:: dict[str, Any]

delete_orphaned¶

Remove remote files not present in the local bundle.

Type:: bool

include_manifest¶

Upload manifest.json alongside assets.

Type:: bool

content_types¶

Optional content-type overrides keyed by file extension.

Type:: dict[str, str]

__init__(enabled: bool = False, storage_backend: str | None = <factory>, storage_options: dict[str, ~typing.Any] = <factory>, delete_orphaned: bool = <factory>, include_manifest: bool = True, content_types: dict[str, str] = <factory>) → None¶

__post_init__() → None[source]¶: Apply environment fallbacks.

with_overrides(storage_backend: str | None = None, storage_options: dict[str, Any] | None = None, delete_orphaned: bool | None = None) → DeployConfig[source]¶

Return a copy with overrides applied.

Parameters:

storage_backend¶ – Override for the storage URL.
storage_options¶ – Override for backend options.
delete_orphaned¶ – Override deletion behaviour.

Returns:

DeployConfig copy with updated fields.

class litestar_vite.config.InertiaConfig[source]¶

Bases: object

Inertia.js specific settings.

enabled¶

Enable Inertia.js integration.

Type:: bool

root_template¶

Root HTML template for Inertia.

Type:: str

include_routes¶

Include routes metadata in page props.

Type:: bool

include_flash¶

Include flash messages in page props.

Type:: bool

include_errors¶

Include validation errors in page props.

Type:: bool

extra_static_page_props¶

Additional static props to include on every page.

Type:: dict[str, object]

extra_session_page_props¶

Session keys to include as page props.

Type:: list[str]

__init__(enabled: bool = False, root_template: str = 'index.html', include_routes: bool = True, include_flash: bool = True, include_errors: bool = True, extra_static_page_props: dict[str, object] = <factory>, extra_session_page_props: list[str] = <factory>) → None¶

class litestar_vite.config.PathConfig[source]¶

Bases: object

File system paths configuration.

root¶

The root directory of the project. Defaults to current working directory.

Type:: str | Path

bundle_dir¶

Location of compiled assets and manifest.json.

Type:: str | Path

resource_dir¶

TypeScript/JavaScript source directory (equivalent to ./src in Vue/React).

Type:: str | Path

public_dir¶

Static public assets directory (served as-is by Vite).

Type:: str | Path

manifest_name¶

Name of the Vite manifest file.

Type:: str

hot_file¶

Name of the hot file indicating dev server URL.

Type:: str

asset_url¶

Base URL for static asset references (prepended to Vite output).

Type:: str

ssr_output_dir¶

SSR output directory (optional).

Type:: str | Path | None

__post_init__() → None[source]¶: Normalize path types to Path objects.

__init__(root: str | Path = <factory>, bundle_dir: str | Path = <factory>, resource_dir: str | Path = <factory>, public_dir: str | Path = <factory>, manifest_name: str = 'manifest.json', hot_file: str = 'hot', asset_url: str = <factory>, ssr_output_dir: str | Path | None = None) → None¶

class litestar_vite.config.RuntimeConfig[source]¶

Bases: object

Runtime execution settings.

dev_mode¶

Enable development mode with HMR/watch.

Type:: bool

hot_reload¶

Enable Hot Module Replacement (HMR).

Type:: bool

host¶

Vite dev server host.

Type:: str

port¶

Vite dev server port.

Type:: int

protocol¶

Protocol for dev server (http/https).

Type:: Literal[‘http’, ‘https’]

executor¶

JavaScript runtime executor (node, bun, deno).

Type:: Literal[‘node’, ‘bun’, ‘deno’, ‘yarn’, ‘pnpm’] | None

run_command¶

Custom command to run Vite dev server (auto-detect if None).

Type:: list[str] | None

build_command¶

Custom command to build with Vite (auto-detect if None).

Type:: list[str] | None

build_watch_command¶

Custom command for watch mode build.

Type:: list[str] | None

install_command¶

Custom command to install dependencies.

Type:: list[str] | None

is_react¶

Enable React Fast Refresh support.

Type:: bool

ssr_enabled¶

Enable Server-Side Rendering.

Type:: bool

health_check¶

Enable health check for dev server startup.

Type:: bool

detect_nodeenv¶

Detect and use nodeenv in virtualenv (opt-in).

Type:: bool

set_environment¶

Set Vite environment variables from config.

Type:: bool

set_static_folders¶

Automatically configure static file serving.

Type:: bool

csp_nonce¶

Content Security Policy nonce for inline scripts.

Type:: str | None

proxy_mode¶

Proxy mode for dev server requests.

Type:: Literal[‘proxy’, ‘direct’]

spa_handler¶

Auto-register catch-all SPA route when mode=”spa”.

Type:: bool

http2¶

Enable HTTP/2 for proxy HTTP requests (better multiplexing). WebSocket traffic (HMR) uses a separate connection and is unaffected.

Type:: bool

__post_init__() → None[source]¶: Set default commands based on executor.

__init__(dev_mode: bool = <factory>, hot_reload: bool = <factory>, host: str = <factory>, port: int = <factory>, protocol: ~typing.Literal['http', 'https'] = 'http', executor: ~typing.Literal['node', 'bun', 'deno', 'yarn', 'pnpm'] | None = None, run_command: list[str] | None = None, build_command: list[str] | None = None, build_watch_command: list[str] | None = None, install_command: list[str] | None = None, is_react: bool = False, ssr_enabled: bool = False, health_check: bool = <factory>, detect_nodeenv: bool = False, set_environment: bool = True, set_static_folders: bool = True, csp_nonce: str | None = None, proxy_mode: ~typing.Literal['proxy', 'direct'] = <factory>, spa_handler: bool = True, http2: bool = True) → None¶

class litestar_vite.config.SPAConfig[source]¶

Bases: object

Configuration for SPA HTML transformations.

This configuration controls how the SPA HTML is transformed before serving, including route metadata injection, CSRF token injection, and Inertia.js page data handling.

inject_routes¶

Whether to inject route metadata into HTML.

Type:: bool

inject_csrf¶

Whether to inject CSRF token into HTML (as window.__LITESTAR_CSRF__).

Type:: bool

routes_var_name¶

Global variable name for routes (e.g., window.__LITESTAR_ROUTES__).

Type:: str

csrf_var_name¶

Global variable name for CSRF token (e.g., window.__LITESTAR_CSRF__).

Type:: str

routes_include¶

Whitelist patterns for route filtering (None = include all).

Type:: list[str] | None

routes_exclude¶

Blacklist patterns for route filtering (None = exclude none).

Type:: list[str] | None

app_selector¶

CSS selector for the app root element (used for data attributes).

Type:: str

cache_transformed_html¶

Cache transformed HTML in production; disabled when inject_csrf=True because CSRF tokens are per-request.

Type:: bool

__init__(inject_routes: bool = True, inject_csrf: bool = True, routes_var_name: str = '__LITESTAR_ROUTES__', csrf_var_name: str = '__LITESTAR_CSRF__', routes_include: list[str] | None = <factory>, routes_exclude: list[str] | None = <factory>, app_selector: str = '#app', cache_transformed_html: bool = True) → None¶

class litestar_vite.config.TypeGenConfig[source]¶

Bases: object

Type generation settings.

enabled¶

Enable type generation pipeline.

Type:: bool

output¶

Output directory for generated types.

Type:: pathlib.Path

openapi_path¶

Path to export OpenAPI schema.

Type:: pathlib.Path

routes_path¶

Path to export routes metadata.

Type:: pathlib.Path

generate_zod¶

Generate Zod schemas from OpenAPI.

Type:: bool

generate_sdk¶

Generate SDK client from OpenAPI.

Type:: bool

watch_patterns¶

File patterns to watch for type regeneration.

Type:: list[str]

__post_init__() → None[source]¶: Normalize path types.

__init__(enabled: bool = False, output: ~pathlib.Path = <factory>, openapi_path: ~pathlib.Path = <factory>, routes_path: ~pathlib.Path = <factory>, generate_zod: bool = True, generate_sdk: bool = False, watch_patterns: list[str] = <factory>) → None¶

class litestar_vite.config.ViteConfig[source]¶

Bases: object

Root Vite configuration.

This is the main configuration class that combines all sub-configurations. Supports shortcuts for common configurations:

dev_mode: Shortcut for runtime.dev_mode
types=True: Enable type generation with defaults
inertia=True: Enable Inertia.js with defaults

Mode auto-detection:

If mode is not explicitly set:
- Checks for index.html in resource_dir -> SPA mode
- Checks if Jinja2 template engine is configured -> Template mode
- Otherwise defaults to SPA mode
Explicit mode parameter overrides auto-detection

mode¶

Serving mode - “spa”, “template”, or “htmx”. Auto-detected if not set.

Type:: Literal[‘spa’, ‘template’, ‘htmx’] | None

paths¶

File system paths configuration.

Type:: litestar_vite.config.PathConfig

runtime¶

Runtime execution settings.

Type:: litestar_vite.config.RuntimeConfig

types¶

Type generation settings (True enables with defaults).

Type:: TypeGenConfig | bool

inertia¶

Inertia.js settings (True enables with defaults).

Type:: InertiaConfig | bool

spa¶

SPA transformation settings (True enables with defaults, False disables).

Type:: SPAConfig | bool | None

dev_mode¶

Convenience shortcut for runtime.dev_mode.

Type:: bool

base_url¶

Base URL for production assets (CDN support).

Type:: str | None

deploy¶

Deployment configuration for CDN publishing.

Type:: DeployConfig | bool

__post_init__() → None[source]¶: Normalize configurations and apply shortcuts.

validate_mode() → None[source]¶

Validate the mode configuration against the project structure.

Raises:: ValueError – If the configuration is invalid for the selected mode.

property executor: JSExecutor¶: Get the JavaScript executor instance.

property bundle_dir: Path¶: Get bundle directory path.

property resource_dir: Path¶: Get resource directory path.

property public_dir: Path¶: Get public directory path.

property root_dir: Path¶: Get root directory path.

property manifest_name: str¶: Get manifest file name.

property hot_file: str¶: Get hot file name.

property asset_url: str¶: Get asset URL.

property host: str¶: Get dev server host.

property port: int¶: Get dev server port.

property protocol: str¶: Get dev server protocol.

property hot_reload: bool¶: Check if hot reload is enabled.

property is_dev_mode: bool¶: Check if dev mode is enabled.

property is_react: bool¶: Check if React mode is enabled.

property ssr_enabled: bool¶: Check if SSR is enabled.

property run_command: list[str]¶: Get the run command.

property build_command: list[str]¶: Get the build command.

property build_watch_command: list[str]¶: Get the build watch command.

property install_command: list[str]¶: Get the install command.

property health_check: bool¶: Check if health check is enabled.

property set_environment: bool¶: Check if environment should be set.

property set_static_folders: bool¶: Check if static folders should be configured.

property detect_nodeenv: bool¶: Check if nodeenv detection is enabled.

property proxy_mode: Literal['proxy', 'direct']¶: Get proxy mode (proxy=single-port via ASGI, direct=expose Vite port).

property spa_handler: bool¶: Check if SPA handler auto-registration is enabled.

property http2: bool¶: Check if HTTP/2 is enabled for proxy connections.

property ssr_output_dir: Path | None¶: Get SSR output directory.

property spa_config: SPAConfig | None¶

Get SPA configuration if enabled, or None if disabled.

Returns:: SPAConfig instance if spa transformations are enabled, None otherwise.

property deploy_config: DeployConfig | None¶

Get deploy configuration if enabled.

Returns:: DeployConfig instance when deployment is configured, None otherwise.

__init__(mode: Literal['spa', 'template', 'htmx'] | None = None, paths: ~litestar_vite.config.PathConfig = <factory>, runtime: ~litestar_vite.config.RuntimeConfig = <factory>, types: TypeGenConfig | bool = <factory>, inertia: InertiaConfig | bool = False, spa: SPAConfig | bool | None = None, dev_mode: bool = False, base_url: str | None = <factory>, deploy: DeployConfig | bool = False, _executor_instance: JSExecutor | None = None, _mode_auto_detected: bool = False) → None¶