HuynhSang2005/hey-api-openapi-ts
.agents/skills/hey-api-openapi-ts/SKILL.md
End-to-end guidance for @hey-api/openapi-ts across configuration, plugin composition, generated artifact usage, migration safety, and runtime integration. Use whenever users mention hey-api, openapi-ts, openapi-ts.config.ts, sdk.gen.ts, client.gen.ts, types.gen.ts, zod.gen.ts, @hey-api/client-fetch, @hey-api/sdk, @tanstack/react-query.gen, or OpenAPI code generation workflows.
tools
Updated Apr 16, 2026
$ install --global
skillsauthnpx skillsauth add HuynhSang2005/delivery-app hey-api-openapi-tsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 8:53 PM1.8s1 file scanned
SKILL.md
- name:
- hey-api-openapi-ts
- description:
- End-to-end guidance for @hey-api/openapi-ts across configuration, plugin composition, generated artifact usage, migration safety, and runtime integration. Use whenever users mention hey-api, openapi-ts, openapi-ts.config.ts, sdk.gen.ts, client.gen.ts, types.gen.ts, zod.gen.ts, @hey-api/client-fetch, @hey-api/sdk, @tanstack/react-query.gen, or OpenAPI code generation workflows.
Hey API OpenAPI TS
Use this skill to implement, audit, refactor, and troubleshoot projects that generate API layers with @hey-api/openapi-ts.
When to Use This Skill
- User asks to set up or improve
@hey-api/openapi-ts. - User asks about generated outputs like
sdk.gen.ts,types.gen.ts,client.gen.ts,zod.gen.ts,transformers.gen.ts, or TanStack output files. - User needs migration support after version upgrades.
- User reports API typing drift, runtime auth/interceptor issues, or validator/transformer mismatch.
- User wants reusable patterns for Fetch-based generated clients.
When Not to Use This Skill
- Work is unrelated to OpenAPI code generation.
- User asks for generic API design without codegen/tooling integration.
- Project uses a different generator and user did not request hey-api adoption.
Core Principles
- Generated artifacts are dependencies: never hand-edit
.gen.tsfiles. - Prefer generated SDK and types over ad-hoc request code.
- Keep runtime config centralized and deterministic.
- Use plugin composition intentionally (client, sdk, validators, transformers, state plugins).
- Run migration checks against official migration notes before and after version bumps.
Standard Workflow
- Discover current setup.
- Validate plugin composition and output contract.
- Audit runtime integration (
client.setConfig(), runtime config path, interceptors). - Audit consumption patterns (SDK usage, generated query options, query keys, error mapping).
- Apply minimum necessary changes.
- Regenerate and verify (types, lint, tests, build).
- Document migration and maintenance notes.
Discovery Checklist
- Locate generator config (usually
openapi-ts.config.ts). - Identify generator script in
package.json. - Identify source specs (
openapi/*.json|yamlor URL inputs). - Identify output path and all generated files.
- Detect active plugins and option set.
- Detect runtime wiring location (
main.tsx, app bootstrap, or API init module).
Detailed checklist: references/audit-checklist.md
Configuration Model (Plugin-First)
At minimum, validate:
input: file path(s), URL(s), or OpenAPI object(s).output.path: generated destination.plugins: explicit ordered list.
Common production stack for Fetch + SDK + validation + transforms + TanStack Query:
@hey-api/client-fetch@hey-api/sdkzod(or another validator plugin)@hey-api/transformers@tanstack/react-query(or framework equivalent)
Reference recipes: references/config-recipes.md
Runtime Integration Patterns
Preferred order of runtime initialization:
- Configure base URL and auth.
- Add request/response interceptors.
- Add error interceptor/mapping.
- Start app/providers.
Supported patterns:
client.setConfig()at startup.runtimeConfigPathfor initialization-time defaults.- Override per-call via SDK request options.
- Custom client instance for one-off domain/tenant routes.
Reference runtime patterns: references/runtime-patterns.md
Generated Artifact Contract
Treat these outputs as stable integration surfaces:
client.gen.ts: global client instance setup.sdk.gen.ts: operation-level SDK functions/classes.types.gen.ts: canonical request/response types.zod.gen.ts/ validator artifacts: runtime schema validation.transformers.gen.ts: parse/transform helpers when enabled.@tanstack/...gen.ts: generated query/mutation option builders.
Never duplicate generated DTOs unless extending with clearly named local view-model types.
Migration Guardrails
Before upgrading @hey-api/openapi-ts:
- Read official migration notes.
- Check runtime version constraints (Node and ESM support changes).
- Check renamed/removed options and plugin API shifts.
- Snapshot generated output or run on a branch.
- Compare generated diffs before merging.
Reference migration watchlist: references/migration-watchlist.md
Verification Requirements
After any generator or config change:
- Run generation script.
- Run type-check.
- Run lint.
- Run tests (focused then full as needed).
- Run build.
Reference verification matrix: references/testing-and-verification.md
Anti-Patterns
- Manually editing
.gen.tsfiles. - Replacing generated SDK calls with manual
fetch/axioswithout explicit reason. - Mixing generated query keys with unrelated key conventions without a deliberate adapter strategy.
- Enabling transformer plugin but forgetting
sdk.transformer. - Enabling validator intent without validator plugin or
sdk.validatorwiring. - Upgrading versions without reading migration notes.
Related Skills
tanstack-query-best-practicesfor cache and mutation strategy.zodfor schema authoring/validation conventions.plan-workfor multi-file design and sequencing.execute-workfor disciplined implementation checkpoints.systematic-debuggingfor root-cause investigation.verification-before-completionbefore claiming success.
Templates
templates/openapi-ts.config.fetch-react-query.tstemplates/runtime-config.fetch.ts
Sources
- Official docs:
https://heyapi.dev/openapi-ts/ - Migration notes:
https://heyapi.dev/openapi-ts/migrating - Fetch client docs:
https://heyapi.dev/openapi-ts/clients/fetch - SDK docs:
https://heyapi.dev/openapi-ts/plugins/sdk - Repository:
https://github.com/hey-api/openapi-ts
Related Skills
HuynhSang2005/react-hook-form
tools
VerifiedTrustedCommunity
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, and useFieldArray. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling.
SKILL.mdUpdated Apr 16, 2026
HuynhSang2005/react-hook-form-zod
tools
VerifiedTrustedCommunity
Build type-safe validated forms using React Hook Form v7 and Zod v4. Single schema works on client and server with full TypeScript inference via z.infer. Use when building forms, multi-step wizards, or fixing uncontrolled warnings, resolver errors, useFieldArray issues, performance problems with large forms.
SKILL.mdUpdated Apr 16, 2026
HuynhSang2005/prisma-postgres
tools
VerifiedTrustedCommunity
Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres databases, working in Prisma Console, provisioning with create-db/create-pg/create-postgres, or integrating programmatic provisioning with service tokens or OAuth.
SKILL.mdUpdated Apr 16, 2026
HuynhSang2005/prisma-driver-adapter-implementation
development
VerifiedTrustedCommunity
Required reference for Prisma v7 driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter/Transaction interfaces. Contains critical contract details not inferable from code examples — including the transaction lifecycle protocol, error mapping requirements, and verification checklist. Existing implementations do not replace this skill.
SKILL.mdUpdated Apr 16, 2026