# Openapi TS V0

> Generate TypeScript clients from OpenAPI specs using @hey-api/openapi-ts — type-safe API clients. Use when generating TypeScript clients from OpenAPI specifications for frontend or API consumers.

- Skill: `blockmatic/openapi-ts-v0` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add blockmatic/openapi-ts-v0`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blockmatic/openapi-ts-v0/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: blockmatic (https://skillmd.com/u/blockmatic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/blockmatic/openapi-ts-v0

---


# 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](../fastify-v5/SKILL.md))

## Assumptions

- `@hey-api/openapi-ts` v0+
- OpenAPI 3.0 specification format
- TypeScript v5+ with strict mode
- Default output is types and client only; React Query hooks are handwritten in consuming apps

## Principles

- Generate clients from OpenAPI specs (single source of truth)
- 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
- Zod schemas and generated React Query plugins are optional add-ons

## Constraints

### MUST

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

### SHOULD

- Use Prettier formatting (`output.format: 'prettier'`)
- Generate TypeScript enums (`types.enums: 'typescript'`)
- Write TanStack Query hooks by hand against the generated client
- Add Zod schemas (`schemas.type: 'zod'`) only when runtime validation is required
- Add generated React Query plugin only when the project opts into it

### AVOID

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

## Interactions

- Consumes OpenAPI specs generated by [fastify](../fastify-v5/SKILL.md)
- Works with [next](../next-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',
  },
})
```

### 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