openapi-ts-v0 skill

---
name: Hey API Codegen
description: |
  Generate TypeScript clients from OpenAPI specs using @hey-api/openapi-ts. Type-safe API clients with Zod schemas.
  
  Use when: generating TypeScript clients from OpenAPI specifications for frontend or API consumers.
---

# Skill: openapi-ts

## Scope

- Applies to: Generating TypeScript clients from OpenAPI 3.0 specifications using `@hey-api/openapi-ts`
- Does NOT cover: Writing OpenAPI specs, API server implementation (see [fastify](@cursor/skills/fastify-v5/SKILL.md))

## Assumptions

- `@hey-api/openapi-ts` v0+
- OpenAPI 3.0 specification format
- TypeScript v5+ with strict mode
- Zod for runtime validation (when using Zod schemas)

## Principles

- Generate clients from OpenAPI specs (single source of truth)
- Use generated Zod schemas for runtime validation
- Client methods are fully typed from OpenAPI spec
- Error responses are typed from OpenAPI error schemas
- Use `createClient` factory for client instantiation
- Configure output format and schema type in config file

## Constraints

### MUST

- Use `openapi-ts.config.ts` for configuration
- Generate clients before using in code
- Handle `response.error` for typed error responses

### SHOULD

- Use Zod schemas (`schemas.type: 'zod'`) for runtime validation
- Use Prettier formatting (`output.format: 'prettier'`)
- Generate TypeScript enums (`types.enums: 'typescript'`)

### AVOID

- Manually editing generated code
- Using generated clients without error handling
- Mixing generated and manual client code

## Interactions

- Consumes OpenAPI specs generated by [fastify](@cursor/skills/fastify-v5/SKILL.md)
- Works with [nextjs](@cursor/skills/nextjs-v16/SKILL.md) for API client usage
- Integrates with TanStack Query (see [React Query Integration](references/react-query-integration.md))

## Patterns

### Configuration Pattern

```typescript
// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts'

export default defineConfig({
  input: './openapi.json',
  output: {
    path: './src/gen',
    format: 'prettier',
  },
  types: {
    enums: 'typescript',
  },
  schemas: {
    type: 'zod',
  },
})
```

### Client Usage Pattern

```typescript
import { createClient } from './gen/client'

const client = createClient({
  baseUrl: 'https://api.example.com',
})

const response = await client.GET('/users/{id}', {
  params: { path: { id: '123' } },
})

if (response.error) {
  // Handle typed error
  return
}

// response.data is typed from OpenAPI spec
```

See [Config Template](templates/openapi-ts.config.ts) for complete example.

## References

- [React Query Integration](references/react-query-integration.md) - Using generated clients with TanStack Query