mcpField
H
heyapi

heyapi

github.com/dobroslavradosavljevicDevelopment342 installsUpdated 3d ago
Repository

About heyapi

heyapi is a coding skill for TypeScript projects using Hey API and `@hey-api/openapi-ts`. It guides API client generation, configuration, plugin use, and validation of generated code.

Key features

  1. 01OpenAPI-to-TypeScript client guidance
  2. 02Plugin and validator configuration
  3. 03HTTP client and auth setup
  4. 04Generated output and migration checks
  5. 05Code generation verification

Use cases

  1. 01Generating a TypeScript API layer from an OpenAPI spec
  2. 02Configuring TanStack Query or validation plugins
  3. 03Updating Hey API versions and migrations

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dobroslavradosavljevic/skills --skill heyapi

After installing, type/heyapiin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
clients-sdk.md
output-migration.md
plugins-validators.md
setup-config.md
source-map.md

Details

From the project README

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 (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.
  2. 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.
  3. For install, CLI, defineConfig, input/output, multi-job configs, and Vite, use setup-config.md.
  4. For HTTP clients, SDK shapes, auth, interceptors, throwOnError, and consuming generated functions, use clients-sdk.md.
  5. For Zod/Valibot, TanStack Query, transformers/validators, and web-framework plugins, use plugins-validators.md.
  6. For output layout, entry exports, and breaking-change checks, use output-migration.md.
  7. 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.

Comments

Markdown supported