tRPC v11 + Next.js App Router: 보일러플레이트 없이 엔드 투 엔드 타입 안전성

발행: 3주 전 (2026년 4월 17일 AM 11:01 GMT+9)

9 분 소요

원문: Dev.to

Source: Dev.to

번역을 진행하려면 실제 번역이 필요한 텍스트(본문)를 제공해 주시겠어요?
본문을 알려주시면 요청하신 대로 마크다운 형식과 코드 블록, URL은 그대로 유지하면서 한국어로 번역해 드리겠습니다.

tRPC v11 + Next.js App Router – No‑Ceremony Setup

작년에 Next.js App Router와 함께 tRPC v10을 사용하면서 이틀을 보냈습니다. 모든 튜토리얼은 페이지 라우터용이거나, 설치 시 깨지는 v11‑베타 기사였죠.

v11이 안정화된 지금, 통합이 정말 훌륭합니다. 아래는 별도의 어댑터 없이 핵심만으로 동작하는 정확한 패턴입니다.

왜 tRPC인가?

전체 TypeScript 추론 지원 (입력 → 출력, 형 변환 필요 없음)
Procedures 를 Server Components, Client Components, Server Actions 어디서든 사용할 수 있음
필요할 때 WebSocket 으로 구독(Subscriptions) 가능
타입이 지정된 미들웨어 로 인증, 속도 제한, 로깅 등을 구현

앱에 10개 이상의 API 엔드포인트가 있고 fetch 호출과 Zod 스키마를 양쪽에서 직접 관리하고 있다면, tRPC는 일주일 만에 비용을 회수합니다.

패키지 설치

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next zod
npm install @tanstack/react-query

서버‑사이드 설정

`server/trpc.ts`

import { initTRPC, TRPCError } from '@trpc/server';
import { getServerSession } from 'next-auth';
import { z } from 'zod';

const t = initTRPC.context> | null;
}>().create();

export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({ ctx: { session: ctx.session } });
});

`server/routers/posts.ts`

import { router, protectedProcedure, publicProcedure } from '../trpc';
import { z } from 'zod';

export const postsRouter = router({
  // Public list endpoint
  list: publicProcedure
    .input(
      z.object({
        cursor: z.string().optional(),
        limit: z.number().min(1).max(50).default(20),
      })
    )
    .query(async ({ input }) => {
      const posts = await db.post.findMany({
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        orderBy: { createdAt: 'desc' },
      });
      const nextCursor =
        posts.length > input.limit ? posts.pop()!.id : undefined;
      return { posts, nextCursor };
    }),

  // Protected create endpoint
  create: protectedProcedure
    .input(
      z.object({
        title: z.string().min(1).max(200),
        content: z.string(),
      })
    )
    .mutation(async ({ input, ctx }) => {
      return db.post.create({
        data: { ...input, authorId: ctx.session.user.id },
      });
    }),
});

`server/root.ts`

import { router } from './trpc';
import { postsRouter } from './routers/posts';

export const appRouter = router({
  posts: postsRouter,
});

export type AppRouter = typeof appRouter;

API Route – `app/api/trpc/[trpc]/route.ts`

import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/root';
import { getServerSession } from 'next-auth';

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: async () => ({
      session: await getServerSession(),
    }),
    onError: ({ error }) => {
      if (error.code === 'INTERNAL_SERVER_ERROR') {
        console.error('tRPC error:', error);
      }
    },
  });

export { handler as GET, handler as POST };

클라이언트‑사이드 제공자

`app/_providers/trpc.tsx`

'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@/server/root';
import { useState } from 'react';

export const trpc = createTRPCReact<AppRouter>();

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: { queries: { staleTime: 60 * 1000 } },
      })
  );

  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: '/api/trpc',
          headers: () => ({ 'x-trpc-source': 'react' }),
        }),
      ],
    })
  );

  return (
    <QueryClientProvider client={queryClient}>
      <trpc.Provider client={trpcClient} queryClient={queryClient}>
        {children}
      </trpc.Provider>
    </QueryClientProvider>
  );
}

서버 컴포넌트에서 tRPC 사용 (Zero HTTP)

`app/posts/page.tsx`

import { createCaller } from '@/server/root';
import { getServerSession } from 'next-auth';

export default async function PostsPage() {
  const session = await getServerSession();
  const caller = createCaller({ session });

  // Direct call — no HTTP, full type safety
  const { posts } = await caller.posts.list({ limit: 20 });

  return (
    <section>
      {posts.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </section>
  );
}

createCaller 유틸리티는 라우터를 서버 프로세스에서 직접 실행합니다—같은 인증 컨텍스트, 같은 미들웨어, HTTP 오버헤드 제로.

Source: …

Client Components에서 tRPC 사용하기

`components/CreatePostForm.tsx`

'use client';
import { trpc } from '@/app/_providers/trpc';
import { useState } from 'react';

export function CreatePostForm() {
  const [title, setTitle] = useState('');
  const utils = trpc.useUtils();

  const createPost = trpc.posts.create.useMutation({
    onSuccess: () => {
      utils.posts.list.invalidate();
      setTitle('');
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        createPost.mutate({ title, content: '' });
      }}
    >
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Post title"
      />
      <button type="submit" disabled={createPost.isPending}>
        {createPost.isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  );
}

tRPC의 useUtils() 훅은 쿼리 캐시에 대한 타입이 지정된 접근을 제공합니다. 낙관적 업데이트는 단순히 캐시를 조작하는 것입니다:

const utils = trpc.useUtils();

const deletePost = trpc.posts.delete.useMutation({
  onMutate: async ({ id }) => {
    await utils.posts.list.cancel();
    const prev = utils.posts.list.getData();
    utils.posts.list.setData(undefined, (old) =>
      old ? old.filter((post) => post.id !== id) : []
    );
    return { prev };
  },
  onError: (err, _vars, context) => {
    utils.posts.list.setData(undefined, context?.prev);
  },
  onSettled: () => {
    utils.posts.list.invalidate();
  },
});

d => ({
  ...old!,
  posts: old!.posts.filter(p => p.id !== id),
}))
return { prev }
},
onError: (_err, _vars, ctx) => {
  utils.posts.list.setData(undefined, ctx?.prev)
},
onSettled: () => {
  utils.posts.list.invalidate()
},
})

핵심 포인트: setData는 라우터의 출력 스키마에 맞게 타입이 지정됩니다. 잘못된 형태를 실수로 설정할 수 없습니다.

tRPC는 오류 코드를 HTTP 상태 코드에 자동으로 매핑하지만, 클라이언트에서 특정 오류를 직접 처리할 수도 있습니다:

createPost.mutate({ title }, {
  onError: (error) => {
    if (error.data?.code === 'UNAUTHORIZED') {
      router.push('/login')
    } else if (error.data?.code === 'BAD_REQUEST') {
      // Zod 검증 오류 — `error.data.zodError`에 필드‑레벨 상세 정보가 포함됩니다
      setErrors(error.data.zodError.fieldErrors)
    }
  }
})

추가 참고 사항

WebSocket을 이용한 tRPC 구독 – 실시간 푸시가 꼭 필요하지 않다면, 폴링이나 Supabase Realtime을 사용하는 것이 좋습니다. WebSocket 설정은 대부분의 앱에 필요 없는 인프라 복잡성을 추가합니다.
Server Actions와 함께 사용하는 tRPC – 가능하지만, 두 패턴을 섞게 됩니다. 하나만 선택하세요. 저는 모든 데이터 조회와 변이를 tRPC로 처리하거나, Zod와 함께 순수 Server Actions만 사용합니다 – 둘을 동시에 쓰지는 않습니다.
App Router와 함께하는 tRPC v11은 제가 찾은 가장 “해결된” 풀스택 TypeScript 설정에 가깝습니다. Server Components용 createCaller 패턴은 v10에서 가장 큰 고통점이던 부분을 없애고, 나머지 API는 충분히 깔끔해서 도구에 신경 쓰지 않고 제품에 집중할 수 있습니다.

오늘 새로운 Next.js 프로젝트를 시작하고 TypeScript가 필수라면, 이 스택을 권합니다.

Building with tRPC + Claude Code at whoffagents.com

tRPC v11 + Next.js App Router: 보일러플레이트 없이 엔드 투 엔드 타입 안전성

tRPC v11 + Next.js App Router – No‑Ceremony Setup

왜 tRPC인가?

패키지 설치

서버‑사이드 설정

`server/trpc.ts`

`server/routers/posts.ts`

`server/root.ts`

API Route – `app/api/trpc/[trpc]/route.ts`

클라이언트‑사이드 제공자

`app/_providers/trpc.tsx`

서버 컴포넌트에서 tRPC 사용 (Zero HTTP)

`app/posts/page.tsx`

Client Components에서 tRPC 사용하기

`components/CreatePostForm.tsx`

추가 참고 사항

관련 제품

관련 글

KeyYap 구축: 프리미엄 ‘Yapping’ 플랫폼 만들기

TypeScript에서 유틸리티 타입 이해하기: Partial, Readonly, Pick, 그리고 Record를 예제로 설명

Protobuf: Google 서버가 JSON을 사용하지 않는 이유

내가 오래된 Invoice App을 다시 만들고 있는데, 이번엔 정말 뭘 하는지 알고 있다

tRPC v11 + Next.js App Router – No‑Ceremony Setup

왜 tRPC인가?

패키지 설치

서버‑사이드 설정

server/trpc.ts

server/routers/posts.ts

server/root.ts

API Route – app/api/trpc/[trpc]/route.ts

클라이언트‑사이드 제공자

app/_providers/trpc.tsx

서버 컴포넌트에서 tRPC 사용 (Zero HTTP)

app/posts/page.tsx

Client Components에서 tRPC 사용하기

components/CreatePostForm.tsx

추가 참고 사항

관련 제품

관련 글

KeyYap 구축: 프리미엄 ‘Yapping’ 플랫폼 만들기

TypeScript에서 유틸리티 타입 이해하기: Partial, Readonly, Pick, 그리고 Record를 예제로 설명

Protobuf: Google 서버가 JSON을 사용하지 않는 이유

내가 오래된 Invoice App을 다시 만들고 있는데, 이번엔 정말 뭘 하는지 알고 있다

`server/trpc.ts`

`server/routers/posts.ts`

`server/root.ts`

API Route – `app/api/trpc/[trpc]/route.ts`

`app/_providers/trpc.tsx`

`app/posts/page.tsx`

`components/CreatePostForm.tsx`