This skill builds on [server-setup], [client-setup], [react-query-setup], and [adapter-fetch]. Read them first for foundational concepts.
tRPC -- Next.js App Router
File Structure
.
├── app
│ ├── api/trpc/[trpc]
│ │ └── route.ts # tRPC HTTP handler
│ ├── layout.tsx # mount TRPCReactProvider
│ ├── page.tsx # server component (prefetch)
│ └── client-greeting.tsx # client component (consume)
├── trpc
│ ├── init.ts # initTRPC, createTRPCContext
│ ├── routers
│ │ └── _app.ts # main app router, AppRouter type
│ ├── query-client.ts # shared QueryClient factory
│ ├── client.tsx # client hooks & TRPCReactProvider
│ └── server.tsx # server-side proxy & helpers
└── ...Setup
1. Install
npm install @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query zod server-only client-only2. Server init and context
import { initTRPC } from '@trpc/server';
export const createTRPCContext = async (opts: { headers: Headers }) => {
return { userId: 'user_123' };
};
const t = initTRPC
.context<Awaited<ReturnType<typeof createTRPCContext>>>()
.create();
export const createTRPCRouter = t.router;
export const createCallerFactory = t.createCallerFactory;
export const baseProcedure = t.procedure;3. Define the router
import { z } from 'zod';
import { baseProcedure, createTRPCRouter } from '../init';
export const appRouter = createTRPCRouter({
hello: baseProcedure
.input(z.object({ text: z.string() }))
.query(({ input }) => ({
greeting: `hello ${input.text}`,
})),
});
export type AppRouter = typeof appRouter;4. Route handler (API endpoint)
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { createTRPCContext } from '../../../../trpc/init';
import { appRouter } from '../../../../trpc/routers/_app';
const handler = (req: Request) =>
fetchRequestHandler({
endpoint: '/api/trpc',
req,
router: appRouter,
createContext: () => createTRPCContext({ headers: req.headers }),
});
export { handler as GET, handler as POST };5. QueryClient factory
import {
defaultShouldDehydrateQuery,
QueryClient,
} from '@tanstack/react-query';
export function makeQueryClient() {
return new QueryClient({
defaultOptions: {
queries: {
staleTime: 30 * 1000,
},
dehydrate: {
shouldDehydrateQuery: (query) =>
defaultShouldDehydrateQuery(query) ||
query.state.status === 'pending',
},
},
});
}If using a data transformer (e.g., superjson), add dehydrate.serializeData and hydrate.deserializeData here.
6. Client provider (client component)
'use client';
import type { QueryClient } from '@tanstack/react-query';
import { QueryClientProvider } from '@tanstack/react-query';
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import { createTRPCContext } from '@trpc/tanstack-react-query';
import { useState } from 'react';
import { makeQueryClient } from './query-client';
import type { AppRouter } from './routers/_app';
export const { TRPCProvider, useTRPC, useTRPCClient } =
createTRPCContext<AppRouter>();
let browserQueryClient: QueryClient;
function getQueryClient() {
if (typeof window === 'undefined') {
return makeQueryClient();
}
if (!browserQueryClient) browserQueryClient = makeQueryClient();
return browserQueryClient;
}
function getUrl() {
const base = (() => {
if (typeof window !== 'undefined') return '';
if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
return 'http://localhost:3000';
})();
return `${base}/api/trpc`;
}
export function TRPCReactProvider(props: { children: React.ReactNode }) {
const queryClient = getQueryClient();
const [trpcClient] = useState(() =>
createTRPCClient<AppRouter>({
links: [
httpBatchLink({
url: getUrl(),
}),
],
}),
);
return (
<QueryClientProvider client={queryClient}>
<TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
{props.children}
</TRPCProvider>
</QueryClientProvider>
);
}7. Server-side proxy (server component)
import 'server-only';
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query';
import type { TRPCQueryOptions } from '@trpc/tanstack-react-query';
import { headers } from 'next/headers';
import { cache } from 'react';
import { createTRPCContext } from './init';
import { makeQueryClient } from './query-client';
import { appRouter } from './routers/_app';
export const getQueryClient = cache(makeQueryClient);
export const trpc = createTRPCOptionsProxy({
ctx: async () =>
createTRPCContext({
headers: await headers(),
}),
router: appRouter,
queryClient: getQueryClient,
});
export function HydrateClient(props: { children: React.ReactNode }) {
const queryClient = getQueryClient();
return (
<HydrationBoundary state={dehydrate(queryClient)}>
{props.children}
</HydrationBoundary>
);
}
export function prefetch<T extends ReturnType<TRPCQueryOptions<any>>>(
queryOptions: T,
) {
const queryClient = getQueryClient();
if (queryOptions.queryKey[1]?.type === 'infinite') {
void queryClient.prefetchInfiniteQuery(queryOptions as any);
} else {
void queryClient.prefetchQuery(queryOptions);
}
}8. Mount provider in layout
import { TRPCReactProvider } from '../trpc/client';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<TRPCReactProvider>{children}</TRPCReactProvider>
</body>
</html>
);
}Core Patterns
Prefetch in server component, consume in client component
import { HydrateClient, prefetch, trpc } from '../trpc/server';
import { ClientGreeting } from './client-greeting';
export default async function Home() {
prefetch(trpc.hello.queryOptions({ text: 'world' }));
return (
<HydrateClient>
<ClientGreeting />
</HydrateClient>
);
}'use client';
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from '../trpc/client';
export function ClientGreeting() {
const trpc = useTRPC();
const greeting = useQuery(trpc.hello.queryOptions({ text: 'world' }));
if (!greeting.data) return <div>Loading...</div>;
return <div>{greeting.data.greeting}</div>;
}Suspense with prefetch
import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import { HydrateClient, prefetch, trpc } from '../trpc/server';
import { ClientGreeting } from './client-greeting';
export default async function Home() {
prefetch(trpc.hello.queryOptions({ text: 'world' }));
return (
<HydrateClient>
<ErrorBoundary fallback={<div>Something went wrong</div>}>
<Suspense fallback={<div>Loading...</div>}>
<ClientGreeting />
</Suspense>
</ErrorBoundary>
</HydrateClient>
);
}'use client';
import { useSuspenseQuery } from '@tanstack/react-query';
import { useTRPC } from '../trpc/client';
export function ClientGreeting() {
const trpc = useTRPC();
const { data } = useSuspenseQuery(trpc.hello.queryOptions({ text: 'world' }));
return <div>{data.greeting}</div>;
}Direct server caller (data needed on server only)
// Add to existing server.tsx
export const caller = appRouter.createCaller(async () =>
createTRPCContext({ headers: await headers() }),
);import { caller } from '../trpc/server';
export default async function Home() {
const greeting = await caller.hello({ text: 'world' });
return <div>{greeting.greeting}</div>;
}Note: caller results are not stored in the query cache. They cannot hydrate to client components. Use prefetchQuery if client components also need the data.
fetchQuery for data on server AND client
import { getQueryClient, HydrateClient, trpc } from '../trpc/server';
import { ClientGreeting } from './client-greeting';
export default async function Home() {
const queryClient = getQueryClient();
const greeting = await queryClient.fetchQuery(
trpc.hello.queryOptions({ text: 'world' }),
);
// Use greeting on the server
console.log(greeting.greeting);
return (
<HydrateClient>
<ClientGreeting />
</HydrateClient>
);
}Common Mistakes
Not exporting both GET and POST from route handler
Next.js App Router route handlers must export named GET and POST functions. Missing either causes queries or mutations to return 405 Method Not Allowed.
// WRONG
export default function handler(req: Request) { ... }
// CORRECT
const handler = (req: Request) =>
fetchRequestHandler({ req, router: appRouter, endpoint: '/api/trpc', createContext });
export { handler as GET, handler as POST };Creating a singleton QueryClient for SSR
In server components, each request needs its own QueryClient instance. A singleton leaks data between requests.
// WRONG
const queryClient = new QueryClient(); // shared across requests!
// CORRECT
export const getQueryClient = cache(makeQueryClient);The cache() wrapper from React ensures the same QueryClient is reused within a single request but a new one is created for each new request.
Missing dehydrate/shouldDehydrateQuery config
RSC hydration requires shouldDehydrateQuery to include pending queries so that prefetched-but-not-yet-resolved promises can stream to the client. Without this, prefetched queries may not appear in the hydrated state.
// WRONG
new QueryClient(); // default shouldDehydrateQuery skips pending
// CORRECT
new QueryClient({
defaultOptions: {
dehydrate: {
shouldDehydrateQuery: (query) =>
defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
},
},
});Suspense query failure crashes entire page during SSR
If a query fails during SSR with useSuspenseQuery, the entire page crashes. Error Boundaries only catch errors on the client side. For critical pages, either handle errors server-side before rendering, or use useQuery (non-suspense) which allows graceful degradation.
See Also
- [react-query-setup] -- TanStack React Query setup, queryOptions/mutationOptions factories
- [adapter-fetch] -- fetchRequestHandler for edge/serverless runtimes
- [server-setup] -- initTRPC, routers, procedures, context
- [nextjs-pages-router] -- if maintaining a Pages Router project alongside App Router