Type Generation

Configure TypeScript type generation for routes and props.

Enabling Type Generation

from litestar_vite import ViteConfig, VitePlugin

# Simple - enable with defaults
VitePlugin(config=ViteConfig(
    types=True,
    inertia=True,
))

# Advanced - custom configuration
from litestar_vite.config import TypeGenConfig

VitePlugin(config=ViteConfig(
    types=TypeGenConfig(
        output=Path("src/generated"),
        generate_routes=True,
        generate_page_props=True,
    ),
    inertia=True,
))

TypeGenConfig Reference

Parameter

Type

Description

output

Path

Output directory for generated files. Default: src/generated

openapi_path

Path | None

Path for OpenAPI schema. Default: {output}/openapi.json

routes_path

Path | None

Path for routes JSON. Default: {output}/routes.json

routes_ts_path

Path | None

Path for routes TypeScript. Default: {output}/routes.ts

page_props_path

Path | None

Path for page props JSON. Default: {output}/inertia-pages.json

generate_zod

bool

Generate Zod schemas. Default: False

generate_sdk

bool

Generate API client SDK. Default: True

generate_routes

bool

Generate typed routes.ts. Default: True

generate_page_props

bool

Generate page props types. Default: True

fallback_type

Literal["unknown", "any"]

Fallback value type for untyped dict/list in page props. Default: unknown

type_import_paths

dict[str, str]

Map schema/type names to TypeScript import paths for props types excluded from OpenAPI. Default: {}

global_route

bool

Register route() globally on window. Default: False

watch_patterns

list[str]

Patterns to watch for regeneration

Generating Types

# Generate all types
litestar assets generate-types

# Or export routes only
litestar assets export-routes

Generated routes.ts

The routes.ts file provides type-safe route handling:

// If OpenAPI schemas include a `format`, `routes.ts` also emits semantic aliases
// and uses them in route parameter types (aliases are plain primitives, no runtime parsing).
export type UUID = string;
export type DateTime = string;

// Generated types
export type RouteName = "home" | "dashboard" | "user-profile" | ...;

export interface RoutePathParams {
  "user-profile": { userId: number };
  "home": Record<string, never>;
  // ...
}

export interface RouteQueryParams {
  "user-profile": Record<string, never>;
  "home": Record<string, never>;
  // ...
}

type EmptyParams = Record<string, never>
type MergeParams<A, B> =
  A extends EmptyParams ? (B extends EmptyParams ? EmptyParams : B) : B extends EmptyParams ? A : A & B

export type RouteParams<T extends RouteName> =
  MergeParams<RoutePathParams[T], RouteQueryParams[T]>;

// Type-safe route function (params required only when needed)
export function route<T extends RoutesWithoutRequiredParams>(name: T): string;
export function route<T extends RoutesWithoutRequiredParams>(name: T, params?: RouteParams<T>): string;
export function route<T extends RoutesWithRequiredParams>(name: T, params: RouteParams<T>): string;

// Usage
route("home");                           // "/"
route("user-profile", { userId: 123 });  // "/users/123"
route("user-profile");                   // TS Error: missing params

Note

For URL generation, route params never require null values. Optionality is represented by optional query parameters (?:) and omission, matching how route() serializes values.

Generated inertia-pages.json

The Vite plugin reads this metadata to generate page-props.ts:

{
  "pages": {
    "Dashboard": {
      "route": "/dashboard",
      "tsType": "DashboardProps",
      "schemaRef": "#/components/schemas/DashboardProps",
      "customTypes": ["DashboardProps"]
    }
  },
  "typeImportPaths": {
    "InternalProps": "@/types/internal"
  },
  "fallbackType": "unknown",
  "typeGenConfig": {
    "includeDefaultAuth": true,
    "includeDefaultFlash": true
  },
  "generatedAt": "2025-12-11T00:00:00Z"
}

Vite Plugin Configuration

The Vite plugin generates the final page-props.ts:

vite.config.ts
import litestar from "litestar-vite-plugin";

export default {
  plugins: [
    litestar({
      input: ["resources/main.ts"],
      hotFile: "public/hot",
      // Page props generation is automatic when inertia-pages.json exists
    }),
  ],
};

Watch Mode

Configure patterns to trigger regeneration:

TypeGenConfig(
    watch_patterns=[
        "**/routes.py",
        "**/handlers.py",
        "**/controllers/**/*.py",
    ],
)

Output Structure

Default generated file structure:

src/generated/
├── openapi.json       # OpenAPI schema
├── routes.json        # Route metadata
├── routes.ts          # Type-safe route helper
├── inertia-pages.json # Page props metadata
└── page-props.ts      # Generated by Vite plugin

See Also