Plugin

class litestar_vite.inertia.plugin.InertiaPlugin

Bases: InitPluginProtocol

Inertia plugin.

This plugin configures Litestar for Inertia.js support, including: - Session middleware requirement validation - Exception handler for Inertia responses - InertiaRequest and InertiaResponse as default classes - Type encoders for StaticProp and DeferredProp

BlockingPortal Behavior:

The plugin creates a BlockingPortal during its lifespan for executing async DeferredProp callbacks from synchronous type encoders. This is necessary because Litestar’s JSON serialization happens synchronously, but DeferredProp may contain async callables.

The portal is shared across all requests during the app’s lifetime. Type encoders for StaticProp and DeferredProp use val.render() which may access this portal for async resolution.

If you’re using DeferredProp outside of InertiaResponse (e.g., in custom serialization), ensure the app lifespan is active and the portal is available via inertia_plugin.portal.

SSR Client Pooling:

When SSR is enabled, the plugin maintains a shared httpx.AsyncClient for all SSR requests. This provides significant performance benefits: - Connection pooling with keep-alive - TLS session reuse - HTTP/2 multiplexing (when available)

The client is initialized during app lifespan and properly closed on shutdown. Access via inertia_plugin.ssr_client if needed.

Example:

from litestar_vite.inertia import InertiaPlugin, InertiaConfig

app = Litestar(
    plugins=[InertiaPlugin(InertiaConfig())],
    middleware=[ServerSideSessionConfig().middleware],
)

__init__(config: InertiaConfig) → None

Initialize the plugin with Inertia configuration.

lifespan(app: Litestar) → AsyncGenerator[None, None]

Lifespan to ensure the event loop is available.

Initializes: - BlockingPortal for sync-to-async DeferredProp resolution - Shared httpx.AsyncClient for SSR requests (connection pooling)

Parameters:

app – The Litestar instance.

Yields:

An asynchronous context manager.

property portal: BlockingPortal

Return the blocking portal used for deferred prop resolution.

Returns:

The BlockingPortal instance.

Raises:

RuntimeError – If accessed before app lifespan is active.

property ssr_client: AsyncClient | None

Return the shared httpx.AsyncClient for SSR requests.

The client is initialized during app lifespan and provides connection pooling, TLS session reuse, and HTTP/2 multiplexing benefits.

Returns:

The shared AsyncClient instance, or None if not initialized.

on_app_init(app_config: AppConfig) → AppConfig

Configure application for use with Vite.

Parameters:

app_config – The AppConfig instance.

Raises:

ImproperlyConfiguredException – If the Inertia plugin is not properly configured.

Returns:

The AppConfig instance.