tRPCが解決する問題

TypeScript で REST API を構築すると、レスポンスの形式はサーバー側で定義されます。クライアント側では、それに一致する TypeScript の型を手動で作成する必要があります。API の進化に伴ってこれらの型は時間とともにずれていきますが、型が別々のパッケージで定義されているため、コンパイラーは不一致を検出できません。

サーバー側でフィールド名を変更しても、クライアント側では実行時まで気付けないバグになります。

GraphQL は、graphql-codegen のようなツールを使ってスキーマから TypeScript の型を生成することで、型のずれを解決します。これはうまく機能しますが、別のクエリ言語（GraphQL SDL）、ビルドパイプラインでのコード生成ステップ、スキーマ管理ツールなどの複雑さが加わります。

すでに GraphQL を導入しているチームにとっては、codegen が適切な解決策です。GraphQL のオーバーヘッドなしで型安全性を確保したいチームには、tRPC という選択肢があります。

tRPC のアプローチは非常にシンプルです。サーバー上で API のプロシージャを TypeScript 関数として定義し、ルーターの型をエクスポートして、その型をクライアントにインポートします。コード生成は不要で、別のスキーマ言語も必要ありません。

クライアントとサーバー間の契約は、TypeScript コンパイラー自体によってビルド時に強制されます。

tRPC では、TypeScript のインポートを通じてサーバーとクライアントで型を共有する必要があります。これは、サーバーとクライアントが相互にインポートできる別々のパッケージとして存在するモノレポ（Turborepo、Nx、pnpm workspaces）で自然に機能します。

バックエンドとフロントエンドが完全に分離されている場合は、ルーターの型を共有パッケージとして公開する必要があります。そのため公開のステップが追加されますが、コード生成は不要です。

サーバーでは、ルーターを定義してその型をエクスポートします。例: export type AppRouter = typeof appRouter。クライアントでは、その型をインポートして、型付けされたクライアントを作成します。例: createTRPCReact()。クライアントは、存在するプロシージャと、それぞれの入力型および出力型を正確に把握できます。

サーバー上のプロシージャ名を変更すると、クライアント側ですぐに TypeScript エラーが表示されます。

tRPC は TypeScript の型システムを直接利用するため、エディターはクライアント側でプロシージャ名、入力形式、戻り値の型を完全に自動補完できます。プロシージャ名の変更は、コードベース全体に対する手動の検索・置換ではなく、TypeScript の名前変更リファクタリングになります。

この開発者体験の向上は、実際の利用において tRPC が最も高く評価されている特徴です。

デフォルトでは、tRPC は HTTP をトランスポートとして使います。各プロシージャ呼び出しが HTTP リクエストになります。tRPC はサブスクリプション用に WebSockets もサポートしています。トランスポートは実装の詳細であり、トランスポートの種類にかかわらずクライアント API は同じです。

互換性のない tRPC クライアントにも対応できるよう、REST adapter を使って tRPC プロシージャを従来の REST エンドポイントとして公開することもできます。

tRPC は Express、Fastify、Hono のミドルウェアとして機能します。Next.js では、API route handlers を通じて統合できます。create-t3-app starter（T3 Stack）は、tRPC、Prisma、NextAuth、Tailwind をフルスタックの Next.js テンプレートにまとめています。

T3 Stack は tRPC の出発点として最も人気があり、本番環境で利用できるパターンを示しています。

型安全な REST の別のアプローチとして、Zod スキーマを定義し、OpenAPI spec を自動生成して、その spec から TypeScript の型を生成する方法があります。これにより、TypeScript 以外のクライアントでも利用できる API 契約を提供できます。

tRPC はよりシンプルですが、TypeScript 専用です。OpenAPI+Zod は複雑さが増す一方で、公開 API の契約を生成できます。内部の TypeScript 間通信には tRPC を、公開 API には OpenAPI を選びます。

第三者が利用する公開 API、TypeScript で書かれていないモバイルクライアント、または安定したバージョン管理済みの契約を必要とするパートナー向けの API が必要な場合、tRPC は REST の代替にはなりません。tRPC は、フルスタックで型安全性を確保する TypeScript モノレポ向けの仕組みです。

この適用範囲を理解しておくと、REST や GraphQL の方が適している状況で tRPC を導入するのを避けられます。

npm create t3-app@latest を実行すると、tRPC、Prisma、NextAuth.js、Tailwind CSS、TypeScript があらかじめ設定された Next.js プロジェクトがスキャフォールドされます。生成されたコードでは、ルーターの構成、コンテキストの作成、クライアントのセットアップが示されています。

このスキャフォールドを学ぶことが、実際のアプリケーションで tRPC の各要素がどのように連携するかを理解する最短の方法です。

コード生成を行わずに、tRPC はどのようにサーバーとクライアントの間で型を共有するのでしょうか。

tRPC は、ルーターの TypeScript 型を import で直接共有することで、TypeScript のクライアントとサーバー間の型の乖離を解消し、コード生成を不要にします。モノレポで利用でき、Next.js、Express、Fastify、Hono と統合できます。T3 Stack（create-t3-app）は、標準的な本番用スターターです。

tRPC は TypeScript 専用であり、公開 API ではなく、内部向けのフルスタックアプリケーションに最適です。