OpenAPI TypeScript SDK & Schema Helpers¶

When TypeGenConfig(generate_sdk=True) is active, Litestar Vite exports Litestar's OpenAPI 3.1 schema to src/generated/openapi.json and runs @hey-api/openapi-ts inside litestar-vite-plugin to generate a complete, tree-shakeable TypeScript client SDK under src/generated/api/.

Python Configuration¶

docs/examples/typegen/openapi_and_routes.py

"""OpenAPI SDK and Ziggy-style typed route metadata export."""

from __future__ import annotations

from pathlib import Path

from litestar import Litestar, get
from msgspec import Struct

from litestar_vite import RuntimeConfig, TypeGenConfig, ViteConfig, VitePlugin
from litestar_vite.codegen import generate_routes_json, generate_routes_ts


class CustomerRecord(Struct, frozen=True, gc=False):
    """Customer response schema exported to OpenAPI and TypeScript."""

    id: int
    name: str
    tier: str


@get("/api/customers", name="customers:list", sync_to_thread=False)
def list_customers() -> list[CustomerRecord]:
    """Return all customers for the generated OpenAPI SDK."""
    return [CustomerRecord(id=1, name="Acme Corp", tier="enterprise")]


def create_app() -> Litestar:
    """Create a Litestar app with OpenAPI SDK and route codegen enabled."""
    vite_config = ViteConfig(
        mode="spa",
        dev_mode=True,
        runtime=RuntimeConfig(start_dev_server=False),
        types=TypeGenConfig(
            output=Path("src/generated"), generate_sdk=True, generate_routes=True, generate_page_props=False
        ),
    )
    return Litestar(route_handlers=[list_customers], plugins=[VitePlugin(config=vite_config)])


def main() -> None:
    """Verify deterministic route metadata and TypeScript route generation."""
    app = create_app()
    routes_data = generate_routes_json(app)
    routes_ts = generate_routes_ts(app)
    assert "customers:list" in routes_data["routes"]
    assert "customers:list" in routes_ts


__all__ = ("CustomerRecord", "create_app", "list_customers", "main")

Ergonomic Schema Type Helpers¶

Raw @hey-api/openapi-ts types require indexing into generated operation request/response unions. To make forms and API responses effortless, TypeGenConfig(generate_schemas=True) generates src/generated/schemas.ts with high-level utility types keyed by operation or route name:

Helper Type	Resolves To	Example
`FormInput<K>`	Request body payload type for operation `K`	`type CreateCustomerForm = FormInput<"customers:create">;`
`FormResponse<K, Status>`	Response body type for operation `K` and HTTP status code	`type ValidationErr = FormResponse<"customers:create", 422>;`
`SuccessResponse<K>`	200 / `201` success response payload for operation `K`	`type CustomerList = SuccessResponse<"customers:list">;`
`ErrorResponse<K>`	Union of error response payloads (400, 422, 500) for operation `K`	`type CreateCustomerError = ErrorResponse<"customers:create">;`
`PathParams<K>`	Path parameter object for operation `K`	`type CustomerPath = PathParams<"customers:detail">;`
`QueryParams<K>`	Query string parameter object for operation `K`	`type CustomerQuery = QueryParams<"customers:list">;`

src/components/CustomerList.tsx

import { listCustomers } from "../generated/api";
import type { FormInput, SuccessResponse } from "../generated/schemas";

type Customers = SuccessResponse<"customers:list">;
type NewCustomerInput = FormInput<"customers:create">;

export async function fetchEnterpriseCustomers(_draft?: NewCustomerInput): Promise<Customers> {
  const { data } = await listCustomers({ throwOnError: true });
  return data.filter((customer: { tier: string }) => customer.tier === "enterprise");
}

Runtime Zod Schema Generation¶

Set TypeGenConfig(generate_zod=True) when you want @hey-api/openapi-ts to emit runtime Zod validation schemas alongside static TypeScript interfaces — ideal for client-side form validation with React Hook Form, TanStack Form, or VeeValidate:

from litestar_vite import TypeGenConfig, ViteConfig

config = ViteConfig(
    types=TypeGenConfig(
        generate_sdk=True,
        generate_zod=True,
    ),
)

Customizing the OpenAPI Generator¶

If your project includes an openapi-ts.config.ts file in the root directory, litestar-vite-plugin respects your custom plugins, client selection (@hey-api/client-fetch), and formatting rules while keeping input and output synchronized with .litestar.json:

openapi-ts.config.ts

import { defineConfig } from "@hey-api/openapi-ts";

export default defineConfig({
  input: "./src/generated/openapi.json",
  output: "./src/generated/api",
  plugins: [
    "@hey-api/client-fetch",
    "@hey-api/schemas",
    "@hey-api/sdk",
    {
      name: "@hey-api/typescript",
      enums: "javascript",
    },
  ],
});

Generating Types from the CLI¶

In CI pipelines or before running tsc --noEmit, run litestar assets generate-types to export all JSON schemas and execute @hey-api/openapi-ts without starting the HTTP server:

litestar assets generate-types