Hey API

Use this skill when work touches Hey API / @hey-api/openapi-ts: generating TypeScript clients from OpenAPI, configuring plugins, wiring HTTP clients, validators, TanStack Query artifacts, or regenerating API layers.

Workflow

1. Inspect the local Hey API surface before changing code:

- Package versions for @hey-api/openapi-ts, @hey-api/vite-plugin, client packages, validators (zod / valibot), and TanStack Query. - Config file: openapi-ts.config.ts (or .js / .mjs / .cjs) and any Vite plugin integration. - Spec input: local path, remote URL, registry shorthand (hey-api/..., scalar:..., readme:...), or inline object. - Output folder contents (*.gen.ts, client/, core/) and whether consumers import from index.ts or specific generated files. - Runtime wiring: client.setConfig, runtimeConfigPath / createClientConfig, auth, interceptors, per-call client overrides.

1. Refresh docs when the user asks for latest behavior, the installed version is unclear, or the work touches migrations, plugin APIs, or Node/runtime requirements. Start from [source-map.md](references/source-map.md).
2. For install, CLI, defineConfig, input/output, multi-job configs, and Vite, use [setup-config.md](references/setup-config.md).
3. For HTTP clients, SDK shapes, auth, interceptors, throwOnError, and consuming generated functions, use [clients-sdk.md](references/clients-sdk.md).
4. For Zod/Valibot, TanStack Query, transformers/validators, and web-framework plugins, use [plugins-validators.md](references/plugins-validators.md).
5. For output layout, entry exports, and breaking-change checks, use [output-migration.md](references/output-migration.md).
6. Implement in the existing project style:

- Prefer regenerating over hand-editing *.gen.ts or bundled client/ / core/ scaffolding. - Compose only the plugins the app needs; defaults already emit TypeScript + SDK (Fetch). - Pin @hey-api/openapi-ts to an exact version unless the project deliberately tracks a range. - Prefer bun / bunx in command examples when adding scripts.

Judgment

• Treat the OpenAPI spec as the contract. Fix or regenerate from the spec; do not paper over drift with local edits to generated files.
• Treat the output folder as a dependency. Changes there are erased on the next codegen run.
• Default client is Fetch (@hey-api/client-fetch). Pick Axios, Ky, Next.js, Nuxt, OFetch, or Angular only when the runtime needs them.
• SDK responses are typically { data, error } unless throwOnError is enabled on the client plugin (not the SDK plugin).
• Enable SDK validator / transformer only when runtime validation or transformation is intentional; it has a cost and pulls in the validator plugin.
• For React Query, prefer spreading generated Options() / Mutation() helpers into useQuery / useMutation rather than re-wrapping SDK calls by hand.
• Watch mode supports remote URL inputs; do not assume local-file watch works.
• Requires Node.js 22+ (22.13+ for recent releases). Package is ESM-only since v0.91.
• Python codegen is not production-ready yet; keep this skill focused on TypeScript @hey-api/openapi-ts.

Verification

Prefer the repo's existing checks. For meaningful Hey API work, include the relevant subset:

• Regenerate with the project's openapi-ts script and confirm a clean diff policy for generated output.
• Typecheck consumers of SDK functions, query options, and Zod/Valibot schemas.
• Smoke one success path and one error path (data vs error, or thrown errors if throwOnError).
• Confirm baseUrl / baseURL (client-specific), auth, and interceptors against a real or mocked endpoint.
• After upgrades, read Migrating for the crossed versions before merging.