Um desenvolvedor passou duas semanas substituindo uma API REST por tRPC em uma ferramenta interna.

Por que a mudança foi importante

A stack antiga nos obrigava a manter um DTO, um validador e um conjunto separado de tipos TypeScript para o frontend. Renomeie um campo no backend e a API ainda retornava 200, a UI continuava renderizando e o bug aparecia apenas como valores “undefined”. Um cliente percebeu o problema antes de qualquer pessoa da equipe. Os contratos REST escondiam o problema, e os arquivos extras adicionavam uma manutenção que nunca valia a pena.

Como era a configuração REST

  • OpenAPI spec – um arquivo estático que descrevia os endpoints, mas nunca servia como a única fonte de verdade.
  • Etapa de geração de Client SDK – um job de CI que produzia um wrapper JavaScript.
  • Postman collection – um artefato de teste compartilhado que ninguém usava.
  • Interfaces TypeScript manuais – tipos escritos à mão que precisavam estar em sincronia com o servidor.

Cada mudança na API afetava pelo menos três desses artefatos, além do validador e de quaisquer chamadas de fetch subsequentes. O processo era propenso a erros e lento.

Como o tRPC enxugou a base de código

O tRPC elimina o arquivo de contrato separado. O servidor exporta um tipo de roteador; o cliente importa esse mesmo tipo. Renomeie um campo no backend e o editor sinaliza a incompatibilidade instantaneamente — sem precisar rodar o código ou esperar uma requisição falhar. O desenvolvedor removeu:

  • O arquivo da OpenAPI spec.
  • A etapa de geração de Client SDK.
  • A Postman collection não utilizada.
  • A pasta de interfaces TypeScript manuais.

O repositório ficou mais enxuto e o feedback chegou durante o desenvolvimento, em vez de após o deploy.

Limites do tRPC

O tRPC só funciona quando ambas as pontas falam TypeScript. Ele deixa a desejar se:

  • Uma equipe mobile usa Swift ou Kotlin.
  • A API precisa ser consumida por parceiros externos.
  • Você precisa de uma interface pública e agnóstica em relação à linguagem.

O que a migração realmente exigiu

O esforço de duas semanas foi mais do que apenas copiar e colar. O desenvolvedor teve que:

  • Reescrever cada chamada fetch para usar as funções de cliente do tRPC.
  • Ajustar a lógica de tratamento de erros.
  • Atualizar componentes de UI que dependiam de estados de carregamento e tentativa de repetição (retry) vinculados a respostas HTTP brutas.

Perguntas para fazer antes de começar

  • Tanto o frontend quanto o backend usam TypeScript? Sem um sistema de tipos compartilhado, o tRPC perde sua principal vantagem.
  • A mesma equipe é responsável por ambos os lados? Lacunas de responsabilidade podem reintroduzir o descompasso de contratos (contract drift).
  • Você está corrigindo um bug concreto ou seguindo uma tendência? O aumento de produtividade é real, mas deve resolver um problema existente.

Uma abordagem híbrida para 2025

Muitas equipes encontram o ponto ideal executando ambas as stacks:

  • tRPC para camadas de aplicação internas, onde a base de código é totalmente TypeScript e a mesma equipe é dona do servidor e do cliente.
  • REST para webhooks, APIs públicas e integrações com parceiros, onde o acesso agnóstico à linguagem é necessário.

Usar a ferramenta certa para cada superfície mantém o desenvolvimento interno rápido, preservando a abertura necessária para consumidores externos.

Conclusão: Substituir REST por tRPC pode eliminar artefatos de contrato duplicados e expor bugs no momento da edição, mas os ganhos só se materializam quando toda a stack compartilha TypeScript e a equipe consegue absorver o custo da migração. Uma estratégia mista permite colher os benefícios sem excluir consumidores que não usam TypeScript.