tRPC 11 Setup for Next.js App router 2025

Simple, up-to-date, copy-paste setup guide for your Next.js App Router + tRPC setup.

Usage:

Client

Using the tRPC v11 client with the new syntax.

"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>;
}

Prefetch on server-side

Prefetch on the server side to get faster loads.

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>
  );
}

Use await instead of void if you want to completely avoid streaming and client-side loading.

Setup

Folder structure:

You may use a src folder if needed.

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

I like to consolidate everything into one tRPC folder for both front and backend. This makes tRPC config easy to manage.

Please setup Next.js if you haven’t already.

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

1. Install deps

Use pnpm or use your package manager of choice

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

tsconfig.json

Make sure strict mode is set to true in tsconfig

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

1. /trpc/query-client.ts

The TanStack Query Client setup. Superjson is optional but highly recommended for being able to send instances such as the Date object between front & backend.

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,
      },
    },
  });
}

2. /trpc/init.ts

This is where you define your base tRPC procedures, middleware, and context. Use your auth of choice.

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,
    },
  });
});

3. /trpc/router.ts

This is where you customize your trpc routers for your use-case.

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;

4. /trpc/server.tsx

This is new with tRPC v11 that enables prefetching on the server-side.

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);
  }
}

5. /trpc/utils.ts

Exports the React provider and hooks with the correct types.

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

6. /trpc/client.tsx

Create the React provider that will be used by your app, integrating TanStack Query & tRPC.

"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>
  );
}

7. Mount your tRPC api endpoint at /app/api/trpc/[trpc]/route.ts

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 };

8. App router root layout /app/layout.tsx

Finally, wrap your app with the QueryProvider.

// /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>
  );
}