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

   bash

   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

   bash

   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.