Integrating tRPC with React Query and Auth

The tRPC context is an object created fresh for every request by the createTRPCContext function. It can contain the database client, the authenticated session, the request headers, or any per-request data your procedures need.

Context creation runs before any procedure, making it the right place for authentication and database connection setup.

In createTRPCContext, call getServerSession(authOptions) from next-auth/next. Attach the result to the context object: return { session: await getServerSession(authOptions), db }. All procedures now have access to ctx.session.

If session is null, the user is unauthenticated. Procedures can check this to conditionally return data or throw an error.

Define a middleware that checks ctx.session: const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); }).

The next() call passes the narrowed context (non-null session) to subsequent middlewares and the procedure handler.

Compose the middleware with publicProcedure: const protectedProcedure = publicProcedure.use(isAuthenticated). Now any handler defined with protectedProcedure.query() or protectedProcedure.mutation() automatically has a non-null session in ctx.

TypeScript infers that ctx.session is non-null inside protected procedures because the middleware would have thrown before reaching the handler.

Replace publicProcedure with protectedProcedure for endpoints that require authentication: protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id)). TypeScript knows ctx.session is non-null here, so accessing ctx.session.user.id is safe without a null check.

Unauthenticated requests automatically receive a 401 UNAUTHORIZED response before the handler executes.

Pass a headers function to httpBatchLink: links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. The function runs before every batch of requests.

This is used when authenticating tRPC from a React Native client or any non-Next.js client that manages its own auth tokens.

For SSR in the Next.js Pages Router, create a server-side helper: createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) }). Use helpers.post.getAll.prefetch() in getServerSideProps.

Dehydrate the prefetched state with dehydrate(queryClient) and pass it as props. On the client, the QueryClient hydrates from this state, avoiding the first-load refetch.

Wrap your Next.js _app.tsx with Hydrate from @tanstack/react-query. Pass pageProps.trpcState to the state prop. This restores the prefetched query cache on the client from the serialized server state.

With this setup, users see fully populated pages immediately without client-side loading spinners on initial navigation.

Throw TRPCError with appropriate HTTP-semantic codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500). The tRPC client maps these to appropriate error states in the hook result.

The message field can contain user-facing details, but avoid leaking sensitive server information in production error messages.

tRPC works with React Native clients using the same AppRouter type. Replace httpBatchLink with an httpLink (RN fetch works the same) and configure authentication headers. The @trpc/react-query adapter works identically to the web setup.

This means a monorepo can share one tRPC router between a Next.js web app and an Expo React Native app, with full type safety on both.

Extend the middleware pattern for role-based access: check ctx.session.user.role and throw TRPCError({ code: 'FORBIDDEN' }) if the role is insufficient. Create adminProcedure = publicProcedure.use(isAdmin) for admin-only endpoints.

Stack multiple middlewares for complex authorization: publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...).

How is a protected procedure created in tRPC to enforce authentication?

tRPC context is created per-request and holds the session, database client, and other request-scoped data. Protected procedures are created by composing a session-checking middleware onto publicProcedure with .use(). Server-side rendering uses createServerSideHelpers for prefetching and Hydrate for cache restoration on the client.

Auth headers for non-Next.js clients are passed via the headers option on httpBatchLink.