Skip to content

Runtime & Inertia Helpers

Browser and SSR runtime utilities for CSRF token injection, route matching, HTMX JSON templates, WebSocket/SSE event streams, Litestar Channels, Litestar Queues, Inertia page resolution, pagination helpers, and Laravel Precognition validation.

Subpath Import Specifier Source Entrypoint Exports
./helpers litestar-vite-plugin/helpers src/js/src/helpers/index.ts csrfFetch, csrfHeaders, getCsrfHeaderName, getCsrfToken, CsrfFetchOptions, CsrfOptions, +37 more
./inertia-helpers litestar-vite-plugin/inertia-helpers src/js/src/inertia-helpers/index.ts ResolvePageComponentOptions, OffsetPaginationProps, ClassicPaginationProps, CursorPaginationProps, ScrollProps, PrecognitionValidationErrors, +9 more

litestar-vite-plugin/helpers

Package Subpath: ./helpers · Types: ./dist/js/helpers/index.d.ts · Source: src/js/src/helpers/index.ts

Litestar Vite Helpers

Export Kind Description
csrfFetch function Create a fetch wrapper that automatically includes CSRF token.
csrfHeaders function Create headers object with CSRF token included.
getCsrfHeaderName function Get the configured CSRF header name.
getCsrfToken function Get the CSRF token from the page.
CsrfFetchOptions interface Exported interface from src/js/src/helpers/csrf.ts.
CsrfOptions interface Exported interface from src/js/src/helpers/csrf.ts.
createChannelsStream function Create a stream for a WebSocket route generated by ChannelsPlugin.
createTypedChannels function Create a typed channel factory bound to a generated ChannelMap.
ChannelMap type Exported type from src/js/src/helpers/channels.ts.
ChannelMetadataEntry interface Exported interface from src/js/src/helpers/channels.ts.
ChannelsStreamOptions interface Exported interface from src/js/src/helpers/channels.ts.
RealtimeChannelShape interface Exported interface from src/js/src/helpers/channels.ts.
TypedChannelOptions interface Exported interface from src/js/src/helpers/channels.ts.
addDirective function Exported function from src/js/src/helpers/htmx.ts.
registerHtmxExtension function Exported function from src/js/src/helpers/htmx.ts.
setHtmxDebug function Enable or disable debug logging for the HTMX extension.
swapJson function Exported function from src/js/src/helpers/htmx.ts.
createQueueEventStream function Create a stream for routes generated by QueuePlugin EventStreamConfig.
QUEUE_SSE_EVENTS const Exported const from src/js/src/helpers/queues.ts.
QueueStreamTarget type Exported type from src/js/src/helpers/queues.ts.
QueueStreamValue type Exported type from src/js/src/helpers/queues.ts.
BoundRouteFunction interface Bound route() helper with .ws() attached for WebSocket route URL resolution.
createRouteHelpers function Create route helpers bound to a specific routeDefinitions object.
currentRoute function Get the current route name based on the browser URL.
formatRouteUrl function Format a route path with path and query parameters.
isCurrentRoute function Check if the current browser URL matches a route name or pattern.
isRoute function Check if a URL matches a route name or pattern.
resolveWsUrl function Resolve a relative or HTTP URL into a WebSocket URL (ws:// or wss://).
RouteDefinition interface Route definition structure from generated routes.
RouteDefinitions type Map of route names to their definitions.
RouteHelpers interface Route helpers interface returned by createRouteHelpers.
toRoute function Convert a URL to its corresponding route name.
WebSocketRouteNames type Extract route names from a RouteDefinitions map that declare protocol: "websocket".
wsRoute function Generate a WebSocket URL (ws:// or wss://) for a named WebSocket route.
WsRouteName type Resolve the allowed route-name union for wsRoute / route.ws. Narrows to protocol: "websocket" routes when literal protocol metadata is present, and falls back to keyof TRoutes & string for untyped Record<string, RouteDefinition> maps.
WsRouteOptions interface Options for resolving WebSocket route URLs.
createEventStream function Create a reconnecting, transport-agnostic Litestar event stream.
EventStream interface Exported interface from src/js/src/helpers/stream.ts.
EventStreamConfig interface Exported interface from src/js/src/helpers/stream.ts.
StreamGap interface Resilient WebSocket and SSE helpers for Litestar event streams.
defineStreamElement function Register the declarative stream element.
LitestarStreamElement class Exported class from src/js/src/helpers/stream-element.ts.
StreamElementOptions interface Exported interface from src/js/src/helpers/stream-element.ts.

csrfFetch

export function csrfFetch(input: RequestInfo | URL, init?: RequestInit, options?: CsrfFetchOptions): Promise<Response>

Create a fetch wrapper that automatically includes CSRF token.

csrfHeaders

export function csrfHeaders(additionalHeaders: Record<string, string> = {}, optionsOrHeaderFallback?: string | CsrfOptions, cookieNameFallback?: string): Record<string, string>

Create headers object with CSRF token included.

getCsrfHeaderName

export function getCsrfHeaderName(fallback: string = DEFAULT_CSRF_HEADER_NAME): string

Get the configured CSRF header name.

getCsrfToken

export function getCsrfToken(cookieNameFallbackOrOptions?: string | CsrfOptions): string

Get the CSRF token from the page.

CsrfFetchOptions

export interface CsrfFetchOptions extends CsrfOptions

CsrfOptions

export interface CsrfOptions
Property Type Default Description
headerName? string — —
cookieName? string — —

createChannelsStream

export function createChannelsStream<TFrame = unknown, TParams extends Record<string, string | number> = Record<string, string | number>>( options: ChannelsStreamOptions<TFrame, TParams>, ): EventStream<TFrame>

Create a stream for a WebSocket route generated by ChannelsPlugin.

createTypedChannels

export function createTypedChannels<TChannels extends { [K in keyof TChannels]: RealtimeChannelShape } = ChannelMap>(defaults?: { basePath?: string metadata?: Partial<Record<keyof TChannels & string, ChannelMetadataEntry>> }): { stream<K extends keyof TChannels & string>(channel: K, options: TypedChannelOptions<TChannels[K]>): EventStream<TChannels[K]["send"]> }

Create a typed channel factory bound to a generated ChannelMap.

ChannelMap

export type ChannelMap = Record<string, RealtimeChannelShape>

ChannelMetadataEntry

export interface ChannelMetadataEntry
Property Type Default Description
address string — —
protocol "websocket" | "sse" | "channels" — —

ChannelsStreamOptions

export interface ChannelsStreamOptions<TFrame = unknown, TParams extends Record<string, string | number> = Record<string, string | number>> extends Omit<
  EventStreamConfig<TFrame, TFrame>,
  "EventSourceCtor" | "sseEvents" | "transport"
>
Property Type Default Description
channel ChannelName — —
params? TParams — —
basePath? string — —
transformUrl? (url: URL) => string | URL — —

RealtimeChannelShape

export interface RealtimeChannelShape
Property Type Default Description
address string — —
protocol "websocket" | "sse" | "channels" — —
params? Record<string, any> — —
send? unknown — —
receive? unknown — —

TypedChannelOptions

export interface TypedChannelOptions<TChannel extends RealtimeChannelShape> extends EventStreamConfig<TChannel["receive"], TChannel["send"]>
Property Type Default Description
params? TChannel["params"] — —
basePath? string — —
address? string — —
transformUrl? (url: URL) => string | URL — —

addDirective

export function addDirective(dir: Dir): void

registerHtmxExtension

export function registerHtmxExtension(): void

setHtmxDebug

export function setHtmxDebug(on: boolean): void

Enable or disable debug logging for the HTMX extension.

swapJson

export function swapJson(el: Element, data: unknown): void

createQueueEventStream

export function createQueueEventStream<TFrame = unknown>(options: QueueEventStreamOptions<TFrame>): EventStream

Create a stream for routes generated by QueuePlugin EventStreamConfig.

QUEUE_SSE_EVENTS

export const QUEUE_SSE_EVENTS = [

QueueStreamTarget

export type QueueStreamTarget =
  | { scope: "task"; taskId: QueueStreamValue }

QueueStreamValue

export type QueueStreamValue = string | (() => string)

BoundRouteFunction

export interface BoundRouteFunction<T extends string, TRoutes extends Record<T, RouteDefinition> = Record<T, RouteDefinition>>

Bound route() helper with .ws() attached for WebSocket route URL resolution.

Property Type Default Description
ws <TName extends string = WsRouteName<TRoutes>>(name: TName & WsRouteName<TRoutes>, params?: Record<string, unknown>, options?: WsRouteOptions) => string — —

createRouteHelpers

export function createRouteHelpers<T extends string, TRoutes extends Record<T, RouteDefinition> = Record<T, RouteDefinition>>( routes: TRoutes, defaultOptions?: WsRouteOptions, ): RouteHelpers<T, TRoutes>

Create route helpers bound to a specific routeDefinitions object.

currentRoute

export function currentRoute<T extends string>(routes: Record<T, RouteDefinition>): T | null

Get the current route name based on the browser URL.

formatRouteUrl

export function formatRouteUrl<TRoutes extends Record<string, RouteDefinition>, TName extends keyof TRoutes & string>( name: TName, routes: TRoutes, params?: Record<string, unknown>, apiUrl?: string, ): string

Format a route path with path and query parameters.

isCurrentRoute

export function isCurrentRoute<T extends string>(pattern: string, routes: Record<T, RouteDefinition>): boolean

Check if the current browser URL matches a route name or pattern.

isRoute

export function isRoute<T extends string>(url: string, pattern: string, routes: Record<T, RouteDefinition>): boolean

Check if a URL matches a route name or pattern.

resolveWsUrl

export function resolveWsUrl(pathOrUrl: string, serverUrl?: string): string

Resolve a relative or HTTP URL into a WebSocket URL (ws:// or wss://).

RouteDefinition

export interface RouteDefinition

Route definition structure from generated routes.

Property Type Default Description
path string — —
methods readonly string[] — —
method? string — —
pathParams readonly string[] — —
queryParams readonly string[] — —
component? string — —
protocol? "http" | "websocket" — —
channelKey? string — —

RouteDefinitions

export type RouteDefinitions = Record<string, RouteDefinition>

Map of route names to their definitions.

RouteHelpers

export interface RouteHelpers<T extends string, TRoutes extends Record<T, RouteDefinition> = Record<T, RouteDefinition>>

Route helpers interface returned by createRouteHelpers.

Property Type Default Description
route BoundRouteFunction<T, TRoutes> — —
wsRoute <TName extends string = WsRouteName<TRoutes>>(name: TName & WsRouteName<TRoutes>, params?: Record<string, unknown>, options?: WsRouteOptions) => string — —
toRoute (url: string) => T | null — —
currentRoute () => T | null — —
isRoute (url: string, pattern: string) => boolean — —
isCurrentRoute (pattern: string) => boolean — —

toRoute

export function toRoute<T extends string>(url: string, routes: Record<T, RouteDefinition>): T | null

Convert a URL to its corresponding route name.

WebSocketRouteNames

export type WebSocketRouteNames<TRoutes extends Record<string, RouteDefinition>> = {

Extract route names from a RouteDefinitions map that declare protocol: "websocket".

wsRoute

export function wsRoute<TRoutes extends Record<string, RouteDefinition>, TName extends string = WsRouteName<TRoutes>>( name: TName & WsRouteName<TRoutes>, routes: TRoutes, params?: Record<string, unknown>, options?: WsRouteOptions, ): string

Generate a WebSocket URL (ws:// or wss://) for a named WebSocket route.

WsRouteName

export type WsRouteName<TRoutes extends Record<string, RouteDefinition>> = [WebSocketRouteNames<TRoutes>] extends [never] ? keyof TRoutes & string : WebSocketRouteNames<TRoutes>

Resolve the allowed route-name union for wsRoute / route.ws. Narrows to protocol: "websocket" routes when literal protocol metadata is present, and falls back to keyof TRoutes & string for untyped Record<string, RouteDefinition> maps.

WsRouteOptions

export interface WsRouteOptions

Options for resolving WebSocket route URLs.

Property Type Default Description
serverUrl? string — —
wsServerUrl? string — —

createEventStream

export function createEventStream<TFrame = unknown, TSend = never>(options: EventStreamOptions<TFrame, TSend>): EventStream<TSend>

Create a reconnecting, transport-agnostic Litestar event stream.

EventStream

export interface EventStream<TSend = never>
Property Type Default Description
healthy boolean — —

EventStreamConfig

export interface EventStreamConfig<TFrame = unknown, TSend = never>
Property Type Default Description
transport? "websocket" | "sse" — —
sseEvents? readonly string[] — —
onEvent (frame: TFrame) => void — —
onOpen? (url: string) => void — —
onClose? () => void — —
onHealthChange? (healthy: boolean) => void — —
onReconnect? () => void — —
onGap? (gap: StreamGap) => void — —
onStale? () => void — —
shouldReconnect? (closeCode: number) => boolean — —
isHeartbeat? (frame: TFrame) => boolean — —
getEventKey? (frame: TFrame) => string | undefined — —
getSequence? (frame: TFrame) => { stream: string; value: number } | undefined — —
baseDelayMs? number — —
maxDelayMs? number — —
dedupWindow? number — —
heartbeatTimeoutMs? number — —
heartbeatIntervalMs? number — —
maxTrackedStreams? number — —
parseFrame? (data: string) => TFrame — —
serializeFrame? (payload: TSend) => string — —
WebSocketCtor? typeof WebSocket — —
EventSourceCtor? typeof EventSource — —

StreamGap

export interface StreamGap

Resilient WebSocket and SSE helpers for Litestar event streams.

Property Type Default Description
stream string — —
from number — —
to number — —
missing number — —

defineStreamElement

export function defineStreamElement(options: StreamElementOptions = {}): void

Register the declarative stream element.

LitestarStreamElement

export class LitestarStreamElement extends HTMLElementBase

StreamElementOptions

export interface StreamElementOptions
Property Type Default Description
tagName? string — —

litestar-vite-plugin/inertia-helpers

Package Subpath: ./inertia-helpers · Types: ./dist/js/inertia-helpers/index.d.ts · Source: src/js/src/inertia-helpers/index.ts

Inertia.js helpers for Litestar applications.

Export Kind Description
ResolvePageComponentOptions interface Resolve a page component from a glob import.
OffsetPaginationProps interface Offset-based pagination props.
ClassicPaginationProps interface Classic page-based pagination props.
CursorPaginationProps interface Cursor-based pagination props.
ScrollProps interface Scroll props configuration for Inertia v2 infinite scroll.
PrecognitionValidationErrors interface Validation error format returned by Precognition responses.
PrecognitionFormConfig interface Configuration options for Precognition forms.
PaginationProps type Union type for any pagination props.
unwrapPageProps function Unwrap page props that may have content nested under "content" key.
resolvePageComponent function Exported function from src/js/src/inertia-helpers/index.ts.
resolvePageModule function Resolve a page module from a glob import, preserving the module { default: Component } shape.
isPrecognitionSuccess function Check if a response is a successful Precognition validation.
isPrecognitionError function Check if a response is a Precognition validation error.
extractPrecognitionErrors function Extract validation errors from a Precognition error response.
PrecognitionHeaders const HTTP headers used by the Precognition protocol.

ResolvePageComponentOptions

export interface ResolvePageComponentOptions

Resolve a page component from a glob import.

Property Type Default Description
rawModule? boolean — —

OffsetPaginationProps

export interface OffsetPaginationProps<T>

Offset-based pagination props.

Property Type Default Description
items T[] — —
total number — —
limit number — —
offset number — —

ClassicPaginationProps

export interface ClassicPaginationProps<T>

Classic page-based pagination props.

Property Type Default Description
items T[] — —
currentPage number — —
totalPages number — —
pageSize number — —

CursorPaginationProps

export interface CursorPaginationProps<T>

Cursor-based pagination props.

Property Type Default Description
items T[] — —
total? number — —
hasMore? boolean — —
hasNext? boolean — —
hasPrevious? boolean — —
nextCursor? string | null — —
previousCursor? string | null — —

ScrollProps

export interface ScrollProps

Scroll props configuration for Inertia v2 infinite scroll.

Property Type Default Description
pageName string — —
currentPage number — —
previousPage number | null — —
nextPage number | null — —

PrecognitionValidationErrors

export interface PrecognitionValidationErrors

Validation error format returned by Precognition responses.

Property Type Default Description
message string — —
errors Record<string, string[]> — —

PrecognitionFormConfig

export interface PrecognitionFormConfig

Configuration options for Precognition forms.

Property Type Default Description
validationTimeout? number — —
onSuccess? () => void — —
onValidationError? (errors: PrecognitionValidationErrors) => void — —
onBefore? () => boolean | undefined — —
onFinish? () => void — —

PaginationProps

export type PaginationProps<T> = OffsetPaginationProps<T> | ClassicPaginationProps<T> | CursorPaginationProps<T>

Union type for any pagination props.

unwrapPageProps

export function unwrapPageProps<T extends Record<string, unknown>>(props: T): T

Unwrap page props that may have content nested under "content" key.

resolvePageComponent

export async function resolvePageComponent( path: string | string[], pages: Record<string, Promise<unknown> | (() => Promise<unknown>)>, options?: ResolvePageComponentOptions, ): Promise<unknown>

resolvePageModule

export async function resolvePageModule<T>(path: string | string[], pages: Record<string, Promise<{ default: T }> | (() => Promise<{ default: T }>)>): Promise<{ default: T }>

Resolve a page module from a glob import, preserving the module { default: Component } shape.

isPrecognitionSuccess

export function isPrecognitionSuccess(response: Response): boolean

Check if a response is a successful Precognition validation.

isPrecognitionError

export function isPrecognitionError(response: Response): boolean

Check if a response is a Precognition validation error.

extractPrecognitionErrors

export async function extractPrecognitionErrors(response: Response): Promise<PrecognitionValidationErrors>

Extract validation errors from a Precognition error response.

PrecognitionHeaders

export const PrecognitionHeaders = {

HTTP headers used by the Precognition protocol.