SPA Handler#

The AppHandler manages serving Single Page Applications in both development and production modes.

Features#

  • Development mode: Proxies requests to Vite dev server for HMR

  • Production mode: Serves built index.html with caching

  • CSRF token injection

  • Page data injection for Inertia.js

  • Async and sync initialization support

  • HTML transformation utilities

SPA mode handler public API.

This package provides the AppHandler for serving single-page applications with Vite asset integration.

class litestar_vite.handler.AppHandler[source]#

Bases: object

Handler for serving SPA HTML in both dev and production modes.

__init__(config: ViteConfig, *, csrf_config: CSRFConfig | None = None) → None[source]#

Initialize the SPA handler.

Parameters:

  • config – The Vite configuration.

  • csrf_config – The app’s Litestar CSRF configuration, if enabled.

property is_initialized: bool#

Whether the handler has been initialized.

Returns:

True when initialized, otherwise False.

async initialize_async(vite_url: str | None = None, manifest: dict[str, Any] | None = None) → None[source]#

Initialize the handler asynchronously.

Parameters:

  • vite_url – Optional Vite server URL to use for proxying.

  • manifest – Optional pre-parsed manifest from the shared asset loader. This avoids reading and parsing the same file again during worker startup. It is ignored when hot development or an external development server skips manifest loading.

initialize_sync(vite_url: str | None = None) → None[source]#

Initialize the handler synchronously.

Parameters:

vite_url – Optional Vite server URL to use for proxying.

async shutdown_async() → None[source]#

Shutdown the handler asynchronously.

async get_html(request: Request[Any, Any, Any], *, page_data: dict[str, Any] | None = None) → str[source]#

Get the HTML for the SPA with optional transformations.

Parameters:

  • request – Incoming request.

  • page_data – Optional page data to inject (e.g., Inertia page props).

Returns:

The rendered HTML.

Raises:

ImproperlyConfiguredException – If the handler is not initialized.

get_html_sync(*, page_data: dict[str, Any] | None = None, csrf_token: str | None = None) → str[source]#

Get the HTML for the SPA synchronously.

Parameters:

  • page_data – Optional page data to inject (e.g., Inertia page props).

  • csrf_token – Optional CSRF token to inject.

Returns:

The rendered HTML.

async get_bytes() → bytes[source]#

Get cached index.html bytes (production).

Returns:

Cached HTML bytes. .

create_route_handler() → HTTPRouteHandler[source]#

Create a Litestar route handler for the SPA.

Returns:

A Litestar route handler suitable for registering on an application.