2025年にNext.jsアプリケーションにtRPC + TanStack Queryを導入した話【株式会社ライトコード】

はじめに

Next.js App Routerで React Server Componentや Server Functionが導入されましたが、クライアントサイドからデータを取得したい場面ではあまり向いておらず、従来のAjaxで対応した方が望ましいケースがあります。

担当しているNext.jsプロジェクトでは、そのようなケースを以下のような構成で実装していました:

API Routesによる REST API 作成
クライアントコンポーネントにてuseEffect + axiosによるデータ取得

この構成にはいくつかの課題がありました:

従来の実装における課題

型安全性の欠如: フロントエンドとバックエンドで型定義を手動で同期する必要がある
ボイラープレートコードの増加: 各API Route実装、axiosによる呼び出し関数の実装など手間がかかる
useEffectの落とし穴: race condition未対応, cleanup関数不在などの実装の漏れが多数

これらの課題を解決するため、tRPC + TanStack Queryを導入し、いくつかのユースケースに適用しました。本記事では、ライブラリ選定の経緯と具体的な例を紹介します。

ライブラリ選定の背景

今回の技術選定では、以下の3点を重視しました：

導入の容易さ: 既存のNext.jsプロジェクトに最小限のコストで導入できること
TypeScript特化: サーバークライアント両方TypeScriptであり、汎用的なrpcやGraphQLなどは不要
コミュニティの規模: ドキュメントが充実しており、開発が活発で、トラブルシューティングが容易であること

検討した選択肢

RPC層

TypeScript環境での型安全な通信を実現するため、以下のライブラリを比較検討しました：

tRPC: この3つの中でダウンロード数が最も多く、T3 Stackを参考に導入しやすいそう
@effect/rpc: 関数型プログラミングのパラダイムを取り入れており強力そうだが、導入のハードルが高そう
oRPC: 新興ライブラリで利用者数はまだ少ないが、tRPCとAPI設計が似ているため、まずはtRPCを採用し、移行検討でも良さそう

データフェッチング層TanStack Query

Webアプリケーションでサーバー状態を取得、キャッシュ、同期、更新するライブラリです。この系のライブラリでは最も人気のある1つで、以下のような感じで使用します。

const { data } = useQuery({

  queryKey: ['post', postId],

  queryFn: () => fetch(`/api/post?id=${postId}`).then((res) => res.json()),

  enabled: shouldFetch,

  refetchInterval: 10_000,

})

tRPCの公式integrationでは以下のように使用します. oRPCにも類似なintegrationが用意されています.

const { data } = useQuery(

  trpc.post.get.queryOptions({

    id: postId

  }, {

    enabled: shouldFetch,

    refetchInterval: 10_000,

  })

)

SWR

vercelが開発しているデータ取得ライブラリです。以下のような感じで使用します。

const { data } = useSWR(

  shouldFetch ? `/api/post?id=${postId}` : null,

  (url) => fetch(url).then((res) => res.json()),

  { refreshInterval: 10_000 },

)

特徴として、useSWR の第2引数 fetcher は第1引数 key を受け取ってデータを取得する非同期関数です。RESTful APIやGraphQLなどのAPIサーバーと通信する場合は、fetcherを共通化することで簡潔に記述できます。しかし、tRPCなどのRPC層と組み合わせる場合、key の管理において型安全性を諦めて単なる文字列にするか、独自のレイヤーを構築するか、あるいはサードパーティ製のライブラリを導入する必要があると感じました。

一方、TanStack Queryは queryKey と queryFn が独立した設計になっています。RESTful APIなどでは情報の重複が冗長な気もしますが、tRPCやoRPCの統合環境ではキー管理が自動化されるため、その点は問題になりません。

選定

最終的には、tRPC + TanStack Query の組み合わせに決めました。

tRPCのエコシステムには「T3 Stack」という有名なテンプレートがあり、Next.js + tRPC + TanStack Query を組み合わせた構成をサクッと生成できます。tRPCのコアメンバーである Julius Marminge 氏が T3 Stack のメインテナーでもあることから、公式に近い「動く事例」を参考にできるのは大きな魅力です。断片的なコード例に頼るよりも、手軽に導入できると判断しました。