API Client Code Generation

This skill manages the workflow for keeping the frontend TypeScript API client in sync with the backend.

When to use this skill

• After modifying Litestar routes in

  backend/app/

• After changing request/response schemas (msgspec)
• After adding new API endpoints
• When frontend TypeScript errors mention missing types
• Before committing changes that affect the API contract

Quick Command

make codegen  # Generate TypeScript API client from backend OpenAPI schema

Complete Workflow

1. Modify backend (routes, schemas, endpoints)

   • Edit Litestar route handlers in

     backend/app/server/

   • Update msgspec schemas in

     backend/app/domain/*/schemas.py

   • Add new endpoints or modify existing ones

2. Generate API client

   make codegen
   

   This will:

   • Start the backend server temporarily
   • Fetch OpenAPI schema from

     /schema/openapi.json

   • Generate TypeScript client in

     frontend/src/openapi/

   • Stop the backend server

3. Verify generation

   • Check

     frontend/src/openapi/

     for new types
   • Review generated request/response interfaces
   • Look for any generation warnings

4. Update frontend code

   • Import new types from

     @/openapi

   • Use generated API client methods
   • Fix any TypeScript errors

5. Type check

   make check-frontend  # Verify TypeScript compilation
   

What Gets Generated

The codegen process creates:

• Type definitions: Request/response interfaces
• API client methods: Type-safe API calls
• Enums and constants: From backend schemas
• Path parameters: Type-safe route params

Location:

frontend/src/openapi/

Example Usage

Backend Schema (msgspec)

# backend/app/domain/users/schemas.py
from msgspec import Struct

class UserCreateRequest(Struct):
    email: str
    name: str

class UserResponse(Struct):
    id: int
    email: str
    name: str
    created_at: str

Generated TypeScript

// frontend/src/openapi/models.ts
export interface UserCreateRequest {
  email: string;
  name: string;
}

export interface UserResponse {
  id: number;
  email: string;
  name: string;
  created_at: string;
}

Frontend Usage

import { api } from '@/openapi';
import type { UserCreateRequest, UserResponse } from '@/openapi';

const createUser = async (data: UserCreateRequest): Promise<UserResponse> => {
  const response = await api.users.create(data);
  return response;
};

Troubleshooting

Generation fails

• Backend not starting: Check for syntax errors in Python code
• Port 8000 in use: Stop existing backend process
• OpenAPI schema errors: Verify all route handlers have proper schemas

Types missing after generation

• Endpoint not in OpenAPI: Ensure route is registered in Litestar app
• Schema not exported: Check msgspec Struct definitions
• Route tags: Verify API grouping/tagging

Frontend TypeScript errors after codegen

• Incompatible changes: Breaking API changes require frontend updates
• Missing imports: Update imports to use new generated types
• Deprecated types: Remove references to old type names

Best Practices

1. Run codegen frequently: After any backend schema changes
2. Commit generated files: Include

   frontend/src/openapi/

   in commits
3. Review changes: Check git diff for generated code changes
4. Type safety: Let TypeScript catch API contract mismatches
5. Breaking changes: Coordinate with frontend team for major API changes

Integration with Development Workflow

Making API Changes

1. Modify backend route/schema
2. Run

   make codegen

3. Update frontend code to use new types
4. Run

   make check-frontend

5. Test changes locally
6. Commit all changes together (backend + frontend + generated)

Before Pull Request

make codegen         # Regenerate API client
make check-all       # Type check everything
make test            # Run backend tests

This ensures the API contract is in sync across the full stack.