@trpc/next 11.14.0 → 11.14.1

package/README.md

@@ -36,6 +36,14 @@ pnpm add @trpc/next @trpc/react-query @tanstack/react-query
 bun add @trpc/next @trpc/react-query @tanstack/react-query
 ```
 
+## AI Agents
+
+If you use an AI coding agent, install tRPC skills for better code generation:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
 ## Basic Example
 
 Setup tRPC in `utils/trpc.ts`.

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library');
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.');
+    console.error('');
+    console.error('Install it as a dev dependency:');
+    console.error('  npm add -D @tanstack/intent');
+    console.error('');
+    console.error('Or run directly:');
+    console.error('  npx @tanstack/intent@latest list');
+    process.exit(1);
+  }
+  throw e;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@trpc/next",
-  "version": "11.14.0",
+  "version": "11.14.1",
   "description": "The tRPC Next.js library",
   "author": "KATT",
   "license": "MIT",
@@ -100,13 +100,16 @@
     "app-dir",
     "ssrPrepass",
     "!**/*.test.*",
-    "!**/__tests__"
+    "!**/__tests__",
+    "skills",
+    "!skills/_artifacts",
+    "bin"
   ],
   "peerDependencies": {
     "@tanstack/react-query": "^5.59.15",
-    "@trpc/client": "11.14.0",
-    "@trpc/react-query": "11.14.0",
-    "@trpc/server": "11.14.0",
+    "@trpc/client": "11.14.1",
+    "@trpc/react-query": "11.14.1",
+    "@trpc/server": "11.14.1",
     "next": "*",
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0",
@@ -121,10 +124,11 @@
     }
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.0.20",
     "@tanstack/react-query": "^5.80.3",
-    "@trpc/client": "11.14.0",
-    "@trpc/react-query": "11.14.0",
-    "@trpc/server": "11.14.0",
+    "@trpc/client": "11.14.1",
+    "@trpc/react-query": "11.14.1",
+    "@trpc/server": "11.14.1",
     "@types/express": "^5.0.0",
     "@types/node": "^22.13.5",
     "@types/react": "^19.1.0",
@@ -145,5 +149,11 @@
   "funding": [
     "https://trpc.io/sponsor"
   ],
-  "gitHead": "6e03f5c2f8d8ebaa237747d2db447737393402c6"
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
+  "gitHead": "e896259af491fc4b1c9e8fc320817e2222bae869"
 }

package/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,429 @@
+---
+name: nextjs-app-router
+description: >
+  Full end-to-end tRPC setup for Next.js App Router. Covers route handler
+  with fetchRequestHandler (GET + POST exports), TRPCProvider with
+  QueryClientProvider, createTRPCOptionsProxy for RSC prefetching,
+  HydrateClient/HydrationBoundary for hydration, useSuspenseQuery
+  for Suspense, and server-side callers.
+type: framework
+library: trpc
+framework: react
+library_version: '11.14.0'
+requires:
+  - server-setup
+  - client-setup
+  - react-query-setup
+  - adapter-fetch
+sources:
+  - www/docs/client/nextjs/overview.mdx
+  - www/docs/client/tanstack-react-query/server-components.mdx
+  - www/docs/server/adapters/nextjs.md
+  - examples/next-prisma-starter/
+  - examples/next-sse-chat/
+---
+
+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
+
+```sh
+npm install @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query zod server-only client-only
+```
+
+### 2. Server init and context
+
+```ts title="trpc/init.ts"
+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
+
+```ts title="trpc/routers/_app.ts"
+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)
+
+```ts title="app/api/trpc/[trpc]/route.ts"
+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
+
+```ts title="trpc/query-client.ts"
+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)
+
+```tsx title="trpc/client.tsx"
+'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)
+
+```tsx title="trpc/server.tsx"
+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
+
+```tsx title="app/layout.tsx"
+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
+
+```tsx title="app/page.tsx"
+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>
+  );
+}
+```
+
+```tsx title="app/client-greeting.tsx"
+'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
+
+```tsx title="app/page.tsx"
+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>
+  );
+}
+```
+
+```tsx title="app/client-greeting.tsx"
+'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)
+
+```tsx title="trpc/server.tsx"
+// Add to existing server.tsx
+export const caller = appRouter.createCaller(async () =>
+  createTRPCContext({ headers: await headers() }),
+);
+```
+
+```tsx title="app/page.tsx"
+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
+
+```tsx title="app/page.tsx"
+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.
+
+```ts
+// 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.
+
+```ts
+// 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.
+
+```ts
+// 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

package/skills/nextjs-pages-router/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: nextjs-pages-router
+description: >
+  Set up tRPC in Next.js Pages Router with createNextApiHandler,
+  createTRPCNext, withTRPC HOC, SSR via ssr option and ssrPrepass,
+  SSG via createServerSideHelpers with getStaticProps, and
+  server-side helpers for getServerSideProps prefetching.
+type: framework
+library: trpc
+framework: react
+library_version: '11.14.0'
+requires:
+  - server-setup
+  - client-setup
+sources:
+  - www/docs/client/nextjs/overview.mdx
+  - www/docs/server/adapters/nextjs.md
+  - examples/next-prisma-starter/
+---
+
+This skill builds on [server-setup] and [client-setup]. Read them first for foundational concepts.
+
+# tRPC -- Next.js Pages Router
+
+## File Structure
+
+```
+.
+├── src
+│   ├── pages
+│   │   ├── _app.tsx              # withTRPC() HOC
+│   │   ├── api/trpc
+│   │   │   └── [trpc].ts        # tRPC API handler
+│   │   └── index.tsx             # page using tRPC hooks
+│   ├── server
+│   │   ├── routers
+│   │   │   └── _app.ts          # main app router
+│   │   ├── context.ts           # createContext
+│   │   └── trpc.ts              # initTRPC, procedure helpers
+│   └── utils
+│       └── trpc.ts              # createTRPCNext, hooks
+└── ...
+```
+
+## Setup
+
+### 1. Install
+
+```sh
+npm install @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query zod
+```
+
+### 2. Server init
+
+```ts title="server/trpc.ts"
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+export const router = t.router;
+export const procedure = t.procedure;
+```
+
+### 3. Define the router
+
+```ts title="server/routers/_app.ts"
+import { z } from 'zod';
+import { procedure, router } from '../trpc';
+
+export const appRouter = router({
+  hello: procedure.input(z.object({ text: z.string() })).query(({ input }) => ({
+    greeting: `hello ${input.text}`,
+  })),
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### 4. API handler
+
+```ts title="pages/api/trpc/[trpc].ts"
+import { createNextApiHandler } from '@trpc/server/adapters/next';
+import { appRouter } from '../../../server/routers/_app';
+
+export default createNextApiHandler({
+  router: appRouter,
+  createContext: () => ({}),
+});
+```
+
+### 5. Create tRPC hooks
+
+```ts title="utils/trpc.ts"
+import { httpBatchLink } from '@trpc/client';
+import { createTRPCNext } from '@trpc/next';
+import type { AppRouter } from '../server/routers/_app';
+
+function getBaseUrl() {
+  if (typeof window !== 'undefined') return '';
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
+  return `http://localhost:${process.env.PORT ?? 3000}`;
+}
+
+export const trpc = createTRPCNext<AppRouter>({
+  config() {
+    return {
+      links: [
+        httpBatchLink({
+          url: `${getBaseUrl()}/api/trpc`,
+        }),
+      ],
+    };
+  },
+  ssr: false,
+});
+```
+
+### 6. Wrap app with withTRPC HOC
+
+```tsx title="pages/_app.tsx"
+import type { AppType } from 'next/app';
+import { trpc } from '../utils/trpc';
+
+const MyApp: AppType = ({ Component, pageProps }) => {
+  return <Component {...pageProps} />;
+};
+
+export default trpc.withTRPC(MyApp);
+```
+
+### 7. Use hooks in pages
+
+```tsx title="pages/index.tsx"
+import { trpc } from '../utils/trpc';
+
+export default function IndexPage() {
+  const hello = trpc.hello.useQuery({ text: 'client' });
+  if (!hello.data) return <div>Loading...</div>;
+  return <p>{hello.data.greeting}</p>;
+}
+```
+
+## Core Patterns
+
+### SSR with ssr: true
+
+Enable SSR to prefetch all queries on the server automatically. Requires `ssrPrepass` and forwarding client headers.
+
+```ts title="utils/trpc.ts"
+import { httpBatchLink } from '@trpc/client';
+import { createTRPCNext } from '@trpc/next';
+import { ssrPrepass } from '@trpc/next/ssrPrepass';
+import type { AppRouter } from '../server/routers/_app';
+
+function getBaseUrl() {
+  if (typeof window !== 'undefined') return '';
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
+  return `http://localhost:${process.env.PORT ?? 3000}`;
+}
+
+export const trpc = createTRPCNext<AppRouter>({
+  ssr: true,
+  ssrPrepass,
+  config({ ctx }) {
+    if (typeof window !== 'undefined') {
+      return {
+        links: [httpBatchLink({ url: '/api/trpc' })],
+      };
+    }
+    return {
+      links: [
+        httpBatchLink({
+          url: `${getBaseUrl()}/api/trpc`,
+          headers() {
+            if (!ctx?.req?.headers) return {};
+            return { cookie: ctx.req.headers.cookie };
+          },
+        }),
+      ],
+    };
+  },
+});
+```
+
+### SSG with createServerSideHelpers and getStaticProps
+
+```tsx title="pages/posts/[id].tsx"
+import { createServerSideHelpers } from '@trpc/react-query/server';
+import type {
+  GetStaticPaths,
+  GetStaticPropsContext,
+  InferGetStaticPropsType,
+} from 'next';
+import superjson from 'superjson';
+import { appRouter } from '../../server/routers/_app';
+import { trpc } from '../../utils/trpc';
+
+export async function getStaticProps(
+  context: GetStaticPropsContext<{ id: string }>,
+) {
+  const helpers = createServerSideHelpers({
+    router: appRouter,
+    ctx: {},
+    transformer: superjson,
+  });
+  const id = context.params?.id as string;
+
+  await helpers.post.byId.prefetch({ id });
+
+  return {
+    props: {
+      trpcState: helpers.dehydrate(),
+      id,
+    },
+    revalidate: 1,
+  };
+}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  return { paths: [], fallback: 'blocking' };
+};
+
+export default function PostPage(
+  props: InferGetStaticPropsType<typeof getStaticProps>,
+) {
+  const { id } = props;
+  const postQuery = trpc.post.byId.useQuery({ id });
+
+  if (postQuery.status !== 'success') return <>Loading...</>;
+  return <h1>{postQuery.data.title}</h1>;
+}
+```
+
+### Server-side helpers with getServerSideProps
+
+```tsx title="pages/posts/[id].tsx"
+import { createServerSideHelpers } from '@trpc/react-query/server';
+import type {
+  GetServerSidePropsContext,
+  InferGetServerSidePropsType,
+} from 'next';
+import superjson from 'superjson';
+import { appRouter } from '../../server/routers/_app';
+import { trpc } from '../../utils/trpc';
+
+export async function getServerSideProps(
+  context: GetServerSidePropsContext<{ id: string }>,
+) {
+  const helpers = createServerSideHelpers({
+    router: appRouter,
+    ctx: {},
+    transformer: superjson,
+  });
+  const id = context.params?.id as string;
+
+  await helpers.post.byId.prefetch({ id });
+
+  return {
+    props: {
+      trpcState: helpers.dehydrate(),
+      id,
+    },
+  };
+}
+
+export default function PostPage(
+  props: InferGetServerSidePropsType<typeof getServerSideProps>,
+) {
+  const { id } = props;
+  const postQuery = trpc.post.byId.useQuery({ id });
+
+  if (postQuery.status !== 'success') return <>Loading...</>;
+  return <h1>{postQuery.data.title}</h1>;
+}
+```
+
+### SSR response caching
+
+```ts title="utils/trpc.ts"
+import { httpBatchLink } from '@trpc/client';
+import { createTRPCNext } from '@trpc/next';
+import { ssrPrepass } from '@trpc/next/ssrPrepass';
+import type { AppRouter } from '../server/routers/_app';
+
+export const trpc = createTRPCNext<AppRouter>({
+  ssr: true,
+  ssrPrepass,
+  config() {
+    return {
+      links: [httpBatchLink({ url: '/api/trpc' })],
+    };
+  },
+  responseMeta(opts) {
+    const { clientErrors } = opts;
+    if (clientErrors.length) {
+      return { status: clientErrors[0].data?.httpStatus ?? 500 };
+    }
+    const ONE_DAY_IN_SECONDS = 60 * 60 * 24;
+    return {
+      headers: new Headers([
+        [
+          'cache-control',
+          `s-maxage=1, stale-while-revalidate=${ONE_DAY_IN_SECONDS}`,
+        ],
+      ]),
+    };
+  },
+});
+```
+
+### CORS on the API handler
+
+```ts title="pages/api/trpc/[trpc].ts"
+import { createNextApiHandler } from '@trpc/server/adapters/next';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { appRouter } from '../../../server/routers/_app';
+
+const nextApiHandler = createNextApiHandler({
+  router: appRouter,
+  createContext: () => ({}),
+});
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'OPTIONS, GET, POST');
+  res.setHeader('Access-Control-Allow-Headers', '*');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(200);
+    return res.end();
+  }
+
+  return nextApiHandler(req, res);
+}
+```
+
+## Common Mistakes
+
+### Using ssr: true without understanding implications
+
+Enabling `ssr: true` imports `react-dom` and runs `ssrPrepass` on every request, rendering the component tree repeatedly until no queries are fetching. This adds latency and server load. For better control, keep `ssr: false` (the default) and use `createServerSideHelpers` in `getServerSideProps` or `getStaticProps` to selectively prefetch only the queries you need.
+
+### SSR prepass renders multiple times
+
+The SSR prepass loop re-renders the component tree repeatedly until all queries resolve. This is by design but causes performance issues with expensive renders. Keep SSR-rendered pages lightweight, or switch to selective prefetching with server-side helpers.
+
+### Mixing App Router and Pages Router patterns
+
+App Router uses `fetchRequestHandler`, `createTRPCOptionsProxy`, and `@trpc/tanstack-react-query`. Pages Router uses `createNextApiHandler`, `createTRPCNext`, and `@trpc/next`/`@trpc/react-query`. Applying App Router patterns (like `HydrationBoundary` or `prefetchQuery`) in Pages Router, or vice versa, produces non-functional code.
+
+### Forgetting to return trpcState from getStaticProps/getServerSideProps
+
+When using `createServerSideHelpers`, you must return `trpcState: helpers.dehydrate()` in props. Without this, the prefetched data is lost and queries re-fetch on the client.
+
+```ts
+// WRONG
+return { props: { id } }; // missing trpcState!
+
+// CORRECT
+return { props: { trpcState: helpers.dehydrate(), id } };
+```
+
+## See Also
+
+- [server-setup] -- initTRPC, routers, procedures, context
+- [client-setup] -- vanilla tRPC client, links configuration
+- [nextjs-app-router] -- if migrating to or starting with App Router
+- [react-query-classic-migration] -- migrating from @trpc/react-query to @trpc/tanstack-react-query