tRPC v11이 Next.js App Router에서 REST를 대체하는 방식 — 코드 생성 없는 end-to-end 타입 안전성과 서버 스트리밍

// 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';
 
// App Router 환경에서는 cache()로 감싸 요청당 1회만 생성
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' });
  // session!으로 TypeScript에 non-null을 전달해 이후 ctx.session 접근의 타입을 확정
  return next({ ctx: { ...ctx, session: ctx.session! } });
});

// v10 — tRPC 전용 훅 레이어
const { data } = trpc.post.list.useQuery({ limit: 10 });
 
// v11 — TanStack Query 네이티브 인터페이스
const trpc = useTRPC();
const { data } = useQuery(trpc.post.list.queryOptions({ limit: 10 }));

# 기존 패키지 제거 후 신규 패키지 설치
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은 '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: {
        // pending 상태의 쿼리도 직렬화해 Suspense 경계와 호환
        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';
 
// 요청당 1회만 생성
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: 매번 새로 생성
    return makeQueryClient();
  }
  // 브라우저: 싱글톤 유지 (React Suspense 재렌더 시에도 동일 인스턴스 사용)
  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는 Provider 컨텍스트에 의존하므로 반드시 클라이언트 컴포넌트에서 사용
'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>로딩 중...</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="제목" required />
      <textarea name="content" placeholder="내용" />
      <button type="submit" disabled={createPost.isPending}>
        {createPost.isPending ? '저장 중...' : '게시'}
      </button>
      {createPost.isError && (
        {/* 프로덕션에서는 error.message를 그대로 노출하지 않고 사용자 친화적 메시지로 변환 권장 */}
        <p>오류가 발생했습니다. 잠시 후 다시 시도해 주세요.</p>
      )}
    </form>
  );
}

// server/routers/notification.ts
import { on, EventEmitter } from 'events';
import { router, protectedProcedure } from '../trpc';
 
// 실제 환경에서는 Redis pub/sub 또는 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;
 
    // 연결 시 미읽은 알림 즉시 전달
    const pending = await ctx.db.notification.findMany({
      where: { userId, read: false },
      orderBy: { createdAt: 'desc' },
      take: 5,
    });
    if (pending.length > 0) yield pending;
 
    // signal이 abort될 때(클라이언트 연결 해제)까지 이벤트 대기
    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('새 알림:', data),
    })
  );
 
  return <span>알림 {notifications?.length ?? 0}개</span>;
}

// 잘못된 예 — 요청마다 Context가 중복 생성될 수 있음
export const createTRPCContext = async () => { /* ... */ };
 
// 올바른 예 — 요청당 1회 보장
export const createTRPCContext = cache(async () => { /* ... */ });

// v11에서 동작하지 않는 v10 패턴
const { data } = trpc.post.list.useQuery({ limit: 10 }); // ❌
 
// v11 올바른 패턴
const trpc = useTRPC();
const { data } = useQuery(trpc.post.list.queryOptions({ limit: 10 })); // ✅