Code Generation#

Code generation utilities for extracting route metadata and generating type-safe route definitions.

Features#

  • Extract route metadata from Litestar applications

  • Generate Ziggy-compatible routes.json

  • Generate TypeScript route definitions with type safety

  • Support for path and query parameters with OpenAPI type enrichment

  • Inertia page props metadata extraction

Public code generation API.

This package provides code generation utilities for:

  • Unified asset export (export_integration_assets)

  • Route metadata export (routes.json + Ziggy-compatible TS)

  • Inertia page props metadata export

  • AsyncAPI plugin discovery and document normalization

Internal implementation details (OpenAPI integration, TypeScript conversion) are kept in private submodules to keep the public API clean.

class litestar_vite.codegen.ExportResult[source]#

Bases: object

Result of the export operation.

exported_files: list[str]#

Files that were written (content changed).

unchanged_files: list[str]#

Files that were skipped (content unchanged).

openapi_schema: dict[str, Any] | None = None#

The OpenAPI schema dict (for downstream use).

asyncapi_schema: dict[str, Any] | None = None#

The AsyncAPI schema dict (for downstream use).

__init__(exported_files: list[str] = <factory>, unchanged_files: list[str] = <factory>, openapi_schema: dict[str, ~typing.Any] | None=None, asyncapi_schema: dict[str, ~typing.Any] | None=None) → None#
class litestar_vite.codegen.InertiaPageMetadata[source]#

Bases: object

Metadata for a single Inertia page component.

__init__(component: str, route_path: str, props_type: str | None = None, schema_ref: str | None = None, handler_name: str | None = None, ts_type: str | None = None, custom_types: list[str] = <factory>, wrap_with_content: bool = False) → None#
class litestar_vite.codegen.RouteMetadata[source]#

Bases: object

Metadata for a single route.

__init__(name: str, path: str, methods: list[str], method: str, params: dict[str, str] = <factory>, query_params: dict[str, str] = <factory>, component: str | None = None) → None#
litestar_vite.codegen.asyncapi_docs_paths(app: Litestar) → tuple[str, ...][source]#

Return reserved AsyncAPI documentation route prefixes.

When an AsyncAPI plugin is registered, returns a deduplicated tuple containing the default AsyncAPI documentation path (‘/asyncapi’) and any custom documentation path configured on the plugin. When no plugin is registered, returns an empty tuple.

Parameters:

app – The Litestar application instance.

Returns:

Tuple of reserved documentation path strings.

litestar_vite.codegen.encode_deterministic_json(data: dict[str, Any], *, indent: int = 2, serializer: Callable[[Any], bytes] | None = None) → bytes[source]#

Encode JSON with sorted keys for deterministic output.

This is a wrapper that ensures all nested dict keys are sorted before serialization, producing byte-identical output for the same input data regardless of insertion order.

Parameters:

  • data – Dictionary to encode.

  • indent – Indentation level for formatting.

  • serializer – Optional custom serializer function. If not provided, uses litestar’s default encode_json.

Returns:

Formatted JSON bytes with sorted keys.

litestar_vite.codegen.export_asyncapi(*, app: Litestar, types_config: TypeGenConfig, serializer: Callable[[Any], bytes] | None = None, result: ExportResult) → None[source]#

Export AsyncAPI schema to file when AsyncAPIPlugin is registered.

Parameters:

  • app – The Litestar application instance.

  • types_config – The type generation configuration.

  • serializer – Optional custom serializer for JSON encoding.

  • result – ExportResult accumulator for exported or unchanged files.

litestar_vite.codegen.export_integration_assets(app: Litestar, config: ViteConfig, *, serializer: Callable[[Any], bytes] | None = None) → ExportResult[source]#

Export all integration artifacts with deterministic output.

This is the single source of truth for code generation. Both CLI commands and Plugin startup should call this function to ensure byte-identical output.

OpenAPI schema, route metadata, route definitions, and Inertia page prop artifacts require an active OpenAPIPlugin configuration. AsyncAPI export requires a registered AsyncAPIPlugin (litestar-asyncapi) on the application and generate_channels=True.

The export order is critical: 1. Register Inertia page prop types in OpenAPI schema (mutates schema_dict) 2. Export openapi.json (now includes session prop types) 3. Export routes.json (uses schema for component refs) 4. Export routes.ts (if enabled) 5. Export inertia-pages.json (if enabled) 6. Export asyncapi.json (if enabled and AsyncAPIPlugin is registered)

Parameters:

  • app – The Litestar application instance.

  • config – The ViteConfig instance.

  • serializer – Optional custom serializer for OpenAPI schema encoding.

Returns:

ExportResult with lists of exported and unchanged files.

litestar_vite.codegen.extract_inertia_pages(app: Litestar, *, openapi_schema: dict[str, Any] | None = None, fallback_type: str = 'unknown', openapi_support: OpenAPISupport | None = None) → list[InertiaPageMetadata][source]#

Extract Inertia page metadata from an application.

When multiple handlers map to the same component, GET handlers are preferred since Inertia pages are typically loaded via GET requests.

Parameters:

  • app – Litestar application instance.

  • openapi_schema – Optional OpenAPI schema dict.

  • fallback_type – TypeScript fallback type for unknown types.

  • openapi_support – Optional shared OpenAPISupport instance. If not provided, a new one will be created. Sharing improves determinism and performance.

Returns:

List of InertiaPageMetadata for each discovered page.

litestar_vite.codegen.extract_route_metadata(app: Litestar, *, only: list[str] | None = None, exclude: list[str] | None = None, openapi_schema: dict[str, Any] | None = None) → list[RouteMetadata][source]#

Extract route metadata from a Litestar application.

Note

openapi_schema is used to resolve accurate type component references. If not provided, it will be generated from the application automatically.

Returns:

A list of RouteMetadata objects.

litestar_vite.codegen.find_asyncapi_plugin(app: Litestar) → Any | None[source]#

Find an AsyncAPI plugin registered on the Litestar application.

Queries Litestar’s plugin registry for a registered AsyncAPIPlugin, guarded by ASYNCAPI_INSTALLED.

Parameters:

app – The Litestar application instance.

Returns:

The registered AsyncAPI plugin instance if found, otherwise None.

litestar_vite.codegen.generate_inertia_pages_json(app: Litestar, *, openapi_schema: dict[str, Any] | None = None, include_default_auth: bool = True, include_default_flash: bool = True, inertia_config: InertiaConfig | None = None, types_config: TypeGenConfig | None = None) → dict[str, Any][source]#

Generate Inertia pages metadata JSON.

The output is deterministic: all dict keys are sorted alphabetically to produce byte-identical output for the same input data.

A single OpenAPISupport instance is shared across both page extraction and shared props building to ensure consistent schema registration and naming. This eliminates non-determinism from split schema registries.

Returns:

An Inertia pages metadata payload as a dictionary with sorted keys.

litestar_vite.codegen.generate_routes_json(app: Litestar, *, only: list[str] | None = None, exclude: list[str] | None = None, include_components: bool = False, openapi_schema: dict[str, Any] | None = None, routes_metadata: list[RouteMetadata] | None = None) → dict[str, Any][source]#

Generate Ziggy-compatible routes JSON.

The output is deterministic: routes are sorted by name to produce byte-identical output for the same input data.

Returns:

A Ziggy-compatible routes payload as a dictionary with sorted keys.

litestar_vite.codegen.generate_routes_ts(app: Litestar, *, only: list[str] | None = None, exclude: list[str] | None = None, openapi_schema: dict[str, Any] | None = None, global_route: bool = False, routes_metadata: list[RouteMetadata] | None = None) → str[source]#

Generate typed routes TypeScript file (Ziggy-style).

The output is deterministic: routes are sorted by name to produce byte-identical output for the same input data.

Returns:

The generated TypeScript source.

litestar_vite.codegen.normalize_asyncapi_document(document: dict[str, Any]) → dict[str, Any][source]#

Normalize an AsyncAPI document into a consistent internal shape.

Guarantees that:

  1. The asyncapi version string is present (‘3.0.0’ or ‘3.1.0’).

  2. Channels are re-keyed into collision-safe litestar-vite format using _ChannelKeyAllocator with protocol-aware source selection.

  3. Every channel has an explicit bindings dictionary with protocol markers.

  4. Operation channel and message $ref pointers match the allocated channel keys.

  5. Root document metadata, servers, and components are preserved intact.

Parameters:

document – Raw AsyncAPI document dictionary.

Returns:

A normalized AsyncAPI document dictionary.

litestar_vite.codegen.resolve_asyncapi_document(app: Litestar, title: str | None = None, version: str | None = None) → dict[str, Any] | None[source]#

Resolve and normalize the AsyncAPI document from a registered AsyncAPIPlugin.

Queries the Litestar application for a registered AsyncAPIPlugin via find_asyncapi_plugin. When present, retrieves the schema from the plugin via get_asyncapi_schema (or get_asyncapi_json if a non-dict is returned) and normalizes channel keys and operation references for frontend code generation. When no AsyncAPIPlugin is registered, returns None.

Parameters:

  • app – The Litestar application instance.

  • title – Optional title override for the AsyncAPI document.

  • version – Optional version override for the AsyncAPI document.

Returns:

Normalized AsyncAPI document dictionary when AsyncAPIPlugin is registered, otherwise None.

litestar_vite.codegen.strip_timestamp_for_comparison(content: bytes) → bytes[source]#

Remove generatedAt and other timestamp fields for content comparison.

This allows comparing file content while ignoring fields that change on every generation (like timestamps).

Parameters:

content – JSON content as bytes.

Returns:

JSON content with timestamp fields removed, sorted keys.

litestar_vite.codegen.typegen_outputs_requested(types_config: TypeGenConfig) → bool[source]#

Return whether the typegen config asks for any generated artifact.

litestar_vite.codegen.write_if_changed(path: Path, content: bytes | str, *, normalize_for_comparison: Callable[[bytes], bytes] | None = None, encoding: str = 'utf-8') → bool[source]#

Write content to file only if it differs from the existing content.

Uses hash comparison to avoid unnecessary writes that would trigger file watchers and unnecessary rebuilds. Optionally normalizes content before comparison (e.g., to strip timestamps).

Parameters:

  • path – The file path to write to.

  • content – The content to write (bytes or str).

  • normalize_for_comparison – Optional callback to normalize content before comparison (e.g., strip timestamps). The file is written with the original content, not the normalized version.

  • encoding – Encoding for string content.

Returns:

True if file was written (content changed), False if skipped (unchanged).