Loader

Vite Asset Loader.

This module provides the ViteAssetLoader class for loading and rendering Vite-managed assets. The loader handles both development mode (with HMR) and production mode (with manifest-based asset resolution).

Key features: - Async initialization for non-blocking I/O during app startup - Manifest parsing for production asset resolution - HMR client script generation for development - React Fast Refresh support

litestar_vite.loader.render_hmr_client(context: Mapping[str, Any], /) → markupsafe.Markup

Render the HMR client script tag.

This is a Jinja2 template callable that renders the Vite HMR client script tag for development mode.

Parameters:

context – The template context containing the request.

Returns:

HTML markup for the HMR client script.

litestar_vite.loader.render_asset_tag(context: Mapping[str, Any], /, path: str | list[str], scripts_attrs: dict[str, str] | None = None) → markupsafe.Markup

Render asset tags for the specified path(s).

This is a Jinja2 template callable that renders script/link tags for Vite-managed assets. Also works for HTMX partial responses.

Parameters:

• context – The template context containing the request.

• path – Single path or list of paths to assets.

• scripts_attrs – Optional attributes for script tags.

Returns:

HTML markup for the asset tags.

Example

In a Jinja2 template: {{ vite_asset(“src/main.ts”) }} {{ vite_asset(“src/components/UserProfile.tsx”) }} # For partials

litestar_vite.loader.render_static_asset(context: Mapping[str, Any], /, path: str) → str

Render a static asset URL.

This is a Jinja2 template callable that returns the URL for a static asset.

Parameters:

• context – The template context containing the request.

• path – Path to the static asset.

Returns:

The full URL to the static asset.

litestar_vite.loader.render_partial_asset_tag(context: Mapping[str, Any], /, path: str | list[str], scripts_attrs: dict[str, str] | None = None) → markupsafe.Markup

Render asset tags for the specified path(s).

This is a Jinja2 template callable that renders script/link tags for Vite-managed assets. Also works for HTMX partial responses.

Parameters:

• context – The template context containing the request.

• path – Single path or list of paths to assets.

• scripts_attrs – Optional attributes for script tags.

Returns:

HTML markup for the asset tags.

Example

In a Jinja2 template: {{ vite_asset(“src/main.ts”) }} {{ vite_asset(“src/components/UserProfile.tsx”) }} # For partials

class litestar_vite.loader.ViteAssetLoader

Bases: object

Vite asset loader for managing frontend assets.

This class handles loading and rendering of Vite-managed assets. It supports both development mode (with HMR) and production mode (with manifest-based asset resolution).

The loader is designed to be instantiated per-app (not a singleton) and supports async initialization for non-blocking file I/O.

config

The Vite configuration.

Example

loader = ViteAssetLoader(config) await loader.initialize() html = loader.render_asset_tag(“src/main.ts”)

__init__(config: ViteConfig) → None

Initialize the asset loader.

Parameters:

config – The Vite configuration.

classmethod initialize_loader(config: ViteConfig) → ViteAssetLoader

Synchronously initialize a loader instance.

This is a convenience method for synchronous initialization. For async contexts, prefer using initialize() after construction.

Parameters:

config – The Vite configuration.

Returns:

An initialized ViteAssetLoader instance.

async initialize() → None

Asynchronously initialize the loader.

This method performs async file I/O to load the manifest or hot file. Call this during app startup in an async context.

parse_manifest() → None

Synchronously parse the Vite manifest file.

This method reads the manifest.json file in production mode or the hot file in development mode.

Note: For async contexts, use initialize() instead.

property manifest_content: str

Get the raw manifest content.

property version_id: str

Get the version ID of the manifest.

The version ID is used for cache busting and Inertia.js asset versioning.

Returns:

A hash of the manifest content, or “1.0” if no manifest.

render_hmr_client() → Markup

Render the HMR client script tags.

Returns:

HTML markup containing React HMR and Vite client script tags.

render_asset_tag(path: str | list[str], scripts_attrs: dict[str, str] | None = None) → Markup

Render asset tags for the specified path(s).

Parameters:

• path – Single path or list of paths to assets.

• scripts_attrs – Optional attributes for script tags.

Returns:

HTML markup for script and link tags.

get_static_asset(path: str) → str

Get the URL for a static asset.

Parameters:

path – The path to the asset.

Returns:

The full URL to the asset.

Raises:

AssetNotFoundError – If the asset is not in the manifest.

generate_ws_client_tags() → str

Generate the Vite HMR client script tag.

Only generates output in development mode with hot reload enabled.

Returns:

Script tag HTML or empty string in production.

generate_react_hmr_tags() → str

Generate React Fast Refresh preamble script.

Only generates output when React mode is enabled in development.

Returns:

React refresh script HTML or empty string.

generate_asset_tags(path: str | list[str], scripts_attrs: dict[str, str] | None = None) → str

Generate all asset tags for the specified file(s).

Parameters:

• path – Path or list of paths to assets.

• scripts_attrs – Optional attributes for script tags.

Returns:

HTML string with all necessary script and link tags.

Raises:

ImproperlyConfiguredException – If asset not found in manifest.