0
# Pages Router Integration
1

2
Core integration for Next.js Pages Router providing HOC wrapping and tRPC hook creation. Essential for traditional Next.js applications.
3

4
## Capabilities
5

6
### createTRPCNext Function
7

8
Creates a tRPC instance with React hooks and utilities for Next.js Pages Router.
9

10
```typescript { .api }
11
/**
12
 * Creates a tRPC instance with React hooks and utilities for Next.js Pages Router
13
 * @param opts - Configuration options for tRPC client and SSR behavior
14
 * @returns Object with tRPC hooks, utilities, and withTRPC HOC
15
 */
16
function createTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
17
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
18
): CreateTRPCNext<TRouter, TSSRContext>;
19

20
interface CreateTRPCNext<TRouter extends AnyRouter, TSSRContext extends NextPageContext> {
21
  /** @deprecated renamed to `useUtils` and will be removed in a future tRPC version */
22
  useContext(): CreateReactUtils<TRouter, TSSRContext>;
23
  /** Hook for accessing tRPC utilities like invalidateQueries, refetch, etc. */
24
  useUtils(): CreateReactUtils<TRouter, TSSRContext>;
25
  /** Higher-order component for wrapping Next.js apps/pages */
26
  withTRPC: ReturnType<typeof withTRPC<TRouter, TSSRContext>>;
27
  /** Hook for performing multiple queries in parallel */
28
  useQueries: TRPCUseQueries<TRouter>;
29
  /** Hook for performing multiple suspense queries in parallel */
30
  useSuspenseQueries: TRPCUseSuspenseQueries<TRouter>;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { createTRPCNext } from "@trpc/next";
38
import { httpBatchLink } from "@trpc/client";
39
import type { AppRouter } from "../pages/api/[trpc]";
40

41
// Basic client-side only setup
42
export const trpc = createTRPCNext<AppRouter>({
43
  config() {
44
    return {
45
      links: [
46
        httpBatchLink({
47
          url: "http://localhost:3000/api/trpc",
48
        }),
49
      ],
50
    };
51
  },
52
  ssr: false,
53
});
54

55
// Using the created instance
56
function UserProfile() {
57
  const utils = trpc.useUtils();
58
  const { data } = trpc.user.getProfile.useQuery({ userId: "123" });
59
  
60
  const handleRefresh = () => {
61
    utils.user.getProfile.invalidate({ userId: "123" });
62
  };
63
  
64
  return <div>{data?.name}</div>;
65
}
66
```
67

68
### withTRPC Function
69

70
Higher-order component that wraps Next.js App or Page components with tRPC context and React Query provider.
71

72
```typescript { .api }
73
/**
74
 * Higher-order component that wraps Next.js App or Page components with tRPC context
75
 * @param opts - Configuration options for tRPC client and SSR behavior
76
 * @returns Function that takes a component and returns wrapped component
77
 */
78
function withTRPC<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext>(
79
  opts: WithTRPCNoSSROptions<TRouter> | WithTRPCSSROptions<TRouter>
80
): (AppOrPage: NextComponentType<any, any, any>) => NextComponentType;
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { withTRPC } from "@trpc/next";
87
import { httpBatchLink } from "@trpc/client";
88
import type { AppRouter } from "../pages/api/[trpc]";
89

90
// In pages/_app.tsx
91
const MyApp = ({ Component, pageProps }) => {
92
  return <Component {...pageProps} />;
93
};
94

95
export default withTRPC<AppRouter>({
96
  config() {
97
    return {
98
      links: [
99
        httpBatchLink({
100
          url: process.env.NEXT_PUBLIC_VERCEL_URL
101
            ? `https://${process.env.NEXT_PUBLIC_VERCEL_URL}/api/trpc`
102
            : "http://localhost:3000/api/trpc",
103
        }),
104
      ],
105
    };
106
  },
107
  ssr: false,
108
})(MyApp);
109
```
110

111
### Configuration Options
112

113
#### WithTRPCNoSSROptions
114

115
Configuration for client-side only tRPC setup.
116

117
```typescript { .api }
118
interface WithTRPCNoSSROptions<TRouter extends AnyRouter> extends WithTRPCOptions<TRouter> {
119
  /** Explicitly disable SSR */
120
  ssr?: false;
121
}
122

123
interface WithTRPCOptions<TRouter extends AnyRouter> extends CreateTRPCReactOptions<TRouter>, TransformerOptions<inferClientTypes<TRouter>> {
124
  /** Function that returns tRPC client configuration */
125
  config: (info: { ctx?: NextPageContext }) => WithTRPCConfig<TRouter>;
126
}
127
```
128

129
#### WithTRPCSSROptions
130

131
Configuration for SSR-enabled tRPC setup.
132

133
```typescript { .api }
134
interface WithTRPCSSROptions<TRouter extends AnyRouter> extends WithTRPCOptions<TRouter> {
135
  /** Enable SSR with optional conditional function */
136
  ssr: true | ((opts: { ctx: NextPageContext }) => boolean | Promise<boolean>);
137
  /** Function to set response meta like headers and status codes */
138
  responseMeta?: (opts: {
139
    ctx: NextPageContext;
140
    clientErrors: TRPCClientError<TRouter>[];
141
  }) => ResponseMeta;
142
  /** SSR prepass helper function - use `ssrPrepass` from @trpc/next/ssrPrepass */
143
  ssrPrepass: TRPCPrepassHelper;
144
}
145
```
146

147
#### WithTRPCConfig
148

149
Core configuration options combining tRPC client and React Query settings.
150

151
```typescript { .api }
152
interface WithTRPCConfig<TRouter extends AnyRouter> extends CreateTRPCClientOptions<TRouter>, CreateTRPCReactQueryClientConfig {
153
  /** Whether to abort queries on component unmount */
154
  abortOnUnmount?: boolean;
155
}
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
import { httpBatchLink } from "@trpc/client";
162
import { ssrPrepass } from "@trpc/next/ssrPrepass";
163

164
// Client-side only configuration
165
const clientOnlyConfig = {
166
  config() {
167
    return {
168
      links: [httpBatchLink({ url: "/api/trpc" })],
169
    };
170
  },
171
  ssr: false,
172
};
173

174
// SSR configuration with conditional SSR
175

176
const ssrConfig = {
177
  config(ctx) {
178
    return {
179
      links: [
180
        httpBatchLink({
181
          url: "/api/trpc",
182
          headers: ctx?.ctx?.req?.headers,
183
        }),
184
      ],
185
    };
186
  },
187
  ssr: (ctx) => {
188
    // Only SSR on certain pages
189
    return ctx.ctx?.pathname?.startsWith("/dashboard") ?? false;
190
  },
191
  responseMeta({ ctx, clientErrors }) {
192
    if (clientErrors.length > 0) {
193
      return { status: 500 };
194
    }
195
    return {};
196
  },
197
  ssrPrepass,
198
};
199
```
200

201
## Types
202

203
```typescript { .api }
204
// Function signature for SSR prepass helpers
205
type TRPCPrepassHelper = (opts: {
206
  parent: WithTRPCSSROptions<AnyRouter>;
207
  WithTRPC: NextComponentType<any, any, any>;
208
  AppOrPage: NextComponentType<any, any, any>;
209
}) => void;
210

211
// Props passed to components during SSR prepass
212
interface TRPCPrepassProps<TRouter extends AnyRouter, TSSRContext extends NextPageContext = NextPageContext> {
213
  config: WithTRPCConfig<TRouter>;
214
  queryClient: QueryClient;
215
  trpcClient: TRPCUntypedClient<TRouter> | TRPCClient<TRouter>;
216
  ssrState: 'prepass';
217
  ssrContext: TSSRContext;
218
}
219

220
// Response metadata for SSR
221
interface ResponseMeta {
222
  status?: number;
223
  headers?: Record<string, string>;
224
}
225
```