tRPC para TypeScript: guia completo com exemplos

O que é tRPC e para que serve?

tRPC (TypeScript Remote Procedure Call) é uma biblioteca moderna para criar APIs type-safe entre cliente e servidor. A principal característica do tRPC é que ele não requer geração de código ou duplicação de tipos. Você simplesmente escreve funções no servidor, e o cliente obtém acesso a elas com suporte completo do TypeScript — autocompletar, verificação de tipos e IntelliSense.

Ao contrário de REST ou GraphQL, onde você precisa descrever manualmente esquemas, endpoints e tipos, o tRPC infere automaticamente os tipos a partir do seu código do servidor. Isso simplifica radicalmente o desenvolvimento e reduz o número de erros.

Principais vantagens do tRPC:

\n
• Type-safety completa — erros de tipo são detectados em tempo de compilação, não em tempo de execução
\n
• Sem geração de código — não é necessário executar geradores ou sincronizar esquemas
\n
• Boilerplate mínimo — menos código do que em REST ou GraphQL
\n
• Documentação automática — os tipos servem como documentação
\n
• Simplicidade — funciona como uma chamada de função comum
\n

tRPC é ideal para aplicações full-stack em TypeScript (Next.js, Remix, Express, Fastify) e para arquitetura de microsserviços.

Instalação do tRPC

tRPC consiste em vários pacotes. Para uso básico, você precisará de:

# Instalação das partes servidor e cliente\nnpm install @trpc/server @trpc/client\n\n# Instalação do adaptador React (se você usa React)\nnpm install @trpc/react-query @tanstack/react-query\n\n# Instalação do adaptador para Next.js\nnpm install @trpc/next @trpc/react-query @tanstack/react-query\n\n# Instalação do Zod para validação (recomendado)\nnpm install zod

Se você usa yarn ou pnpm:

yarn add @trpc/server @trpc/client\npnpm add @trpc/server @trpc/client

Para desenvolvedores Python (se você usa Python no backend): tRPC é uma biblioteca TypeScript, mas você pode usá-la com Python através do trpc-py (wrapper experimental). No entanto, o ecossistema principal é TypeScript.

Início rápido com exemplo de código

Vamos criar uma aplicação simples: um servidor com procedimentos para trabalhar com usuários e um cliente que os chama.

1. Servidor (server.ts)

import { initTRPC } from '@trpc/server';\nimport { z } from 'zod';\n\n// Criando uma instância do tRPC\nconst t = initTRPC.create();\n\n// Definindo o tipo de usuário\ninterface User {\n  id: number;\n  name: string;\n  email: string;\n}\n\n// Banco de dados fictício\nconst users: User[] = [\n  { id: 1, name: 'Alice', email: 'alice@example.com' },\n  { id: 2, name: 'Bob', email: 'bob@example.com' },\n];\n\n// Criando um roteador com procedimentos\nconst appRouter = t.router({\n  // Procedimento para obter todos os usuários\n  getUsers: t.procedure\n    .query(() => {\n      return users;\n    }),\n\n  // Procedimento para obter um usuário por ID\n  getUserById: t.procedure\n    .input(z.number())\n    .query(({ input }) => {\n      return users.find(user => user.id === input) || null;\n    }),\n\n  // Procedimento para criar um usuário\n  createUser: t.procedure\n    .input(z.object({\n      name: z.string().min(1),\n      email: z.string().email(),\n    }))\n    .mutation(({ input }) => {\n      const newUser: User = {\n        id: users.length + 1,\n        name: input.name,\n        email: input.email,\n      };\n      users.push(newUser);\n      return newUser;\n    }),\n});\n\n// Exportando o tipo do roteador para o cliente\nexport type AppRouter = typeof appRouter;

2. Cliente (client.ts)

import { createTRPCClient, httpBatchLink } from '@trpc/client';\nimport type { AppRouter } from './server';\n\n// Criando o cliente\nconst client