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]

asset_url

Public URL prefix where deployed assets will be served (e.g., https://cdn.example.com/assets/). When set and deployment is enabled, this value is written to .litestar.json as deployAssetUrl and used by the Vite plugin as the base during vite build. It does not replace PathConfig.asset_url.

Type:: str | None

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]

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

with_overrides(storage_backend: str | None = None, storage_options: dict[str, Any] | None = None, asset_url: str | 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.
asset_url¶ – Override for the public asset URL.
delete_orphaned¶ – Override deletion behaviour.

Returns:

DeployConfig copy with updated fields.

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

class litestar_vite.config.ExternalDevServer[source]

Bases: object

Configuration for external (non-Vite) dev servers.

Use this when your frontend uses a framework with its own dev server (Angular CLI, Next.js, Create React App, etc.) instead of Vite.

For SSR frameworks (Astro, Nuxt, SvelteKit) using Vite internally, leave target as None - the proxy will read the dynamic port from the hotfile.

target

The URL of the external dev server (e.g., “http://localhost:4200”). If None, the proxy reads the target URL from the Vite hotfile.

Type:: str | None

command

Custom command to start the dev server (e.g., [“ng”, “serve”]). If None and start_dev_server=True, uses executor’s default start command.

Type:: list[str] | None

build_command

Custom command to build for production (e.g., [“ng”, “build”]). If None, uses executor’s default build command (e.g., “npm run build”).

Type:: list[str] | None

http2

Enable HTTP/2 for proxy connections.

Type:: bool

enabled

Whether the external proxy is enabled.

Type:: bool

__init__(target: str | None = None, command: list[str] | None = None, build_command: list[str] | None = None, http2: bool = False, enabled: bool = True) → None

class litestar_vite.config.InertiaConfig[source]

Bases: object

Configuration for InertiaJS support.

This is the canonical configuration class for Inertia.js integration. Presence of an InertiaConfig instance indicates Inertia is enabled.

Note

SPA mode (HTML transformation vs Jinja2 templates) is controlled by ViteConfig.mode=’hybrid’. The app_selector for data-page injection is configured via SPAConfig.app_selector.

root_template

Name of the root template to use.

Type:: str

component_opt_keys

Identifiers for getting inertia component from route opts.

Type:: tuple[str, …]

redirect_unauthorized_to

Path for unauthorized request redirects.

Type:: str | None

redirect_404

Path for 404 request redirects.

Type:: str | None

extra_static_page_props

Static props added to every page response.

Type:: dict[str, Any]

extra_session_page_props

Session keys to include in page props.

Type:: set[str] | dict[str, type]

root_template: str = 'index.html'

Name of the root template to use.

This must be a path that is found by the Vite Plugin template config

component_opt_keys: tuple[str, ...] = ('component', 'page')

Identifiers to use on routes to get the inertia component to render.

The first key found in the route handler opts will be used. This allows semantic flexibility - use “component” or “page” depending on preference.

Example

# All equivalent: @get(“/”, component=”Home”) @get(“/”, page=”Home”)

# Custom keys: InertiaConfig(component_opt_keys=(“view”, “component”, “page”))

redirect_unauthorized_to: str | None = None: Optionally supply a path where unauthorized requests should redirect.

redirect_404: str | None = None: Optionally supply a path where 404 requests should redirect.

extra_static_page_props: dict[str, Any]: A dictionary of values to automatically add in to page props on every response.

extra_session_page_props: set[str] | dict[str, type]

Session props to include in page responses.

Can be either: - A set of session key names (types will be ‘unknown’) - A dict mapping session keys to Python types (auto-registered with OpenAPI)

Example with types (recommended):: extra_session_page_props={“currentTeam”: TeamDetail}
Example without types (legacy):: extra_session_page_props={“currentTeam”}

encrypt_history: bool = False

Enable browser history encryption globally (v2 feature).

When True, all Inertia responses will include encryptHistory: true in the page object. The Inertia client will encrypt history state using browser’s crypto API before pushing to history.

This prevents sensitive data from being visible in browser history after a user logs out. Individual responses can override this setting.

Note: Encryption happens client-side; requires HTTPS in production. See: https://inertiajs.com/history-encryption

type_gen: InertiaTypeGenConfig | None = None

Type generation options for Inertia page props.

Controls default types in generated page-props.ts. Set to InertiaTypeGenConfig() or leave as None for defaults. Use InertiaTypeGenConfig(include_default_auth=False) to disable default User/AuthData interfaces for non-standard user models.

ssr: InertiaSSRConfig | bool | None = None

Enable server-side rendering (SSR) for Inertia responses.

When enabled, full-page HTML responses will be pre-rendered by a Node SSR server and injected into the SPA HTML before returning to the client.

Supports:

True: enable with defaults -> InertiaSSRConfig()
False/None: disabled -> None
InertiaSSRConfig: use as-is

__post_init__() → None[source]: Normalize optional sub-configs.

property ssr_config: InertiaSSRConfig | None

Return the SSR config when enabled, otherwise None.

Returns:: The resolved SSR config when enabled, otherwise None.

__init__(root_template: str = 'index.html', component_opt_keys: tuple[str, ...] = ('component', 'page'), redirect_unauthorized_to: str | None = None, redirect_404: str | None = None, extra_static_page_props: dict[str, ~typing.Any] = <factory>, extra_session_page_props: set[str] | dict[str, type] = <factory>, encrypt_history: bool = False, type_gen: ~litestar_vite.config.InertiaTypeGenConfig | None = None, ssr: ~litestar_vite.config.InertiaSSRConfig | bool | None = None) → None

class litestar_vite.config.InertiaSSRConfig[source]

Bases: object

Server-side rendering settings for Inertia.js.

Inertia SSR runs a separate Node server that renders the initial HTML for an Inertia page object. Litestar sends the page payload to the SSR server (by default at http://127.0.0.1:13714/render) and injects the returned head tags and body markup into the HTML response.

Notes

This is not Litestar-Vite’s framework proxy mode (mode="framework"; aliases: mode="ssr" / mode="ssg").
When enabled, failures to contact the SSR server are treated as errors (no silent fallback).

__init__(enabled: bool = True, url: str = 'http://127.0.0.1:13714/render', timeout: float = 2.0) → None

class litestar_vite.config.InertiaTypeGenConfig[source]

Bases: object

Type generation options for Inertia page props.

Controls which default types are included in the generated page-props.ts file. This follows Laravel Jetstream patterns - sensible defaults for common auth patterns.

include_default_auth

Include default User and AuthData interfaces. Default User has: id, email, name. Users extend via module augmentation. Set to False if your User model doesn’t have these fields (uses uuid, username, etc.)

Type:: bool

include_default_flash

Include default FlashMessages interface. Uses { [category: string]: string[] } pattern for flash messages.

Type:: bool

Example

Standard auth (95% of users) - just extend defaults:

# Python: use defaults
ViteConfig(inertia=InertiaConfig())

# TypeScript: extend User interface
declare module 'litestar-vite-plugin/inertia' {
    interface User {
        avatarUrl?: string
        roles: Role[]
    }
}

Custom auth (5% of users) - define from scratch:

# Python: disable defaults
ViteConfig(inertia=InertiaConfig(
    type_gen=InertiaTypeGenConfig(include_default_auth=False)
))

# TypeScript: define your custom User
declare module 'litestar-vite-plugin/inertia' {
    interface User {
        uuid: string  // No id!
        username: string  // No email!
    }
}

include_default_auth: bool = True

Include default User and AuthData interfaces.

When True, generates: - User: { id: string, email: string, name?: string | null } - AuthData: { isAuthenticated: boolean, user?: User }

Users extend via TypeScript module augmentation. Set to False if your User model has different required fields.

include_default_flash: bool = True

Include default FlashMessages interface.

When True, generates: - FlashMessages: { [category: string]: string[] }

Standard flash message pattern used by most web frameworks.

__init__(include_default_auth: bool = True, include_default_flash: bool = True) → None

class litestar_vite.config.LoggingConfig[source]

Bases: object

Logging configuration for console output.

Controls the verbosity and style of console output from both Python and TypeScript (via .litestar.json bridge).

level

Logging verbosity level. - “quiet”: Minimal output (errors only) - “normal”: Standard operational messages (default) - “verbose”: Detailed debugging information Can also be set via LITESTAR_VITE_LOG_LEVEL environment variable. Precedence: explicit config > env var > default (“normal”)

Type:: Literal[‘quiet’, ‘normal’, ‘verbose’]

show_paths_absolute

Show absolute paths instead of relative paths. Default False shows cleaner relative paths in output.

Type:: bool

suppress_npm_output

Suppress npm/yarn/pnpm script echo lines. When True, hides lines like “> dev” / “> vite” from output.

Type:: bool

suppress_vite_banner

Suppress the Vite startup banner. When True, only the LITESTAR banner is shown.

Type:: bool

timestamps

Include timestamps in log messages.

Type:: bool

Example

Quiet mode for CI/CD:

ViteConfig(logging=LoggingConfig(level="quiet"))

Verbose debugging:

ViteConfig(logging=LoggingConfig(level="verbose", show_paths_absolute=True))

Environment variable:

export LITESTAR_VITE_LOG_LEVEL=quiet

__init__(level: ~typing.Literal['quiet', 'normal', 'verbose'] = <factory>, show_paths_absolute: bool = False, suppress_npm_output: bool = False, suppress_vite_banner: bool = False, timestamps: bool = False) → None

class litestar_vite.config.PaginationContainer[source]

Bases: Protocol

Protocol for pagination containers that can be unwrapped for Inertia scroll.

Any type that has items and pagination metadata can implement this protocol. The response will extract items and calculate scroll_props automatically.

Built-in support: - litestar.pagination.OffsetPagination - litestar.pagination.ClassicPagination - advanced_alchemy.service.OffsetPagination

Custom types can implement this protocol:

@dataclass
class MyPagination:
    items: list[T]
    total: int
    limit: int
    offset: int

__init__(*args, **kwargs)

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

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

This also adjusts defaults to prevent Vite’s publicDir (input) from colliding with outDir (output). bundle_dir is treated as the build output directory. When static_dir equals bundle_dir, Vite may warn and effectively disable public asset copying, so static_dir defaults to <resource_dir>/public in that case.

__init__(root: str | Path = <factory>, bundle_dir: str | Path = <factory>, resource_dir: str | Path = <factory>, static_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

proxy_mode

Proxy handling mode: - “vite” (default): Proxy Vite assets only (allow list - SPA mode) - “direct”: Expose Vite port directly (no proxy) - “proxy”: Proxy everything except Litestar routes (deny list - framework mode) - None: No proxy (production mode)

Type:: Literal[‘vite’, ‘direct’, ‘proxy’] | None

external_dev_server

Configuration for external dev server (used with proxy_mode=”proxy”).

Type:: litestar_vite.config.ExternalDevServer | str | None

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

serve_command

Custom command to run production server (for SSR frameworks).

Type:: list[str] | None

install_command

Custom command to install dependencies.

Type:: list[str] | None

is_react

Enable React Fast Refresh support.

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

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]: Normalize runtime settings and apply derived defaults.

__init__(dev_mode: bool = <factory>, proxy_mode: ~typing.Literal['vite', 'direct', 'proxy'] | None = <factory>, external_dev_server: ~litestar_vite.config.ExternalDevServer | str | None = None, 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, serve_command: list[str] | None = None, install_command: list[str] | None = None, is_react: bool = False, health_check: bool = <factory>, detect_nodeenv: bool = False, set_environment: bool = True, set_static_folders: bool = True, csp_nonce: str | None = None, spa_handler: bool = True, http2: bool = True, start_dev_server: 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 CSRF token injection and Inertia.js page data handling.

Note

Route metadata is now generated as TypeScript (routes.ts) at build time instead of runtime injection. Use TypeGenConfig.generate_routes to enable.

inject_csrf

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

Type:: bool

csrf_var_name

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

Type:: str

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_csrf: bool = True, csrf_var_name: str = '__LITESTAR_CSRF__', app_selector: str = '#app', cache_transformed_html: bool = True) → None

class litestar_vite.config.TypeGenConfig[source]

Bases: object

Type generation settings.

Presence of this config enables type generation. Use types=None or types=False in ViteConfig to disable.

output

Output directory for generated types.

Type:: pathlib.Path

openapi_path

Path to export OpenAPI schema.

Type:: Path | None

routes_path

Path to export routes metadata (JSON format).

Type:: Path | None

routes_ts_path

Path to export typed routes TypeScript file.

Type:: Path | None

generate_zod

Generate Zod schemas from OpenAPI.

Type:: bool

generate_sdk

Generate SDK client from OpenAPI.

Type:: bool

generate_routes

Generate typed routes.ts file (Ziggy-style).

Type:: bool

generate_page_props

Generate Inertia page props TypeScript file. Auto-enabled when both types and inertia are configured.

Type:: bool

page_props_path

Path to export page props metadata (JSON format).

Type:: Path | None

global_route

Register route() function globally on window object. When True, adds window.route = route to generated routes.ts, providing global access without imports.

Type:: bool

fallback_type

Fallback value type for untyped containers in generated Inertia props. Controls whether untyped dict/list become unknown (default) or any.

Type:: Literal[‘unknown’, ‘any’]

type_import_paths

Map schema/type names to TypeScript import paths for props types that are not present in OpenAPI (e.g., internal/excluded schemas).

Type:: dict[str, str]

global_route: bool = False

When True, the generated routes.ts will include code that registers the type-safe route() function on window.route, similar to Laravel’s Ziggy library. This allows using route() without imports:

// With global_route=True, no import needed:
window.route('user-profile', { userId: 123 })

// TypeScript users should add to global.d.ts:
// declare const route: typeof import('@/generated/routes').route

Default is False to encourage explicit imports for better tree-shaking.

type_import_paths: dict[str, str]

Map schema/type names to TypeScript import paths for Inertia props.

Use this for prop types that are not present in OpenAPI (e.g., internal schemas).

page_props_path: Path | None = None

Path to export page props metadata JSON.

The Vite plugin reads this file to generate page-props.ts. Defaults to output / “inertia-pages.json”.

__post_init__() → None[source]: Normalize path types and compute defaults based on output directory.

__init__(output: ~pathlib.Path = <factory>, openapi_path: Path | None = None, routes_path: Path | None = None, routes_ts_path: Path | None = None, generate_zod: bool = False, generate_sdk: bool = True, generate_routes: bool = True, generate_page_props: bool = True, global_route: bool = False, fallback_type: Literal['unknown', 'any'] = 'unknown', type_import_paths: dict[str, str] = <factory>, page_props_path: Path | None = None) → 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 or TypeGenConfig(): Enable type generation (presence = enabled)
inertia=True or InertiaConfig(): Enable Inertia.js (presence = enabled)

Mode auto-detection:

If mode is not explicitly set:
- If Inertia is enabled and index.html exists -> Hybrid mode
- If Inertia is enabled without index.html -> Template mode
- Checks for index.html in common locations -> SPA mode
- Checks if Jinja2 template engine is configured -> Template mode
- Otherwise defaults to SPA mode

Dev-mode auto-enable:

If mode=”spa” and no built assets are found in bundle_dir, dev_mode is enabled automatically (unless VITE_AUTO_DEV_MODE=False).
Explicit mode parameter overrides auto-detection

mode

Serving mode - “spa”, “template”, “htmx”, “hybrid”, “framework”, “ssr”, “ssg”, or “external”. Auto-detected if not set. Use “external” for non-Vite frameworks (Angular CLI, etc.) that have their own build system - auto-serves bundle_dir in production.

Type:: Literal[‘spa’, ‘template’, ‘htmx’, ‘hybrid’, ‘inertia’, ‘framework’, ‘ssr’, ‘ssg’, ‘external’] | 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/TypeGenConfig enables, False/None disables).

Type:: TypeGenConfig | bool | None

inertia

Inertia.js settings (True/InertiaConfig enables, False/None disables).

Type:: InertiaConfig | bool | None

spa

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

Type:: SPAConfig | bool | None

logging

Logging configuration (True enables with defaults, None uses defaults).

Type:: LoggingConfig | bool | None

dev_mode

Convenience shortcut for runtime.dev_mode.

Type:: bool

base_url

Base URL for the app entry point.

Type:: str | None

deploy

Deployment configuration for CDN publishing.

Type:: DeployConfig | bool

guards: Sequence[Guard] | None = None

Custom guards for the SPA catch-all route.

When set, these guards are applied to the SPA handler route that serves the SPA index.html (mode=”spa”/”framework” with spa_handler=True).

exclude_static_from_auth: bool = True

Exclude static file routes from authentication.

When True (default), static file routes are served with opt={“exclude_from_auth”: True}, which tells auth middleware to skip authentication for asset requests. Set to False if you need to protect static assets with authentication.

spa_path: str | None = None

Path where the SPA handler serves index.html.

Controls where AppHandler registers its catch-all routes.

Default: “/” (root)
Non-root (e.g. “/web/”): optionally set include_root_spa_paths=True to also serve at “/” and “/{path:path}”.

include_root_spa_paths: bool = False

Also register SPA routes at root when spa_path is non-root.

When True and spa_path is set to a non-root path (e.g., “/web/”), the SPA handler will also serve at “/” and “/{path:path}” in addition to the spa_path routes.

This is useful for Angular apps with –base-href /web/ that also want to serve the SPA from the root path for convenience.

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

Returns:: The configured JavaScript executor.

reset_executor() → None[source]

Reset the cached executor instance.

Call this after modifying logging config to pick up new settings.

property bundle_dir: Path

Get bundle directory path.

Returns:: The configured bundle directory path.

property resource_dir: Path

Get resource directory path.

Returns:: The configured resource directory path.

property static_dir: Path

Get static directory path.

Returns:: The configured static directory path.

property root_dir: Path

Get root directory path.

Returns:: The configured project root directory path.

property manifest_name: str

Get manifest file name.

Returns:: The configured Vite manifest filename.

property hot_file: str

Get hot file name.

Returns:: The configured hotfile filename.

property asset_url: str

Get asset URL.

Returns:: The configured asset URL prefix.

candidate_index_html_paths() → list[Path][source]

Return possible index.html locations for SPA mode detection.

Order mirrors the JS plugin auto-detection: 1. bundle_dir/index.html (for production static builds like Astro/Nuxt/SvelteKit) 2. resource_dir/index.html 3. root_dir/index.html 4. static_dir/index.html

Returns:: A de-duplicated list of candidate index.html paths, ordered by preference.

candidate_manifest_paths() → list[Path][source]

Return possible manifest.json locations in the bundle directory.

Some meta-frameworks emit the manifest under a .vite/ subdirectory (e.g. <bundle_dir>/.vite/manifest.json), while plain Vite builds may write it directly to <bundle_dir>/manifest.json.

Returns:: A de-duplicated list of candidate manifest paths, ordered by preference.

resolve_manifest_path() → Path[source]

Resolve the most likely manifest path.

Returns:: The first existing manifest path, or the highest-priority candidate when none exist.

has_built_assets() → bool[source]

Check if production assets exist in the bundle directory.

Returns:: True if a manifest or built index.html exists in bundle_dir.

Note

This method checks the bundle_dir (output directory) for built artifacts, NOT source directories. The presence of source index.html in resource_dir does not indicate built assets exist.

property host: str

Get dev server host.

Returns:: The configured Vite dev server host.

property port: int

Get dev server port.

Returns:: The configured Vite dev server port.

property protocol: str

Get dev server protocol.

Returns:: The configured Vite dev server protocol.

property hot_reload: bool

Check if hot reload is enabled (derived from dev_mode and proxy_mode).

HMR requires dev_mode=True AND a Vite-based proxy mode (vite, direct, or proxy). All modes support HMR since even SSR frameworks use Vite internally.

Returns:: True if hot reload is enabled, otherwise False.

property is_dev_mode: bool

Check if dev mode is enabled.

Returns:: True if dev mode is enabled, otherwise False.

property is_react: bool

Check if React mode is enabled.

Returns:: True if React mode is enabled, otherwise False.

__init__(mode: Literal['spa', 'template', 'htmx', 'hybrid', 'inertia', 'framework', 'ssr', 'ssg', 'external'] | None = None, paths: ~litestar_vite.config.PathConfig = <factory>, runtime: ~litestar_vite.config.RuntimeConfig = <factory>, types: TypeGenConfig | bool | None = None, inertia: InertiaConfig | bool | None = None, spa: SPAConfig | bool | None = None, logging: LoggingConfig | bool | None = None, dev_mode: bool = False, base_url: str | None = <factory>, deploy: DeployConfig | bool = False, guards: Sequence[Guard] | None = None, exclude_static_from_auth: bool = True, spa_path: str | None = None, include_root_spa_paths: bool = False, _executor_instance: JSExecutor | None = None, _mode_auto_detected: bool = False) → None

property run_command: list[str]

Get the run command.

Returns:: The argv list used to start the Vite dev server.

property build_command: list[str]

Get the build command.

Returns:: The argv list used to build production assets.

property build_watch_command: list[str]

Get the watch command for building frontend in watch mode.

Used by litestar assets serve when hot_reload is disabled.

Returns:: The command argv list used for watch builds.

property serve_command: list[str] | None

Get the serve command for running production server.

Used by litestar assets serve –production for SSR frameworks. Returns None if not configured.

Returns:: The command argv list used to serve production assets, or None if not configured.

property install_command: list[str]

Get the install command.

Returns:: The argv list used to install frontend dependencies.

property health_check: bool

Check if health check is enabled.

Returns:: True if health checks are enabled, otherwise False.

property set_environment: bool

Check if environment should be set.

Returns:: True if Vite environment variables should be set, otherwise False.

property set_static_folders: bool

Check if static folders should be configured.

Returns:: True if static folders should be configured, otherwise False.

property detect_nodeenv: bool

Check if nodeenv detection is enabled.

Returns:: True if nodeenv detection is enabled, otherwise False.

property proxy_mode: Literal['vite', 'direct', 'proxy'] | None

Get proxy mode.

Returns:: The configured proxy mode, or None if proxying is disabled.

property external_dev_server: ExternalDevServer | None

Get external dev server config.

Returns:: External dev server configuration, or None if not configured.

property spa_handler: bool

Check if SPA handler auto-registration is enabled.

Returns:: True if the SPA handler should be auto-registered, otherwise False.

property http2: bool

Check if HTTP/2 is enabled for proxy connections.

Returns:: True if HTTP/2 is enabled for proxy connections, otherwise False.

property csp_nonce: str | None

Return the CSP nonce used for injected inline scripts.

Returns:: CSP nonce string when configured, otherwise None.

property ssr_output_dir: Path | None

Get SSR output directory.

Returns:: The configured SSR output directory, or None if not configured.

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.

property logging_config: LoggingConfig

Get logging configuration.

Returns:: LoggingConfig instance (always available after normalization).