tRPC と React Query、認証を統合する

tRPC コンテキストは、createTRPCContext 関数によってリクエストごとに新しく作成されるオブジェクトです。データベースクライアント、認証済みセッション、リクエストヘッダー、その他プロシージャが必要とするリクエスト単位のデータを含めることができます。

コンテキストの作成はすべてのプロシージャより前に実行されるため、認証やデータベース接続のセットアップに適しています。

createTRPCContext 内で、next-auth/next の getServerSession(authOptions) を呼び出します。その結果をコンテキストオブジェクトに追加します。return { session: await getServerSession(authOptions), db }. これで、すべてのプロシージャから ctx.session にアクセスできるようになります。

session が null の場合、ユーザーは認証されていません。プロシージャはこれを確認して、条件に応じてデータを返すか、エラーをスローできます。

ctx.session を確認するミドルウェアを定義します。const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

next() の呼び出しは、絞り込まれたコンテキスト（null ではないセッション）を後続のミドルウェアとプロシージャハンドラーに渡します。

ミドルウェアを publicProcedure と組み合わせます。const protectedProcedure = publicProcedure.use(isAuthenticated). これで、protectedProcedure.query() または protectedProcedure.mutation() で定義したすべてのハンドラーは、ctx 内に null ではないセッションを自動的に持つようになります。

ミドルウェアはハンドラーに到達する前にエラーをスローするため、TypeScript は保護されたプロシージャ内で ctx.session が null ではないと推論します。

認証が必要なエンドポイントでは、publicProcedure を protectedProcedure に置き換えます。protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). この場合、TypeScript は ctx.session が null ではないことを認識するため、null チェックなしで ctx.session.user.id に安全にアクセスできます。

認証されていないリクエストには、ハンドラーが実行される前に 401 UNAUTHORIZED レスポンスが自動的に返されます。

httpBatchLink に headers 関数を渡します。links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. この関数は、リクエストの各バッチの前に実行されます。

これは、React Native クライアントや、独自に認証トークンを管理する Next.js 以外のクライアントから tRPC を認証するときに使用します。

Next.js Pages Router で SSR を行うには、サーバーサイドヘルパーを作成します。createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). getServerSideProps 内で helpers.post.getAll.prefetch() を使用します。

dehydrate(queryClient) で事前取得した状態をデハイドレートし、props として渡します。クライアントでは QueryClient がこの状態からハイドレートされるため、初回読み込み時の再取得を回避できます。

Next.js の _app.tsx を @tanstack/react-query の Hydrate でラップします。pageProps.trpcState を state prop に渡します。これにより、シリアライズされたサーバーの状態から、クライアント上の事前取得済みクエリキャッシュが復元されます。

この構成では、初回のページ遷移でクライアント側のローディングスピナーを表示することなく、ユーザーにデータが完全に表示されたページをすぐに見せられます。

適切な HTTP セマンティクスに対応するコードを指定して TRPCError をスローします。UNAUTHORIZED（401）、FORBIDDEN（403）、NOT_FOUND（404）、BAD_REQUEST（400）、INTERNAL_SERVER_ERROR（500）などです。tRPC クライアントは、これらをフックの結果における適切なエラー状態へマッピングします。

message フィールドにはユーザー向けの詳細を含められますが、本番環境のエラーメッセージで機密性の高いサーバー情報を漏らさないようにしてください。

tRPC は同じ AppRouter 型を使用して React Native クライアントでも動作します。httpBatchLink を httpLink に置き換え、認証ヘッダーを設定します（RN の fetch も同じように動作します）。@trpc/react-query アダプターは Web の構成と同じように動作します。

つまり、モノレポでは Next.js の Web アプリと Expo React Native アプリの間で 1 つの tRPC ルーターを共有し、両方で完全な型安全性を確保できます。

ロールベースのアクセス制御には、ミドルウェアのパターンを拡張します。ctx.session.user.role を確認し、ロールが不十分な場合は TRPCError({ code: 'FORBIDDEN' }) をスローします。管理者専用のエンドポイントには、adminProcedure = publicProcedure.use(isAdmin) を作成します。

複雑な認可には、複数のミドルウェアを積み重ねます。publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...) のように記述します。

認証を強制するための保護されたプロシージャは、tRPC でどのように作成しますか？

tRPC コンテキストはリクエストごとに作成され、セッション、データベースクライアント、その他のリクエスト単位のデータを保持します。保護されたプロシージャは、セッションを確認するミドルウェアを .use() で publicProcedure に組み合わせて作成します。サーバーサイドレンダリングでは、事前取得に createServerSideHelpers を使用し、クライアント側のキャッシュ復元には Hydrate を使用します。

Next.js 以外のクライアントの認証ヘッダーは、httpBatchLink の headers オプションで渡します。