trpc

tRPC

概要

tRPC は、コード生成やスキーマを使わずに、サーバーとクライアント間で TypeScript の型を共有することで、エンドツーエンドの型安全な API を実現します。サーバーはルーター内でプロシージャ（クエリ、ミューテーション、サブスクリプション）を定義し、クライアントはエクスポートされた AppRouter 型からすべての型を推論します。

使用する場合： 型安全な API レイヤーが必要な TypeScript のフルスタックアプリ、型を共有するモノレポ、リアルタイムサブスクリプション、OpenAPI／GraphQL のオーバーヘッドなしで API を迅速に反復開発する場合。

使用しない場合： TypeScript 以外のクライアントが利用する公開 API（REST／GraphQL を使用）、多言語バックエンド、OpenAPI 仕様の生成を主要な出力として必要とするプロジェクト。

クイックリファレンス

パターン	API	主なポイント
初期化	initTRPC.context<Ctx>().create()	単一のエントリーポイントで、一度だけ設定します
ルーター	t.router({ ... })	t.mergeRouters() でルーターをネストします
クエリ	t.procedure.input(schema).query(fn)	読み取り操作で、クライアントによってキャッシュされます
ミューテーション	t.procedure.input(schema).mutation(fn)	書き込み操作
サブスクリプション	t.procedure.subscription(fn)	WebSocket または SSE によるリアルタイム通信
ミドルウェア	t.middleware(fn)	.use() でチェーンし、next({ ctx }) でコンテキストを拡張します
スタンドアロンミドルウェア	experimental_standaloneMiddleware<{}>()	明示的な型制約を指定して再利用できます
コンテキスト	createContext({ req, res })	リクエストごとに作成され、すべてのプロシージャに渡されます
サーバー側コーラー	t.createCallerFactory(router)	型安全なサーバー側プロシージャ呼び出し
エラー	throw new TRPCError({ code, message })	HTTP ステータスコードにマッピングされます
エラーフォーマッター	initTRPC.create({ errorFormatter })	エラーの形状をカスタマイズし、Zod エラーを公開します
入力検証	.input(zodSchema)	複数の .input() 呼び出しはマージされます（共通部分）
出力検証	.output(zodSchema)	レスポンスから余分なフィールドを除外します
React フック	trpc.useQuery() / trpc.useMutation()	@tanstack/react-query を基盤としています
React ユーティリティ	trpc.useUtils()	キャッシュの無効化、プリフェッチ、setData を実行します
Suspense クエリ	trpc.useSuspenseQuery()	Suspense に対応したデータ取得
React サブスクリプション	trpc.useSubscription(input, opts)	リアルタイムイベント用の onData コールバック
Vanilla クライアント	createTRPCClient<AppRouter>({ links })	React への依存なし
バッチリンク	httpBatchLink({ url })	1 回の HTTP 呼び出しにリクエストをまとめます
ストリームリンク	httpBatchStreamLink({ url })	レスポンスを準備でき次第ストリーミングします
WS リンク	wsLink({ client: wsClient })	サブスクリプション用の WebSocket トランスポート
スプリットリンク	splitLink({ condition, true, false })	操作を異なるトランスポートに振り分けます
ロガーリンク	loggerLink()	開発環境でリクエスト／レスポンスをデバッグします
データトランスフォーマー	initTRPC.create({ transformer })	日付、Map、Set をシリアライズします（superjson）
Fetch アダプター	fetchRequestHandler({ endpoint, req })	Cloudflare Workers、Deno、Bun、Next.js
プロシージャのチェーン化	publicProcedure.use(auth).use(rateLimit)	再利用可能なプロシージャの基盤を構築します

よくある間違い

間違い	正しいパターン
t オブジェクト全体をエクスポートする	t.router、t.procedure、t.middleware、t.createCallerFactory のみをエクスポートする
プロシージャ内でコンテキストを作成する	アダプターのセットアップ時にコンテキストを作成します。自動的に受け渡されます
コンテキスト型に any を使用する	initTRPC.context<MyContext>().create() でコンテキスト型を定義する
プロシージャ内でエラーを捕捉する	エラーを伝播させます。アダプターの onError またはエラーフォーマッターを使用します
クライアントでサーバーコードをインポートする	type AppRouter のみをインポートし、実行時のサーバーコードはインポートしない
本番環境のリクエストハンドラーで createCaller を使用する	型安全で再利用可能な呼び出し元には createCallerFactory を使用する
検証せずに入力を定義する	常に Zod、Valibot、または ArkType のスキーマで検証する
ルーターを誤った方法でネストする	キーにはドット記法または t.mergeRouters() を使用し、深くネストしない
クライアントとサーバーで異なるトランスフォーマーを使用する	両側で同じトランスフォーマー（例：superjson）を使用する
コンポーネントのレンダー内で QueryClient を作成する	コンポーネントの外で一度だけ作成するか、useState の初期化関数を使用する
フックに TypeScript のジェネリクスを手動で指定する	ルーターのプロシージャに型を付け、クライアントには型推論を適用させる
queryFn の fetch に signal を渡さない	tRPC React が中断シグナルを自動的に処理します

インストール

pnpm add @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod

サブスクリプションには、ws（サーバー）を追加し、wsLink（クライアント）を設定します。SSE ベースのサブスクリプションには、代わりに httpBatchStreamLink を使用します。

委任

• プロシージャの検出：Explore エージェントを使用します
• ルーターアーキテクチャのレビュー：Task エージェントを使用します
• コードレビュー：code-reviewer エージェントに委任します

tanstack-query スキルが利用可能な場合は、クエリ／ミューテーションのキャッシュ、無効化、楽観的更新のパターンをこのスキルに委任します。 zod-validation スキルが利用可能な場合は、入力スキーマの設計と検証のパターンをこのスキルに委任します。 drizzle-orm スキルが利用可能な場合は、プロシージャ内のデータベースクエリのパターンをこのスキルに委任します。 vitest-testing スキルが利用可能な場合は、テストランナーの設定とアサーションのパターンをこのスキルに委任します。 hono スキルが利用可能な場合は、Hono フレームワークのルーティングとミドルウェアのパターンをこのスキルに委任します。

参考資料

• ルーターとプロシージャの定義
• ミドルウェアとコンテキストのパターン
• エラー処理とフォーマット
• @trpc/react-query を使った React クライアントの統合
• サーバーサイドの呼び出し元とバニラクライアント
• スタンドアロン、Express、Fastify、Hono 向けのアダプター設定
• サブスクリプションとリアルタイムのパターン
• tRPC プロシージャのテスト