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.

The SPA handler implementation lives in litestar_vite._handler.app. This module exists as a stable import location for users and tests.

class litestar_vite.handler.AppHandler[source]

Bases: object

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

__init__(config: ViteConfig) → None[source]

Initialize the SPA handler.

Parameters:

config – The Vite configuration.

create_route_handler() → Any[source]

Create a Litestar route handler for the SPA.

Returns:

A Litestar route handler suitable for registering on an application.

async get_bytes() → bytes[source]

Get cached index.html bytes (production).

Returns:

Cached HTML bytes.

Raises:

ImproperlyConfiguredException – If index.html cannot be located.

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.

Raises:

ImproperlyConfiguredException – If dev-mode HTTP clients are not initialized or Vite URL is unresolved.

async initialize_async(vite_url: str | None = None) → None[source]

Initialize the handler asynchronously.

Parameters:

vite_url – Optional Vite server URL to use for proxying.

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

Initialize the handler synchronously.

Parameters:

vite_url – Optional Vite server URL to use for proxying.

property is_initialized: bool

Whether the handler has been initialized.

Returns:

True when initialized, otherwise False.

async shutdown_async() → None[source]

Shutdown the handler asynchronously.