heyapi

Hey API

Hey API／@hey-api/openapi-ts に関わる作業では、このスキルを使用してください。対象には、OpenAPI からの TypeScript クライアント生成、プラグインの設定、HTTP クライアントの接続、バリデーター、TanStack Query の生成物、API レイヤーの再生成が含まれます。

ワークフロー

1. コードを変更する前に、ローカルの Hey API の状況を確認します。
   • @hey-api/openapi-ts（最新の安定版は 0.99.0。next のスナップショットビルドは対象外）、@hey-api/vite-plugin、クライアントパッケージ、バリデーター（zod／valibot）、TanStack Query のパッケージバージョン。
   • 設定ファイル：openapi-ts.config.ts（または .js／.mjs／.cjs）と、Vite プラグインの統合状況。
   • 仕様の入力元：ローカルパス、リモート URL、レジストリーの省略表記（hey-api/...、scalar:...、readme:...）、またはインラインオブジェクト。
   • 出力フォルダーの内容（*.gen.ts、client/、core/）と、コンシューマーが index.ts または個別の生成ファイルからインポートしているかどうか。
   • 実行時の接続設定：client.setConfig、runtimeConfigPath／createClientConfig、認証、インターセプター、呼び出しごとの client オーバーライド。
2. ユーザーが最新の動作を求めている場合、インストール済みのバージョンが不明な場合、または移行、プラグイン API、Node／ランタイム要件に関わる作業では、ドキュメントを最新の状態にします。source-map.md から確認を始めてください。
3. インストール、CLI、defineConfig、入力／出力、複数ジョブの設定、Vite については、setup-config.md を参照してください。
4. HTTP クライアント、SDK の形式、認証、インターセプター、throwOnError、生成された関数の利用については、clients-sdk.md を参照してください。
5. Zod／Valibot、TanStack Query、トランスフォーマー／バリデーター、Web フレームワーク用プラグインについては、plugins-validators.md を参照してください。
6. 出力の構成、エクスポートのエントリーポイント、破壊的変更の確認については、output-migration.md を参照してください。
7. 既存のプロジェクトのスタイルに沿って実装します。
   • *.gen.ts や、client/／core/ にまとめられた足場コードを手作業で編集するより、再生成を優先してください。
   • アプリに必要なプラグインだけを組み合わせます。デフォルトで TypeScript と SDK（Fetch）が生成されます。
   • プロジェクトでバージョン範囲を意図的に追跡している場合を除き、@hey-api/openapi-ts のバージョンを厳密に固定してください。
   • スクリプトを追加する際、コマンド例では bun／bunx を優先してください。

判断基準

• OpenAPI 仕様を契約として扱います。仕様から修正または再生成し、生成ファイルへのローカルな編集で差異を取り繕わないでください。
• 出力フォルダーは依存対象として扱います。次回のコード生成で内容が消去されます。
• デフォルトのクライアントは Fetch（@hey-api/client-fetch）です。実行環境で必要な場合に限り、Axios、Ky、Next.js、Nuxt、OFetch、Angular を選択してください。
• SDK のレスポンスは通常 { data, error } です。ただし、throwOnError が SDK プラグインではなくクライアントプラグインで有効になっている場合は異なります。
• SDK の validator／transformer は、実行時の検証または変換が意図されている場合にのみ有効にしてください。処理コストがかかり、バリデータープラグインも追加されます。
• React Query では、SDK 呼び出しを手作業で再ラップするより、生成された *Options()／*Mutation() ヘルパーを useQuery／useMutation に展開して使う方法を優先してください。
• ウォッチモードはリモート URL の入力に対応しています。ローカルファイルの監視も使えるとは限りません。
• Node.js >= 22.18.0 が必要です（v0.98 以降。v0.96～v0.97 では >= 22.13.0 が必要でした）。v0.91 以降、パッケージは ESM 専用です。
• Python のコード生成はまだ本番運用に適していません。このスキルでは TypeScript の @hey-api/openapi-ts を対象としてください。

検証

リポジトリに既存のチェックがあれば、それを優先してください。Hey API に関わる重要な作業では、関連する項目を選んで確認してください。

• プロジェクトの openapi-ts スクリプトで再生成し、生成された出力に対する差分ポリシーを満たしていることを確認します。
• SDK 関数、クエリーオプション、Zod／Valibot スキーマを使用する側の型チェックを実行します。
• 成功パスとエラーパスをそれぞれ 1 つ確認します（data と error のどちらが返るか、または throwOnError が有効な場合は例外がスローされること）。
• 実際の、またはモックのエンドポイントに対して、baseUrl／baseURL（クライアント固有）、認証、インターセプターを確認します。
• アップグレード後は、マージ前に、またいだバージョンに対応する 移行ガイド を読んでください。