React와 Next.js에서 tRPC 설정하기

핵심 tRPC 패키지인 @trpc/server와 @trpc/client를 설치합니다. React 훅 어댑터로 @trpc/react-query를 추가하고, 훅을 구동하는 피어 의존성으로 @tanstack/react-query를 추가합니다.

Next.js API 라우트 통합에는 최근 tRPC 버전에서 추가 어댑터 패키지가 필요하지 않습니다.

server/trpc.ts 파일을 만들고 initTRPC.create()를 호출하여 t 객체를 가져옵니다. t.router를 router로, t.procedure를 publicProcedure로, t.mergeRouters를 유틸리티로 내보냅니다.

initTRPC 팩토리는 모든 프로시저의 ctx 인자에서 사용할 수 있는 데이터를 정의하는 컨텍스트 타입 제네릭을 받습니다.

프로시저는 publicProcedure에 .input(zodSchema).query(handler) 또는 .mutation(handler)를 연결하여 정의합니다. 간단한 인사 엔드포인트는 publicProcedure.input(z.object({ name: z.string() })).query(({ input }) => "Hello " + input.name)과 같이 작성합니다.

Zod 스키마는 입력에 대한 TypeScript 타입과 런타임 검증을 모두 제공합니다.

router() 함수를 사용하여 appRouter를 만듭니다: router({ hello: helloHandler, users: usersRouter }). 중첩 라우터를 사용하면 도메인(users, posts, comments)별로 프로시저를 별도의 파일에 구성할 수 있습니다.

AppRouter 타입을 내보냅니다: export type AppRouter = typeof appRouter. 이 타입을 클라이언트에서 가져옵니다.

app/api/trpc/[trpc]/route.ts(앱 라우터) 또는 pages/api/trpc/[trpc].ts(페이지 라우터)를 만듭니다. @trpc/server/adapters/fetch의 fetchRequestHandler를 사용하여 이 단일 포괄 라우트를 통해 모든 tRPC 요청을 처리합니다.

라우터, createContext 함수, 요청 및 응답 객체를 fetchRequestHandler에 전달합니다.

utils/trpc.ts 파일을 만듭니다. createTRPCReact()를 호출하여 타입이 지정된 trpc 클라이언트 객체를 생성합니다. 이 객체에는 라우터의 각 프로시저에 해당하는 속성이 있으며, 각 속성은 리액트 쿼리 훅을 제공합니다.

AppRouter 타입은 서버 파일에서 가져오며, TypeScript는 가져오기 연결을 따라가 모든 사용을 검증합니다.

앱 레이아웃 또는 _app.tsx에서 QueryClient 인스턴스와 trpc.createClient({ links: [httpBatchLink({ url: '/api/trpc' })] })를 사용한 tRPC 클라이언트 인스턴스를 만듭니다.

컴포넌트 트리를 trpc.Provider(trpc 클라이언트 전달)와 QueryClientProvider(QueryClient 전달)로 모두 감쌉니다. 두 프로바이더가 모두 필요합니다.

어떤 컴포넌트에서든 const { data, isLoading, error } = trpc.hello.useQuery({ name: 'World' })를 사용합니다. 이 훅은 완전히 타입이 지정됩니다. data는 hello 프로시저에서 추론된 반환 타입이며, 입력 객체는 Zod 스키마에 맞는지 타입 검사를 받습니다.

잘못된 입력 타입을 전달하면 런타임 오류가 아니라 TypeScript 컴파일 오류가 발생합니다.

tRPC가 작동하려면 클라이언트에서 서버 파일의 타입을 가져올 수 있어야 합니다. Next.js 프로젝트에서는 서버 코드와 클라이언트 코드가 동일한 TypeScript 컴파일을 공유하므로 가져오기가 바로 작동합니다.

별도의 패키지로 구성된 모노레포에서는 tsconfig.json에서 TypeScript 프로젝트 참조 또는 경로 별칭을 구성하여 서버 패키지를 가리키도록 합니다.

tRPC 핸들러는 서버에서 실행됩니다(Next.js API 라우트 또는 엣지 함수로 실행됩니다). tRPC 클라이언트는 브라우저에서 실행됩니다. TypeScript는 빌드 시점에 타입 수준의 가져오기를 평가하므로 브라우저에서 서버 코드를 실행하지 않습니다.

클라이언트에서는 실제 구현이 아니라 AppRouter 타입만 가져오므로 서버 비밀 정보가 클라이언트 번들로 유출되지 않습니다.

Next.js 개발 서버를 시작하고 브라우저 콘솔을 엽니다. trpc.hello.useQuery 호출은 서버 응답을 로그로 출력해야 합니다. Network 탭에서 입력이 쿼리 매개변수로 일괄 처리된 /api/trpc/hello에 대한 HTTP 요청을 확인합니다.

기본 httpBatchLink는 여러 동시 요청을 하나의 HTTP 호출로 결합하며, 네트워크 워터폴에서 이를 확인할 수 있습니다.

tRPC 인스턴스를 초기화하고 라우터 및 프로시저 팩토리를 제공하는 함수는 무엇인가요?

@trpc/server, @trpc/client, @trpc/react-query, @tanstack/react-query를 설치합니다. initTRPC.create()로 tRPC를 초기화하고 프로시저를 정의한 다음 AppRouter 타입을 내보냅니다. Next.js API 포괄 라우트를 만들고 TRPCProvider와 QueryClientProvider를 설정한 뒤 trpc.procedureName.useQuery()로 프로시저를 호출합니다.

TypeScript는 코드 생성 없이 컴파일 시점에 전체 클라이언트-서버 계약을 적용합니다.