tRPC가 해결하는 문제

TypeScript로 REST API를 구축하면 서버가 응답 형태를 정의합니다. 클라이언트에서는 일치하는 TypeScript 타입을 수동으로 만들어야 합니다. API가 발전함에 따라 시간이 지나면서 이러한 타입이 서로 달라지지만, 타입이 별도의 패키지에 정의되어 있기 때문에 컴파일러가 불일치를 감지하지 못합니다.

서버에서 필드 이름을 변경하면 클라이언트에서 조용히 발생하는 런타임 오류가 됩니다.

GraphQL은 graphql-codegen과 같은 도구를 사용해 스키마에서 TypeScript 타입을 생성함으로써 타입 불일치 문제를 해결합니다. 이 방법은 잘 작동하지만 별도의 쿼리 언어(GraphQL SDL), 빌드 과정의 코드 생성 단계, 스키마 관리 도구가 추가되어 복잡해집니다.

이미 GraphQL에 투자한 팀이라면 코드 생성이 올바른 해결책입니다. GraphQL의 추가 부담 없이 타입 안전성을 원하는 팀에는 tRPC가 대안이 될 수 있습니다.

tRPC의 접근 방식은 놀라울 정도로 단순합니다. 서버에서 API 프로시저를 TypeScript 함수로 정의하고, 라우터 타입을 내보낸 다음, 클라이언트에서 해당 타입을 가져옵니다. 코드 생성이 필요하지 않습니다. 별도의 스키마 언어도 필요하지 않습니다.

TypeScript 컴파일러 자체가 빌드 시 클라이언트와 서버 사이의 계약을 확인합니다.

tRPC는 TypeScript 가져오기를 통해 서버와 클라이언트가 타입을 공유해야 합니다. 서버와 클라이언트가 서로 가져올 수 있는 별도 패키지로 구성된 모노레포(Turborepo, Nx, pnpm workspaces)에서는 이 방식이 자연스럽게 작동합니다.

백엔드와 프런트엔드가 완전히 분리되어 있다면 라우터 타입을 공유 패키지로 게시해야 합니다. 게시 단계가 추가되지만 여전히 코드 생성은 필요하지 않습니다.

서버에서 라우터를 정의하고 그 타입을 내보냅니다: export type AppRouter = typeof appRouter. 클라이언트에서는 해당 타입을 가져와 타입이 지정된 클라이언트를 만듭니다: createTRPCReact<AppRouter>(). 그러면 클라이언트는 어떤 프로시저가 존재하는지와 각 프로시저의 입력 및 출력 타입이 무엇인지 정확히 알 수 있습니다.

서버에서 프로시저 이름을 변경하면 클라이언트에 즉시 TypeScript 오류가 표시됩니다.

tRPC는 TypeScript의 타입 시스템을 직접 사용하므로 편집기에서 클라이언트 측 프로시저 이름, 입력 형태, 반환 타입에 대한 완전한 자동 완성을 제공합니다. 프로시저 이름 변경은 코드베이스 전체에서 수동으로 검색해 바꾸는 작업이 아니라 TypeScript 이름 변경 리팩터링으로 처리됩니다.

이처럼 개발자 경험을 개선하는 점이 실제로 tRPC에서 가장 많이 칭찬받는 기능입니다.

tRPC는 기본적으로 HTTP를 전송 방식으로 사용합니다. 각 프로시저 호출은 HTTP 요청입니다. tRPC는 구독을 위한 WebSockets도 지원합니다. 전송 방식은 구현 세부 사항이므로 어떤 전송 방식을 사용하든 클라이언트 API는 동일합니다.

비-tRPC 클라이언트와의 호환성을 위해 REST 어댑터를 사용하여 tRPC 프로시저를 일반적인 REST 엔드포인트로 노출할 수도 있습니다.

tRPC는 Express, Fastify, Hono에서 미들웨어로 작동합니다. Next.js에서는 API 경로 처리기와 통합됩니다. create-t3-app 시작 템플릿(T3 Stack)은 tRPC, Prisma, NextAuth, Tailwind를 하나의 풀스택 Next.js 템플릿으로 묶어 제공합니다.

T3 Stack은 가장 인기 있는 tRPC 시작 지점이며 프로덕션에 바로 사용할 수 있는 패턴을 보여 줍니다.

타입 안전한 REST 접근 방식으로 Zod 스키마를 정의하고, OpenAPI 명세를 자동 생성한 다음, 명세에서 TypeScript 타입을 생성하는 방법도 있습니다. 이 방식은 TypeScript가 아닌 클라이언트도 사용할 수 있는 API 계약을 제공합니다.

tRPC는 더 단순하지만 TypeScript 전용입니다. OpenAPI+Zod는 더 복잡하지만 공개 API 계약을 만들어 냅니다. 내부 TypeScript 간 통신에는 tRPC를, 공개 API에는 OpenAPI를 선택하십시오.

제3자가 사용하는 공개 API, TypeScript로 작성되지 않은 모바일 클라이언트, 안정적인 버전 관리 계약이 필요한 파트너를 대상으로 한다면 tRPC는 REST를 대체할 수 없습니다. tRPC는 풀스택 타입 안전성이 필요한 TypeScript 모노레포를 위한 도구입니다.

이 범위를 이해하면 REST나 GraphQL이 더 적합한 상황에서 tRPC를 도입하는 일을 피할 수 있습니다.

npm create t3-app@latest를 실행하면 tRPC, Prisma, NextAuth.js, Tailwind CSS, TypeScript가 미리 구성된 Next.js 프로젝트의 뼈대를 생성합니다. 생성된 코드는 라우터 구조, 컨텍스트 생성 및 클라이언트 설정을 보여 줍니다.

이 뼈대를 학습하는 것이 실제 애플리케이션에서 모든 tRPC 구성 요소가 어떻게 맞물리는지 이해하는 가장 빠른 방법입니다.

코드 생성 없이 tRPC는 서버와 클라이언트 사이에서 타입을 어떻게 공유할까요?

tRPC는 가져오기를 통해 라우터의 TypeScript 타입을 직접 공유하여 TypeScript 클라이언트와 서버 사이의 타입 불일치를 해결하고 코드 생성을 없앱니다. 모노레포에서 작동하며 Next.js, Express, Fastify, Hono와 통합됩니다. T3 Stack(create-t3-app)은 프로덕션에서 사용하는 표준 시작 템플릿입니다.

tRPC는 TypeScript 전용이며 공개 API보다는 내부 풀스택 애플리케이션에 가장 적합합니다.