openapi-ts-v0_skill

Overview

This skill generates TypeScript API clients from OpenAPI 3.0 specifications using @hey-api/openapi-ts. It produces fully typed client methods and optional Zod schemas for runtime validation, enabling type-safe API consumption in frontend or consumer code. The output is configured and generated before use, keeping the OpenAPI spec as the single source of truth.

How this skill works

You configure generation in openapi-ts.config.ts and run the generator to emit a TypeScript client and types into a chosen output path. The generated client includes methods typed from OpenAPI operations, typed error responses, and optional Zod validators when schemas.type is set to 'zod'. Use createClient to instantiate a client and inspect response.error for typed error handling.

When to use it

• When you need a type-safe TypeScript client for a REST API defined in an OpenAPI 3.0 spec.
• When you want runtime validation of responses using Zod schemas.
• When you want to avoid manual client code and keep API types sync'd with the spec.
• When integrating generated clients into frontend apps (Next.js, React) or API consumers.
• When you need typed error handling driven by OpenAPI error schemas.

Best practices

• Keep an openapi-ts.config.ts file and include generation in your build or codegen step.
• Enable Zod schemas (schemas.type: 'zod') for runtime validation of responses.
• Format generated output with Prettier (output.format: 'prettier') to keep diffs clean.
• Generate TypeScript enums (types.enums: 'typescript') to preserve enum semantics.
• Never manually edit generated files; treat them as ephemeral and regenerate from the spec.
• Always check response.error and handle typed error payloads instead of assuming success.

Example use cases

• Frontend Next.js app consuming a backend OpenAPI spec and using generated clients in server or client components.
• React apps integrated with TanStack Query using generated methods as query/mutation functions.
• A TypeScript SDK for third-party consumers where runtime validation with Zod is required.
• Automated codegen in CI that regenerates clients when the OpenAPI spec changes.
• Migrating from handwritten fetch wrappers to a single source of truth generated client.