Set up with Next.js Pages Router
On this page
The Pages Router uses the same client as the App Router: the TanStack React Query integration (@trpc/tanstack-react-query). You mount its provider in _app, and prefetch a page's queries in getServerSideProps or getStaticProps when you want them in the first HTML.
Recommended file structure
We recommend a file structure like this one, although it is not enforced by tRPC. The rest of this page will take you through the process of adding tRPC in to this structure.
.
├── prisma # <-- if prisma is added
│ └── [..]
├── src
│ ├── pages
│ │ ├── _app.tsx # <-- mount the providers here
│ │ ├── api
│ │ │ └── trpc
│ │ │ └── [trpc].ts # <-- tRPC HTTP handler
│ │ └── [..]
│ ├── server
│ │ ├── routers
│ │ │ ├── _app.ts # <-- main app router
│ │ │ ├── post.ts # <-- sub routers
│ │ │ └── [..]
│ │ ├── context.ts # <-- create app context
│ │ └── trpc.ts # <-- procedure helpers
│ └── utils
│ ├── query-client.ts # <-- shared QueryClient factory
│ └── trpc.ts # <-- your typesafe tRPC hooks
└── [..]Add tRPC to existing Next.js project
1. Install deps
pnpm add @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query@latest zodnpm install @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query@latest zodyarn add @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query@latest zodbun add @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query@latest zod2. Enable strict mode
If you want to use Zod for input validation, make sure you have enabled strict mode in your tsconfig.json:
"compilerOptions": {
+ "strict": true
}If strict mode is too harsh, you'll at least want to enable strictNullChecks:
"compilerOptions": {
+ "strictNullChecks": true
}3. Create a tRPC router
Initialize your tRPC backend in src/server/trpc.ts using the initTRPC function, and create your first router. We're going to make a simple "hello world" router and procedure here - but for deeper information on creating your tRPC API you should refer to:
- the Quickstart guide and Backend usage docs for tRPC information
- the Next.js Adapter docs for mounting tRPC within your Next.js server.
View sample backend
import { initTRPC } from '@trpc/server';
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;import { z } from 'zod';
import { procedure, router } from '../trpc';
export const appRouter = router({
hello: procedure
.input(
z.object({
text: z.string(),
}),
)
.query((opts) => {
return {
greeting: `hello ${opts.input.text}`,
};
}),
});
// export type definition of API
export type AppRouter = typeof appRouter;import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
// export API handler
// @link https://trpc.io/docs/server/adapters
export default trpcNext.createNextApiHandler({
router: appRouter,
createContext: () => ({}),
});4. Create a Query Client factory
Create utils/query-client.ts. Both _app and the pages that prefetch on the server use it.
import { QueryClient } from '@tanstack/react-query';
export function makeQueryClient() {
return new QueryClient({
defaultOptions: {
queries: {
// keep server-rendered data fresh for a while, so the
// client doesn't fetch it again as soon as the page loads
staleTime: 30 * 1000,
},
},
});
}5. Create tRPC hooks
Use createTRPCContext to create a provider and a useTRPC hook from your API's type signature.
import { createTRPCContext } from '@trpc/tanstack-react-query';
import type { AppRouter } from '../server/routers/_app';
export const { TRPCProvider, useTRPC } = createTRPCContext<AppRouter>();6. Configure _app.tsx
Create the query client and the tRPC client once per app, and wrap every page in the providers. HydrationBoundary puts the queries a page prefetched on the server, which it returns as trpcState, into the cache.
import type { DehydratedState } from '@tanstack/react-query';
import { HydrationBoundary, QueryClientProvider } from '@tanstack/react-query';
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppProps } from 'next/app';
import { useState } from 'react';
import type { AppRouter } from '../server/routers/_app';
import { makeQueryClient } from '../utils/query-client';
import { TRPCProvider } from '../utils/trpc';
export default function App({
Component,
pageProps,
}: AppProps<{ trpcState?: DehydratedState }>) {
const [queryClient] = useState(makeQueryClient);
const [trpcClient] = useState(() =>
createTRPCClient<AppRouter>({
links: [
httpBatchLink({
// transformer: superjson, <-- if you use a data transformer
url: '/api/trpc',
}),
],
}),
);
return (
<QueryClientProvider client={queryClient}>
<TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
<HydrationBoundary state={pageProps.trpcState}>
<Component {...pageProps} />
</HydrationBoundary>
</TRPCProvider>
</QueryClientProvider>
);
}The client only calls the API from the browser, so a relative URL is enough. On the server, pages call your procedures directly, as Server-Side Rendering shows.
7. Make an API request
You're all set! Get the options for a query from useTRPC(), and pass them to TanStack React Query's hooks. For more, see TanStack React Query usage.
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from '../utils/trpc';
export default function IndexPage() {
const trpc = useTRPC();
const helloQuery = useQuery(trpc.hello.queryOptions({ text: 'client' }));
switch (helloQuery.status) {
case 'pending':
return <p>Loading...</p>;
case 'error':
return <p>Error: {helloQuery.error.message}</p>;
case 'success':
return <p>{helloQuery.data.greeting}</p>;
}
}This page fetches in the browser. To put the data in the first HTML, prefetch it in getServerSideProps or getStaticProps.
Using a data transformer
Next.js sends page props as JSON, and checks that they are. So without a transformer, the queries you prefetch can only hold JSON values, in their inputs as well as their results: a Date or an undefined field makes getServerSideProps fail.
If your router uses a data transformer such as superjson, run the whole prefetched cache through it. In getServerSideProps or getStaticProps, return trpcState: superjson.serialize(dehydrate(queryClient)), as the SSG example does. Then read it back with a hook:
import type { DehydratedState } from '@tanstack/react-query';
import { useMemo } from 'react';
import superjson from 'superjson';
export type TRPCState = ReturnType<typeof superjson.serialize>;
export function useTRPCState(trpcState: TRPCState | undefined) {
return useMemo(
() => trpcState && superjson.deserialize<DehydratedState>(trpcState),
[trpcState],
);
}In the _app from step 6, change three things:
- Type the props as
AppProps<{ trpcState?: TRPCState }>. - Pass
transformer: superjsontohttpBatchLink. - Call
const trpcState = useTRPCState(pageProps.trpcState), and passtrpcStatetoHydrationBoundaryinstead ofpageProps.trpcState.
Moving from createTRPCNext
createTRPCNext combined the classic React Query hooks with a higher-order component for _app. Here's what replaces each part:
@trpc/next | @trpc/tanstack-react-query |
|---|---|
createTRPCNext<AppRouter>({ config }) | createTRPCContext<AppRouter>(), plus a createTRPCClient with your links in _app |
trpc.withTRPC(MyApp) | QueryClientProvider, TRPCProvider and HydrationBoundary in _app, as in step 6 |
trpc.post.byId.useQuery(input) | useQuery(trpc.post.byId.queryOptions(input)), with trpc from useTRPC() |
trpc.useUtils() | useQueryClient() with trpc.post.byId.queryKey() or queryFilter() |
ssr: true and ssrPrepass | No direct replacement. Prefetch each page's queries in getServerSideProps |
responseMeta | Set the status and headers in getServerSideProps |
config({ ctx }) forwarding the request headers | Pass a context built from context.req to createTRPCOptionsProxy in getServerSideProps |
createServerSideHelpers (@trpc/react-query/server) | createTRPCOptionsProxy with a query client, then dehydrate(queryClient). See Server-Side Helpers |
abortOnUnmount in config | trpc: { abortOnUnmount: true } on each query. See Aborting Procedure Calls |
queryClientConfig | The options you pass to new QueryClient() in makeQueryClient |
The migration guide covers the hooks in detail, and has a codemod for them that's still a work in progress.
ssr: true rendered the page over and over until no query was fetching. With getServerSideProps, you pick which queries run on the server, and Next.js keeps Automatic Static Optimization for pages that don't need them.
Common mistakes
- Sharing one
QueryClientacross requests. Make it in_appwithuseState, and make a new one in eachgetServerSidePropsorgetStaticProps. A query client at module scope would hand one user's data to the next. - Returning the dehydrated state under another key.
_appreadspageProps.trpcState, so return{ props: { trpcState: dehydrate(queryClient) } }. Otherwise the client fetches every query again. - Prefetching with a different input than the page uses. The input is part of the query key, so the page misses the prefetched data and fetches again.
- Prefetching values JSON can't hold. Next.js sends page props as JSON, so a
Dateor anundefinedfield in a query's input or result makes the page fail. Run the prefetched cache through a data transformer. - Mixing in App Router setup.
HydrateClientandserver-onlyare for the App Router. In the Pages Router, prefetch ingetServerSidePropsorgetStaticPropsinstead.
Next steps
Browse the rest of the docs to learn more about things like authorization, middlewares, and error handling.
You can also find information about queries, mutations and invalidation in the TanStack React Query docs.
Pages under Pages Router
- Server-Side Rendering (SSR)Prefetch a page's tRPC queries in getServerSideProps with createTRPCOptionsProxy, build the context from the request, and set the status and cache headers
- Static Site Generation (SSG)Prefetch tRPC queries in getStaticProps with createTRPCOptionsProxy and dehydrate, and stop the client from refetching them
- Server-Side HelpersPrefetch or fetch tRPC queries in getServerSideProps and getStaticProps with createTRPCOptionsProxy and a query client, then pass them to the page as trpcState
- Aborting Procedure CallsCancel in-flight requests when a component unmounts with the abortOnUnmount option on a query