trpc

tRPC v11

エージェントがコードの作成やレビュー時に適用できるよう、tRPC が求める判断事項とその解決方法をまとめています。すべてのルールで、修正対象となる誤ったデフォルトを明示しています。モデルがすでに正しく判断できる事項についてのルールはありません。

tRPC v11 に固定されており、11.18.0（2026-06-17）に対して検証済みです。 v12 はありません。ただし、ここで取り上げるいくつかの API には @deprecated … will be removed in v12 と記載されており、現在も提供されています。ピア依存関係：typescript >=5.7.2、@tanstack/react-query ^5.80.3、react >=18.2.0。

適用する場面

次の場合にこのスキルを使用します。

• コードで initTRPC、createTRPCContext、createTRPCOptionsProxy、createTRPCReact、createTRPCClient、httpBatchLink、httpSubscriptionLink、splitLink、fetchRequestHandler、createCallerFactory、TRPCError をインポートしている場合、または .input() / .output() / .use() / .query() / .mutation() / .subscription() でプロシージャを定義している場合
• ユーザーが「すべての型が any になる」「無効化が機能しない」「contextMap[utilName] is not a function」「transformer プロパティの場所が変わった」「ダッシュボードで 414 / 413 が発生する」「サブスクリプションに接続できない」「プリフェッチがハイドレーションされない」「すべてのプロシージャが 404 になる」と言った場合
• コードベースを tRPC v10 から移行する場合、または v10 時代の例に基づいて書かれた tRPC コードをレビューする場合。推奨される React クライアントが変更されており、古いコードがそのままコンパイルできることも多いため、特に効果的な適用タイミングです
• 既存のルーターに初めてサブスクリプション、ファイルアップロード、または RSC プリフェッチを追加する場合。それぞれで、v11 が v10 の方式を全面的に置き換えた領域に入るためです
• アプリの成長に合わせてバッチ処理クライアントをレビューする場合。上限のないデフォルト設定が、本番環境で断続的な障害につながるためです

このスキルの対象外：

• TanStack Query の一般的なセマンティクス：キャッシュの有効期間、再試行、useMutation の使い勝手（→ tanstack-query）
• バリデーターとして使用する Zod スキーマの作成や移行（→ zod）
• tRPC ハンドラーの範囲を超えた Next.js App Router のルーティング、ストリーミング、キャッシュ（→ nextjs）
• TypeScript の一般的な型の絞り込みやジェネリクス（→ typescript）

ルールのカテゴリ

#	カテゴリ	接頭辞	対象
1	React クライアントのインターフェース	client-	使用する統合、オプションファクトリー、クエリーキー、無効化、サブスクライブ
2	v10 → v11 の差分	mig-	名前変更、削除、遅延生成される API、ピア依存関係の最低バージョン
3	ルーターとプロシージャの構築	proc-	インスタンスの同一性、ビルダーの順序、コンテキストの型の絞り込み、入力のマージ
4	エラーと検証のセマンティクス	err-	表面化する内容、漏えいする内容、使用するエラークラス
5	リンク、トランスポート、シリアライズ	link-	リンクチェーン、バッチ処理の上限、トランスフォーマー、アダプター、キャッシュ
6	SSR、RSC、サーバーサイド呼び出し	rsc-	プリフェッチとハイドレーション、QueryClient のライフタイム、caller の誤用
7	サブスクリプションとストリーミング	sub-	SSE を介した非同期ジェネレーター、認証、キープアライブ、バックログの競合

クイックリファレンス

1. React クライアントのインターフェース

• client-tanstack-integration — React のデータ取得には @trpc/tanstack-react-query を使用します。createTRPCReact は現在、従来型の方法です
• client-invalidate-with-query-filters — 新しいプロキシには useUtils() がありません。queryClient と pathFilter() / queryFilter() を使って無効化します
• client-derive-query-keys — 新しいプロキシには getQueryKey() がありません。キーは queryKey() / pathKey() / infiniteQueryKey() として取得します
• client-subscription-options — 新しいプロキシには .useSubscription() がありません。@trpc/tanstack-react-query の useSubscription に subscriptionOptions() を渡します

2. v10 → v11 の変更点

• mig-formdata-is-native — 6つの experimental_* アップロード API がすべて削除され、FormData は splitLink の背後でネイティブ入力として扱われます
• mig-renamed-type-exports — AnyRouter → AnyTRPCRouter などに変更されました。inferRouterInputs／Outputs は変更されていません
• mig-await-get-raw-input — rawInput は undefined です。入力は遅延評価されるため、await getRawInput() を使用します
• mig-typescript-version-floor — TS >=5.7.2 が必要です。また、異なる TS バージョンを使うエディターでは、すべてが暗黙に any として型付けされます

3. ルーターとプロシージャの構築

• proc-narrow-ctx-in-middleware — 引数なしの next() では ctx.user が nullable のままになるため、! でガードの型が取り除かれます
• proc-input-before-use — .input() より前に .use() を指定すると、未検証の入力に対してミドルウェアが実行されます
• proc-single-trpc-instance — アプリごとに initTRPC.create() は1つだけにします。インスタンスが一致しないと、実行時に mergeRouters がエラーをスローします
• proc-merge-only-object-inputs — マージされるのはオブジェクトスキーマだけです。それ以外は、前のパーサーをエラーなく置き換えます
• proc-concat-over-standalone-middleware — experimental_standaloneMiddleware は非推奨で、.input() を宣言できません。.concat() を使用します

4. エラーと検証のセマンティクス

• err-format-standard-schema-issues — パーサーのディスパッチは順序付きのため、Zod 専用の errorFormatter は Valibot／Effect（StandardSchemaV1Error）および ArkType（ArkErrors）に対して null を返します
• err-output-strips-fields — .output() が返すのはパース済みの値なので、不明なキーは取り除かれます。失敗時のステータスは4xxではなく500です
• err-nullish-cursor — .optional() のカーソルは invalidate の後にのみ400を返します。.nullish() を使用します
• err-set-isdev-explicitly — isDev を明示的に指定しないと、エッジランタイムでは error.data.stack がすべてのクライアントに送信されます

5. リンク、トランスポート、シリアライズ

• link-transformer-on-terminating-links — トランスフォーマーはリンク内に移動しました。ブランド型のエラーを解消するために削除すると、実行時に Date が正しく動作しなくなります
• link-route-subscriptions-separately — httpBatchLink はサブスクリプション操作を明示的に拒否します
• link-cap-batch-size — maxItems と maxURLLength のデフォルトは Infinity です。サーバーの maxBatchSize と併用します
• link-gate-cache-headers — バッチ処理と一律の responseMeta キャッシュを併用すると、CDN があるユーザーのデータを別のユーザーに配信する可能性があります
• link-default-to-httpbatchlink — httpBatchStreamLink はストリーミング開始後にレスポンスヘッダーを設定できないため、デフォルトではありません
• link-read-batch-headers-from-oplist — バッチリンクが渡すのは { opList } であり、{ op } ではありません。誤った分割代入をすると、すべてのリクエストが401になります
• link-scope-body-parsers — グローバルな express.json() は、tRPC が読み取る前にストリームを消費します
• link-endpoint-matches-mount-path — endpoint は tRPC が取り除くプレフィックスです。一致しないと、すべてのプロシージャが404になります

6. SSR、RSC、サーバーサイド呼び出し

• rsc-query-client-per-request — モジュールスコープの QueryClient を使うと、あるユーザーのキャッシュが次のリクエストに引き継がれます
• rsc-dehydrate-pending-queries — pending のオーバーライドがないと、void prefetchQuery の結果がクライアントに届きません
• rsc-prefetch-through-options-proxy — 呼び出し元の結果がキャッシュに入らないため、クライアントがすべて再取得します
• rsc-share-logic-not-callers — ネストされた呼び出し元がコンテキストを再作成し、ミドルウェアチェーン全体を再実行します

7. サブスクリプションとストリーミング

• sub-write-async-generators — observable() は非推奨で削除予定です。また、tracked() による再接続と再開に対応するのはジェネレーターだけです
• sub-keep-credentials-out-of-urls — connectionParams はトークンをクエリ文字列にシリアライズするため、その情報を含むすべてのログにも記録されます
• sub-enable-sse-keepalive — ping.enabled はデフォルトで false のため、アイドル状態の SSE ストリームはプロキシによって破棄され、不安定なネットワークとして扱われます
• sub-attach-listener-before-backlog — リスナーをアタッチする前に履歴を取得すると、本番環境の負荷がある場合に限ってイベントが失われます

使い方

該当する判断が必要になったら、リファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示し、標準的な方法を説明します。誤った方法が実際の落とし穴になる場合にのみ、誤りと正解を対比しています。

先に確認しておくと役立つショートカットが2つあります。

• 既存の tRPC コードをレビューまたは移行していますか？ client- と mig- から始めてください。古いコードはコンパイルが通ることも多いため、これらの問題に気づく手がかりがありません。他のすべてが引き継ぐのは、まさにこれらのルールです。

• すでに動作しているものの堅牢性を高めたいですか？ セキュリティに関わるルールは、link-gate-cache-headers、rsc-query-client-per-request、err-set-isdev-explicitly、proc-input-before-use、sub-keep-credentials-out-of-urls です。

• セクションの定義 — カテゴリ構成と順序の根拠

• ルールのテンプレート — 新しいルールを追加するためのテンプレート

• AGENTS.md — すべてのルールを含む自動生成の目次

関連スキル

• tanstack-query — tRPC の React クライアントが現在委譲しているクエリレイヤーです。このスキルが前提とするキャッシュのセマンティクスを担います
• zod — バリデーターの作成と Zod 4 への移行差分を扱います。このスキルでは変更先を示すだけの .flatten() から z.treeifyError() への変更も含みます
• typescript — tRPC の型推論の範囲を超える、一般的な型レベルの作業