How To: TypeScript Type Generation¶

TypeScript types are auto-generated from the backend's OpenAPI schema.

Generate Types¶

npm run types:generate   # Backend must be running on localhost:8000

This: 1. Fetches http://localhost:8000/api/v1/openapi.json 2. Generates TypeScript interfaces in packages/api-client/src/generated/api.ts 3. Types are re-exported from packages/api-client/src/types.ts

When to Run¶

After adding/modifying Pydantic schemas in backend/app/schemas/
After adding new API endpoints with response_model
Before committing frontend changes that use new types

Common TypeScript Errors¶

Error	Cause	Fix
Property does not exist	Backend schema changed	Run `npm run types:generate`
Type 'never'	Types not generated yet	Run `npm run types:generate`
Nullable fields	Optional API fields	Use optional chaining: `plate.explanation?.summary`

Pre-commit Hook¶

TypeScript type checking runs automatically before commits via Husky. To bypass (emergency only): git commit --no-verify

How It Works¶

The pipeline uses openapi-typescript to convert the FastAPI OpenAPI spec into TypeScript interfaces. The packages/api-client package re-exports these types for use in apps/web and apps/admin.

FastAPI Pydantic schemas
    → OpenAPI JSON (/api/v1/openapi.json)
    → openapi-typescript
    → packages/api-client/src/generated/api.ts
    → re-exported from packages/api-client/src/types.ts
    → consumed by apps/web and apps/admin