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

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

class litestar_vite.codegen.ExportResult

Bases: object

Result of the export operation.

__init__(exported_files: list[str] = <factory>, unchanged_files: list[str] = <factory>, openapi_schema: dict[str, ~typing.Any] | None = None) → None

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

The OpenAPI schema dict (for downstream use).

exported_files: list[str]

Files that were written (content changed).

unchanged_files: list[str]

Files that were skipped (content unchanged).

class litestar_vite.codegen.InertiaPageMetadata

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>) → None

class litestar_vite.codegen.RouteMetadata

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.encode_deterministic_json(data: dict[str, Any], *, indent: int = 2, serializer: Callable[[Any], bytes] | None = None) → bytes

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_integration_assets(app: Litestar, config: ViteConfig, *, serializer: Callable[[Any], bytes] | None = None) → ExportResult

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.

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)

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]

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]

Extract route metadata from a Litestar application.

Note

openapi_schema is accepted for API compatibility and future enrichment, but parameter typing is currently derived from Litestar’s OpenAPI parameter generation, not the exported schema document.

Returns:

A list of RouteMetadata objects.

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]

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) → dict[str, Any]

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) → str

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.strip_timestamp_for_comparison(content: bytes) → bytes

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.write_if_changed(path: Path, content: bytes | str, *, normalize_for_comparison: Callable[[bytes], bytes] | None = None, encoding: str = 'utf-8') → bool

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).