ReactとNext.jsでのtRPCセットアップ

コアの tRPC パッケージとして @trpc/server と @trpc/client をインストールします。React hooks アダプターとして @trpc/react-query を追加し、hooks の基盤となる peer dependency として @tanstack/react-query も追加します。

Next.js の API ルートと統合する場合、最近の tRPC のバージョンでは追加のアダプターパッケージは必要ありません。

server/trpc.ts ファイルを作成し、initTRPC.create() を呼び出して t オブジェクトを取得します。t.router を router として、t.procedure を publicProcedure として、t.mergeRouters をユーティリティとしてエクスポートします。

initTRPC ファクトリは、すべてのプロシージャの ctx 引数で利用できるデータを定義するコンテキスト型のジェネリックを受け取ります。

プロシージャは、publicProcedure に .input(zodSchema).query(handler) または .mutation(handler) を連結して定義します。単純な hello エンドポイントは、publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name) のように定義できます。

Zod スキーマは、入力に対する TypeScript の型と実行時検証の両方を提供します。

router() 関数を使って appRouter を作成します: router({ hello: helloHandler, users: usersRouter })。ネストされたルーターを使うと、プロシージャをドメイン（users、posts、comments）ごとに別のファイルへ整理できます。

AppRouter 型をエクスポートします: export type AppRouter = typeof appRouter。この型をクライアントが import します。

app/api/trpc/[trpc]/route.ts（App Router）または pages/api/trpc/[trpc].ts（Pages Router）を作成します。@trpc/server/adapters/fetch の fetchRequestHandler を使い、この単一のキャッチオールルートですべての tRPC リクエストを処理します。

ルーター、createContext 関数、リクエストとレスポンスのオブジェクトを fetchRequestHandler に渡します。

utils/trpc.ts ファイルを作成します。createTRPCReact<AppRouter>() を呼び出して、型付けされた trpc クライアントオブジェクトを作成します。このオブジェクトにはルーター内の各プロシージャに対応するプロパティがあり、それぞれが React Query の hooks を提供します。

AppRouter 型はサーバーファイルから import します。TypeScript は import の連鎖をたどって、すべての使用箇所を検証します。

アプリのレイアウトまたは _app.tsx で、QueryClient インスタンスと、trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] }) を使った tRPC クライアントインスタンスを作成します。

コンポーネントツリーを trpc.Provider（tRPC クライアントを指定）と QueryClientProvider（QueryClient を指定）の両方でラップします。両方のプロバイダーが必要です。

任意のコンポーネントで、const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' }) を実行します。この hook には完全な型情報があり、data は hello プロシージャから推論された戻り値の型になり、入力オブジェクトは Zod スキーマに対して型チェックされます。

誤った入力型を渡すと、実行時エラーではなく TypeScript のコンパイルエラーになります。

tRPC を動作させるには、クライアントがサーバーファイルから型を import できなければなりません。Next.js プロジェクトでは、サーバーコードとクライアントコードが同じ TypeScript コンパイルの対象になるため、import するだけで機能します。

パッケージが分かれているモノレポでは、tsconfig.json で TypeScript のプロジェクト参照またはパスエイリアスを設定し、サーバーパッケージを参照するようにします。

tRPC ハンドラーはサーバー上で実行されます（Next.js の API ルートまたは Edge Function として実行されます）。tRPC クライアントはブラウザー上で実行されます。TypeScript はビルド時に型レベルの import を評価するため、ブラウザーでサーバーコードが実行されることはありません。

クライアントで import されるのは AppRouter 型だけで、実際の実装ではありません。そのため、サーバーの秘密情報がクライアントバンドルに漏れることはありません。

Next.js の開発サーバーを起動し、ブラウザーのコンソールを開きます。trpc.hello.useQuery の呼び出しによって、サーバーのレスポンスがログに出力されるはずです。Network タブを確認すると、入力がクエリパラメーターとしてまとめられた /api/trpc/hello への HTTP リクエストを確認できます。

デフォルトの httpBatchLink は、同時に発生した複数のリクエストを 1 つの HTTP 呼び出しにまとめます。これはネットワークウォーターフォールで確認できます。

tRPC インスタンスを初期化し、ルーターとプロシージャのファクトリを提供する関数はどれでしょうか。

@trpc/server、@trpc/client、@trpc/react-query、@tanstack/react-query をインストールします。initTRPC.create() で tRPC を初期化し、プロシージャを定義して、AppRouter 型をエクスポートします。Next.js の API キャッチオールルートを作成し、TRPCProvider と QueryClientProvider をセットアップしてから、trpc.procedureName.useQuery() でプロシージャを呼び出します。

TypeScript はコード生成なしで、クライアントとサーバー間の完全な契約をコンパイル時に適用します。