Inspect the local Hey API surface before changing code:
- Package versions for @hey-api/openapi-ts (latest stable 0.99.0; ignore next snapshot builds), @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.
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.
For install, CLI, defineConfig, input/output, multi-job configs, and Vite, use setup-config.md.
For HTTP clients, SDK shapes, auth, interceptors, throwOnError, and consuming generated functions, use clients-sdk.md.
For Zod/Valibot, TanStack Query, transformers/validators, and web-framework plugins, use plugins-validators.md.
For output layout, entry exports, and breaking-change checks, use output-migration.md.
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.18.0 (since v0.98; v0.96–v0.97 needed >= 22.13.0). 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.

heyapi

Hey API

Workflow