tRPC 실전 가이드 — 타입 안전한 API 만들기

tRPC 핵심 개념과 작동 원리

Next.js App Router 통합 셋업

Bash — 패키지 설치
npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod
npm install -D typescript @types/node

TypeScript — tRPC 초기화 (src/server/trpc.ts)
import { initTRPC, TRPCError } from '@trpc/server'
import { ZodError } from 'zod'

// Context 타입 정의
export interface Context {
  userId?: string
  db: { /* DB 클라이언트 */ }
}

const t = initTRPC.context<Context>().create({
  // Zod 에러를 클라이언트 친화적 형식으로 변환
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    }
  },
})

// 공개 프로시저 (인증 불필요)
export const router = t.router
export const publicProcedure = t.procedure

// 인증 미들웨어
const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.userId) {
    throw new TRPCError({ code: 'UNAUTHORIZED' })
  }
  return next({ ctx: { userId: ctx.userId } })
})

// 인증된 프로시저
export const protectedProcedure = t.procedure.use(isAuthed)

TypeScript — 라우터 정의 (src/server/routers/post.ts)
import { z } from 'zod'
import { router, publicProcedure, protectedProcedure } from '../trpc'
import { TRPCError } from '@trpc/server'

// 입력 스키마
const createPostInput = z.object({
  title: z.string().min(1).max(100),
  content: z.string().min(10),
  published: z.boolean().default(false),
})

export const postRouter = router({
  // 게시글 목록 조회 (query)
  list: publicProcedure
    .input(z.object({ limit: z.number().min(1).max(50).default(10) }))
    .query(async ({ input, ctx }) => {
      // ctx.db에서 실제 DB 쿼리
      return { posts: [], total: 0 }
    }),

  // 게시글 상세 조회
  byId: publicProcedure
    .input(z.object({ id: z.string().cuid() }))
    .query(async ({ input, ctx }) => {
      const post = null // ctx.db에서 조회
      if (!post) throw new TRPCError({ code: 'NOT_FOUND', message: '게시글을 찾을 수 없습니다' })
      return post
    }),

  // 게시글 생성 (mutation, 인증 필요)
  create: protectedProcedure
    .input(createPostInput)
    .mutation(async ({ input, ctx }) => {
      const post = { id: 'generated-id', ...input, authorId: ctx.userId }
      return post
    }),

  // 게시글 삭제
  delete: protectedProcedure
    .input(z.object({ id: z.string().cuid() }))
    .mutation(async ({ input, ctx }) => {
      return { success: true }
    }),
})

Next.js API 핸들러와 클라이언트 설정

TypeScript — App Router API 핸들러 (app/api/trpc/[trpc]/route.ts)
import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
import { appRouter } from '@/server/routers/_app'
import { createContext } from '@/server/context'

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: () => createContext(req),
  })

export { handler as GET, handler as POST }

TypeScript — 클라이언트 설정 (src/utils/trpc.ts)
import { createTRPCReact } from '@trpc/react-query'
import { httpBatchLink } from '@trpc/client'
import type { AppRouter } from '@/server/routers/_app'

export const trpc = createTRPCReact<AppRouter>()

export function getTRPCClient() {
  return trpc.createClient({
    links: [
      httpBatchLink({
        url: '/api/trpc',
        // 요청 배칭 활성화 (기본값)
        maxURLLength: 2048,
      }),
    ],
  })
}

React 컴포넌트에서 tRPC 훅 사용

TypeScript/React — 클라이언트 컴포넌트에서 사용
'use client'
import { trpc } from '@/utils/trpc'
import { useState } from 'react'

export function PostList() {
  // useQuery — 자동 타입 추론
  const { data, isLoading, error } = trpc.post.list.useQuery({ limit: 10 })

  // useMutation — 입력/출력 타입 자동 추론
  const createPost = trpc.post.create.useMutation({
    onSuccess: () => {
      // 목록 자동 갱신
      utils.post.list.invalidate()
    },
  })
  const utils = trpc.useUtils()

  const [title, setTitle] = useState('')
  const [content, setContent] = useState('')

  if (isLoading) return <div>로딩 중...</div>
  if (error) return <div>에러: {error.message}</div>

  return (
    <div>
      <form
        onSubmit={(e) => {
          e.preventDefault()
          createPost.mutate({ title, content })
        }}
      >
        <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder='제목' />
        <textarea value={content} onChange={(e) => setContent(e.target.value)} placeholder='내용' />
        <button type='submit' disabled={createPost.isPending}>
          {createPost.isPending ? '저장 중...' : '게시글 작성'}
        </button>
      </form>
      <ul>
        {data?.posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  )
}

미들웨어와 Zod 검증 심화

TypeScript — 로깅 미들웨어와 레이트 리밋 예제
import { initTRPC, TRPCError } from '@trpc/server'

const t = initTRPC.context<Context>().create()

// 로깅 미들웨어
const withLogging = t.middleware(async ({ path, type, next }) => {
  const start = Date.now()
  const result = await next()
  const durationMs = Date.now() - start
  console.log(`[${type}] ${path} - ${durationMs}ms - ${result.ok ? 'OK' : 'ERROR'}`)
  return result
})

// 레이트 리밋 미들웨어 (인메모리, 프로덕션에선 Redis 사용)
const rateLimitMap = new Map<string, number[]>()
const withRateLimit = t.middleware(({ ctx, next }) => {
  const key = ctx.userId ?? 'anonymous'
  const now = Date.now()
  const windowMs = 60_000  // 1분
  const limit = 100

  const timestamps = (rateLimitMap.get(key) ?? []).filter((t) => now - t < windowMs)
  if (timestamps.length >= limit) {
    throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: '요청 한도 초과' })
  }
  rateLimitMap.set(key, [...timestamps, now])
  return next()
})

// 미들웨어 체이닝
export const loggedProcedure = t.procedure.use(withLogging)
export const rateLimitedProcedure = t.procedure.use(withLogging).use(withRateLimit)