O problema resolvido pelo tRPC

Ao criar uma API REST em TypeScript, o servidor define o formato da resposta. O cliente precisa criar manualmente tipos TypeScript correspondentes. Com o tempo, esses tipos divergem à medida que a API evolui, e o compilador não consegue detectar a incompatibilidade porque os tipos estão definidos em pacotes separados.

Um campo renomeado no servidor transforma-se em um erro silencioso em tempo de execução no cliente.

O GraphQL resolve a divergência de tipos gerando tipos TypeScript a partir do esquema, usando ferramentas como graphql-codegen. Isso funciona bem, mas acrescenta complexidade: uma linguagem de consulta separada (GraphQL SDL), uma etapa de geração de código no fluxo de compilação e ferramentas de gerenciamento de esquemas.

Para equipes que já investem em GraphQL, o codegen é a resposta certa. Para equipes que querem segurança de tipos sem a sobrecarga do GraphQL, o tRPC oferece uma alternativa.

A abordagem do tRPC é radicalmente simples: defina os procedimentos da API no servidor como funções TypeScript, exporte o tipo do roteador e importe esse tipo no cliente. Não há geração de código nem uma linguagem de esquema separada.

O próprio compilador do TypeScript impõe o contrato entre cliente e servidor no momento da compilação.

O tRPC exige que o servidor e o cliente compartilhem tipos por meio de importações do TypeScript. Isso funciona naturalmente em um monorepo (Turborepo, Nx, pnpm workspaces), no qual o servidor e o cliente são pacotes separados que podem importar uns dos outros.

Para um back-end e um front-end totalmente separados, seria necessário publicar os tipos do roteador como um pacote compartilhado. Isso acrescenta uma etapa de publicação, mas continua sem geração de código.

No servidor, defina um roteador e exporte seu tipo: export type AppRouter = typeof appRouter. No cliente, importe esse tipo e crie um cliente tipado: createTRPCReact(). O cliente sabe exatamente quais procedimentos existem e quais são seus tipos de entrada e de saída.

Renomear um procedimento no servidor exibe imediatamente um erro do TypeScript no cliente.

Como o tRPC utiliza diretamente o sistema de tipos do TypeScript, seu editor fornece autocompletar completo para nomes de procedimentos, formatos de entrada e tipos de retorno no cliente. Renomear um procedimento é uma refatoração de renomeação do TypeScript, não uma busca e substituição manual em toda a base de código.

Essa melhoria na experiência de desenvolvimento é, na prática, o recurso mais elogiado do tRPC.

Por padrão, o tRPC utiliza HTTP como transporte. Cada chamada de procedimento é uma solicitação HTTP. O tRPC também oferece suporte a WebSockets para assinaturas. O transporte é um detalhe de implementação; a API do cliente é idêntica independentemente do transporte.

Você também pode expor procedimentos do tRPC como pontos de extremidade REST convencionais usando o adaptador REST, para garantir compatibilidade com clientes que não usam tRPC.

O tRPC funciona como camada intermediária no Express, Fastify e Hono. No Next.js, ele integra-se por meio de manipuladores de rotas de API. O iniciador create-t3-app (T3 Stack) reúne tRPC, Prisma, NextAuth e Tailwind em um modelo de aplicação completa com Next.js.

O T3 Stack é o ponto de partida mais popular para tRPC e demonstra padrões prontos para produção.

Outra abordagem REST com segurança de tipos consiste em definir esquemas Zod, gerar automaticamente uma especificação OpenAPI e gerar tipos TypeScript a partir dessa especificação. Isso fornece um contrato de API que pode ser consumido por clientes que não usam TypeScript.

O tRPC é mais simples, mas exclusivo do TypeScript. OpenAPI+Zod acrescenta complexidade, mas produz um contrato de API pública. Escolha tRPC para comunicação interna de TypeScript para TypeScript; escolha OpenAPI para APIs públicas.

O tRPC não substitui REST quando você precisa de uma API pública consumida por terceiros, clientes móveis que não foram escritos em TypeScript ou parceiros que precisam de um contrato estável e versionado. Ele é voltado especificamente para monorepos TypeScript com segurança de tipos em toda a aplicação.

Entender esse escopo evita adotar o tRPC em contextos nos quais REST ou GraphQL são opções mais adequadas.

A execução de npm create t3-app@latest cria a estrutura inicial de um projeto Next.js com tRPC, Prisma, NextAuth.js, Tailwind CSS e TypeScript pré-configurados. O código gerado demonstra a estrutura do roteador, a criação do contexto e a configuração do cliente.

Estudar essa estrutura inicial é o caminho mais rápido para entender como todas as partes do tRPC se encaixam em uma aplicação real.

Como o tRPC compartilha tipos entre o servidor e o cliente sem gerar código?

O tRPC resolve a divergência de tipos entre o cliente e o servidor TypeScript compartilhando diretamente o tipo TypeScript do roteador por meio de uma importação, eliminando a geração de código. Ele funciona em monorrepositórios e se integra ao Next.js, Express, Fastify e Hono. A T3 Stack (create-t3-app) é o projeto inicial padrão para produção.

O tRPC funciona somente com TypeScript e é mais adequado para aplicações internas de ponta a ponta, não para APIs públicas.