Next.js Integration

tRPC + Next.js

Next.js makes it easy to build a client and server together in one codebase. tRPC makes it easy to share types between them, ensuring typesafety for your application's data fetching.

tRPC provides first-class support for both the App Router and the Pages Router. Choose the guide that matches your project:

App Router

The recommended approach for new Next.js projects. Uses React Server Components, the fetch adapter, and @trpc/tanstack-react-query.

Key features:

• Server Components - Prefetch data on the server and stream it to the client
• Streaming - Leverage Next.js streaming for optimal loading performance
• Suspense - Use useSuspenseQuery with Suspense boundaries for loading states

Get started with App Router →

Pages Router

Uses @trpc/next which provides a higher-order component (HOC) and integrated hooks for the Pages Router data-fetching patterns.

Key features:

• Server-side rendering - Render pages on the server and hydrate them on the client. Read more about SSR.
• Static site generation - Prefetch queries on the server and generate static HTML files. Read more about SSG.
• Automatic Provider Wrapping - @trpc/next provides a HOC that wraps your app with the necessary providers automatically.

Get started with Pages Router →

Choosing between App Router and Pages Router

	App Router	Pages Router
Recommended for	New projects	Existing Pages Router projects
Data fetching	Server Components, prefetchQuery	getServerSideProps, getStaticProps, SSR via HOC
Server adapter	Fetch adapter	Next.js adapter
Client package	@trpc/tanstack-react-query	@trpc/next + @trpc/react-query
Provider setup	Manual QueryClientProvider + TRPCProvider	Automatic via withTRPC() HOC

:::tip If you're starting a new project, we recommend the App Router. If you have an existing Pages Router project, the Pages Router integration works well and is fully supported. :::