tRPC 11 Setup for Next.js App router 2025

"use client"; import { useTRPC } from "@/trpc/utils"; import { useQuery } from "@tanstack/react-query"; export function HelloClient() { const trpc = useTRPC(); // ↓↓↓↓↓ New Syntax! ↓↓↓↓↓ const { data, status } = useQuery(trpc.hello.queryOptions()); return <div>{status}: {data}</div>; } 

import { trpc, prefetch, HydrateClient } from "@/trpc/server"; import { HelloClient } from "./client"; export default async function Page() { void prefetch(trpc.hello.queryOptions()); return ( <HydrateClient> <HelloClient /> </HydrateClient> ); } 

/app ├── api │ └── trpc │ └── [trpc] │ └── route.ts ├── layout.tsx ├── page.tsx /trpc ├── client.tsx ├── init.ts ├── query-client.tsx ├── router.ts ├── server.tsx └── utils.ts 

pnpm create next-app@latest my-app --yes 

pnpm add @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query@latest zod client-only server-only superjson 

"compilerOptions": { "strict": true //... } 

import { defaultShouldDehydrateQuery, QueryClient, } from "@tanstack/react-query"; import superjson from "superjson"; export function makeQueryClient() { return new QueryClient({ defaultOptions: { queries: { staleTime: 30 * 1000, }, dehydrate: { serializeData: superjson.serialize, shouldDehydrateQuery: (query) => defaultShouldDehydrateQuery(query) || query.state.status === "pending", }, hydrate: { deserializeData: superjson.deserialize, }, }, }); } 

import { validateRequest } from "@/app/auth"; import { cache } from "react"; import superjson from "superjson"; import { TRPCError, initTRPC } from "@trpc/server"; export const createTRPCContext = cache(async () => { /** * @see: https://trpc.io/docs/server/context */ // Your custom auth logic here const { session, user } = await validateRequest(); return { session, user, }; }); type Context = Awaited<ReturnType<typeof createTRPCContext>>; /** * Initialization of tRPC backend * Should be done only once per backend! */ const t = initTRPC.context<Context>().create({ transformer: superjson, }); /** * Export reusable router and procedure helpers * that can be used throughout the router */ export const router = t.router; export const publicProcedure = t.procedure; export const createCallerFactory = t.createCallerFactory; export const authenticatedProcedure = t.procedure.use(async (opts) => { if (!opts.ctx.user || !opts.ctx.session) { throw new TRPCError({ code: "UNAUTHORIZED", message: "Unauthorized", }); } return opts.next({ ctx: { user: opts.ctx.user, session: opts.ctx.user, }, }); }); 

import { publicProcedure, router } from "./init"; export const appRouter = router({ hello: publicProcedure.query(async () => { await new Promise((resolve) => setTimeout(resolve, 500)); return "Hello World"; }), }); // Export type router type signature, // NOT the router itself. export type AppRouter = typeof appRouter; 

import "server-only"; // <-- ensure this file cannot be imported from the client import { createTRPCOptionsProxy, TRPCQueryOptions, } from "@trpc/tanstack-react-query"; import { dehydrate, HydrationBoundary } from "@tanstack/react-query"; import { cache } from "react"; import { createTRPCContext } from "./init"; import { makeQueryClient } from "./query-client"; import { appRouter } from "./router"; // IMPORTANT: Create a stable getter for the query client that // will return the same client during the same request. export const getQueryClient = cache(makeQueryClient); export const trpc = createTRPCOptionsProxy({ ctx: createTRPCContext, router: appRouter, queryClient: getQueryClient, }); // Optional: Prefetch helper function export function HydrateClient(props: { children: React.ReactNode }) { const queryClient = getQueryClient(); return ( <HydrationBoundary state={dehydrate(queryClient)}> {props.children} </HydrationBoundary> ); } // Optional: Prefetch helper function // eslint-disable-next-line @typescript-eslint/no-explicit-any export function prefetch<T extends ReturnType<TRPCQueryOptions<any>>>( queryOptions: T ) { const queryClient = getQueryClient(); if (queryOptions.queryKey[1]?.type === "infinite") { // eslint-disable-next-line @typescript-eslint/no-explicit-any void queryClient.prefetchInfiniteQuery(queryOptions as any); } else { void queryClient.prefetchQuery(queryOptions); } } 

import { createTRPCContext } from "@trpc/tanstack-react-query"; import type { AppRouter } from "./router"; export const { TRPCProvider, useTRPC, useTRPCClient } = createTRPCContext<AppRouter>(); 

"use client"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { createTRPCClient, httpBatchLink } from "@trpc/client"; import { useState } from "react"; import { TRPCProvider } from "./utils"; import { AppRouter } from "./router"; import superjson from "superjson"; import { makeQueryClient } from "./query-client"; function getBaseUrl() { if (typeof window !== "undefined") // browser should use relative path return ""; if (process.env.VERCEL_URL) // reference for vercel.com return `https://${process.env.VERCEL_URL}`; if (process.env.RENDER_INTERNAL_HOSTNAME) // reference for render.com return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`; // assume localhost return `http://localhost:${process.env.PORT ?? 3000}`; } let browserQueryClient: QueryClient | undefined = undefined; function getQueryClient() { if (typeof window === "undefined") { // Server: always make a new query client return makeQueryClient(); } else { // Browser: make a new query client if we don't already have one // This is very important, so we don't re-make a new client if React // suspends during the initial render. This may not be needed if we // have a suspense boundary BELOW the creation of the query client if (!browserQueryClient) browserQueryClient = makeQueryClient(); return browserQueryClient; } } export function QueryProvider({ children }: { children: React.ReactNode }) { const queryClient = getQueryClient(); const [trpcClient] = useState(() => createTRPCClient<AppRouter>({ links: [ httpBatchLink({ url: `${getBaseUrl()}/api/trpc`, transformer: superjson, }), ], }) ); return ( <QueryClientProvider client={queryClient}> <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}> {children} </TRPCProvider>  </QueryClientProvider>  ); } 

import { fetchRequestHandler } from "@trpc/server/adapters/fetch"; import { createTRPCContext } from "@/trpc/init"; import { appRouter } from "@/trpc/router"; const handler = (req: Request) => fetchRequestHandler({ endpoint: "/api/trpc", req, router: appRouter, createContext: createTRPCContext, }); export { handler as GET, handler as POST }; 

// /app/layout.tsx import { QueryProvider } from "@/trpc/client"; export default async function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( <html lang="en"> <body> <QueryProvider> {children} </QueryProvider> </body> </html> ); }