tRPC v11 replaces REST in Next.js App Router — end-to-end type safety without code generation and server streaming

// server/routers/post.ts
import { router, publicProcedure } from '../trpc';
import { z } from 'zod';
 
export const postRouter = router({
  list: publicProcedure
    .input(z.object({ limit: z.number().min(1).max(100).default(10) }))
    .query(async ({ input, ctx }) => {
      return ctx.db.post.findMany({ take: input.limit });
    }),
 
  create: publicProcedure
    .input(z.object({ title: z.string().min(1), content: z.string() }))
    .mutation(async ({ input, ctx }) => {
      return ctx.db.post.create({ data: input });
    }),
});
 
// server/routers/index.ts
export const appRouter = router({
  post: postRouter,
});
 
export type AppRouter = typeof appRouter;

// server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { cache } from 'react';
import { auth } from '@/lib/auth';
import { db } from '@/lib/db';
 
// In App Router, wrap with cache() so it's created only once per request
export const createTRPCContext = cache(async () => {
  const session = await auth();
  return { db, session };
});
 
const t = initTRPC.context<typeof createTRPCContext>().create();
 
export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' });
  // Pass session! to TypeScript as non-null to fix the type of ctx.session in subsequent access
  return next({ ctx: { ...ctx, session: ctx.session! } });
});

// v10 — tRPC-specific hook layer
const { data } = trpc.post.list.useQuery({ limit: 10 });
 
// v11 — TanStack Query native interface
const trpc = useTRPC();
const { data } = useQuery(trpc.post.list.queryOptions({ limit: 10 }));

# Remove old package, then install new packages
npm uninstall @trpc/react-query
npm install @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query zod

// lib/trpc/client.ts
import {
  createTRPCClient,
  httpBatchStreamLink,
  httpSubscriptionLink,
  splitLink,
} from '@trpc/client';
import type { AppRouter } from '@/server/routers';
 
export const trpcClient = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      // op.type is 'query' | 'mutation' | 'subscription'
      condition: (op) => op.type === 'subscription',
      true: httpSubscriptionLink({ url: '/api/trpc' }),
      false: httpBatchStreamLink({ url: '/api/trpc' }),
    }),
  ],
});

// lib/trpc/query-client.ts
import { QueryClient, defaultShouldDehydrateQuery } from '@tanstack/react-query';
 
export function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30 * 1000,
      },
      dehydrate: {
        // Serialize pending queries too, for Suspense boundary compatibility
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
      },
    },
  });
}

// lib/trpc/server.ts
import { cache } from 'react';
import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query';
import { HydrationBoundary, dehydrate } from '@tanstack/react-query';
import { makeQueryClient } from './query-client';
import { appRouter } from '@/server/routers';
import { createTRPCContext } from '@/server/trpc';
 
// Created only once per request
export const getQueryClient = cache(makeQueryClient);
 
export function HydrateClient({ children }: { children: React.ReactNode }) {
  return (
    <HydrationBoundary state={dehydrate(getQueryClient())}>
      {children}
    </HydrationBoundary>
  );
}
 
export async function createServerTRPC() {
  const ctx = await createTRPCContext();
  const queryClient = getQueryClient();
  return createTRPCOptionsProxy({ ctx, router: appRouter, queryClient });
}

// app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/routers';
import { createTRPCContext } from '@/server/trpc';
 
const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: createTRPCContext,
  });
 
export { handler as GET, handler as POST };

// components/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createTRPCReactContext } from '@trpc/tanstack-react-query';
import { trpcClient } from '@/lib/trpc/client';
import { makeQueryClient } from '@/lib/trpc/query-client';
import type { AppRouter } from '@/server/routers';
 
export const { TRPCProvider, useTRPC } = createTRPCReactContext<AppRouter>();
 
let browserQueryClient: QueryClient | undefined;
 
function getQueryClient() {
  if (typeof window === 'undefined') {
    // SSR: create a new instance every time
    return makeQueryClient();
  }
  // Browser: keep a singleton (reuse the same instance across React Suspense re-renders)
  return (browserQueryClient ??= makeQueryClient());
}
 
export function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient();
  return (
    <QueryClientProvider client={queryClient}>
      <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
        {children}
      </TRPCProvider>
    </QueryClientProvider>
  );
}

// app/posts/page.tsx — Server Component
import { createServerTRPC, HydrateClient } from '@/lib/trpc/server';
import PostList from './post-list';
 
export default async function PostsPage() {
  const trpc = await createServerTRPC();
  await trpc.post.list.prefetchQuery({ limit: 20 });
 
  return (
    <HydrateClient>
      <PostList />
    </HydrateClient>
  );
}

// app/posts/post-list.tsx — Client Component
// useTRPC depends on Provider context, so it must be used in a client component
'use client';
import { useQuery } from '@tanstack/react-query';
import { useTRPC } from '@/components/providers';
 
export default function PostList() {
  const trpc = useTRPC();
  const { data, isLoading } = useQuery(
    trpc.post.list.queryOptions({ limit: 20 })
  );
 
  if (isLoading) return <div>Loading...</div>;
 
  return (
    <ul>
      {data?.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

// app/posts/create-post-form.tsx
'use client';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { useTRPC } from '@/components/providers';
 
export default function CreatePostForm() {
  const trpc = useTRPC();
  const queryClient = useQueryClient();
 
  const createPost = useMutation(
    trpc.post.create.mutationOptions({
      onSuccess: () => {
        queryClient.invalidateQueries({
          queryKey: trpc.post.list.queryKey(),
        });
      },
    })
  );
 
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    createPost.mutate({
      title: formData.get('title') as string,
      content: formData.get('content') as string,
    });
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" />
      <button type="submit" disabled={createPost.isPending}>
        {createPost.isPending ? 'Saving...' : 'Publish'}
      </button>
      {createPost.isError && (
        {/* In production, avoid exposing error.message directly; convert it to a user-friendly message */}
        <p>An error occurred. Please try again later.</p>
      )}
    </form>
  );
}

// server/routers/notification.ts
import { on, EventEmitter } from 'events';
import { router, protectedProcedure } from '../trpc';
 
// In production, prefer Redis pub/sub or a DB change stream
export const notificationEmitter = new EventEmitter();
 
export const notificationRouter = router({
  feed: protectedProcedure.subscription(async function* ({ ctx, signal }) {
    const userId = ctx.session.user.id;
 
    // Immediately deliver unread notifications on connect
    const pending = await ctx.db.notification.findMany({
      where: { userId, read: false },
      orderBy: { createdAt: 'desc' },
      take: 5,
    });
    if (pending.length > 0) yield pending;
 
    // Wait for events until signal is aborted (client disconnects)
    for await (const [notification] of on(
      notificationEmitter,
      `notification:${userId}`,
      { signal }
    )) {
      yield [notification];
    }
  }),
});

// components/notification-bell.tsx
'use client';
import { useSubscription } from '@trpc/tanstack-react-query';
import { useTRPC } from '@/components/providers';
 
export default function NotificationBell() {
  const trpc = useTRPC();
 
  const { data: notifications } = useSubscription(
    trpc.notification.feed.subscriptionOptions(undefined, {
      onData: (data) => console.log('New notification:', data),
    })
  );
 
  return <span>{notifications?.length ?? 0} notifications</span>;
}

// Wrong — Context may be created multiple times per request
export const createTRPCContext = async () => { /* ... */ };
 
// Correct — Guaranteed once per request
export const createTRPCContext = cache(async () => { /* ... */ });

// v10 pattern that doesn't work in v11
const { data } = trpc.post.list.useQuery({ limit: 10 }); // ❌
 
// Correct v11 pattern
const trpc = useTRPC();
const { data } = useQuery(trpc.post.list.queryOptions({ limit: 10 })); // ✅