A Arquitetura tRPC
Entenda como o tRPC elimina a duplicação de esquemas de API.
A Arquitetura tRPC é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.
O problema de ponta a ponta
Em um aplicativo web típico, o servidor define uma API e o cliente a chama. Manter os tipos sincronizados é difícil: altere um campo no servidor e o cliente falhará silenciosamente em tempo de execução. O tRPC resolve isso compartilhando os tipos diretamente, sem geração de código.
// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they driftO que é tRPC
tRPC é uma biblioteca para construir APIs totalmente tipadas em TypeScript. O servidor define procedimentos; o cliente os chama como se fossem funções locais, com preenchimento automático completo e verificação de tipos inferida a partir do código do servidor.
// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the serverSem geração de código
Diferentemente dos fluxos de trabalho de GraphQL ou OpenAPI, o tRPC não precisa de uma etapa de geração de código. Não há arquivo de esquema para compilar nem cliente gerado. Os tipos fluem do servidor para o cliente exclusivamente por meio da inferência do TypeScript no tempo de compilação.
// No .graphql files, no generated SDK
// Just import a type from the server packageO roteador é o contrato
O centro do tRPC é o roteador. Ele é uma árvore de procedimentos, como consultas e mutações. O objeto roteador no servidor, especificamente seu tipo inferido, é a única fonte de verdade compartilhada com o cliente.
// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contractComo os tipos são compartilhados
O servidor exporta apenas o tipo do seu roteador, não a implementação. O client importa esse tipo e o usa para tipar um client intermediário. Nenhum código do servidor é enviado ao navegador; apenas os tipos, que são apagados no momento da compilação.
// server.ts
export type AppRouter = typeof appRouter;
// client.ts
import type { AppRouter } from '../server';Query e mutation
Os procedimentos vêm em dois tipos principais. Uma query lê dados e normalmente é idempotente. Uma mutation altera dados. Essa distinção corresponde ao armazenamento em cache e à semântica HTTP, além de definir como o client as chama.
// client.user.list.query() -> read
// client.user.create.mutate(...) -> writeExecução versus tipos
O tRPC tem duas camadas. Em tempo de execução, as chamadas são feitas como JSON sobre HTTP e tratadas por um adaptador. Em tempo de compilação, o tipo compartilhado AppRouter verifica completamente cada chamada. A execução é enxuta; a segurança de tipos é o valor.
// Runtime: POST /trpc/user.byId body: {"input":1}
// Types: client.user.byId.query(1) is checked end to endPor que a inferência é melhor que a geração de código
Como os tipos são inferidos, não há uma etapa de sincronização que possa ser esquecida. Edite um procedimento, e o client refletirá imediatamente a alteração, exibindo sublinhados vermelhos onde as chamadas não corresponderem mais. O feedback é instantâneo e aparece no seu editor.
// Add a required input field on the server
// -> every client call missing it becomes a type errorOnde o tRPC se encaixa
O tRPC se destaca em monorrepositórios TypeScript de ponta a ponta, nos quais client e servidor compartilham uma base de código, como em aplicações Next.js. Ele não se destina a APIs públicas consumidas por outras linguagens; nesses casos, você ainda precisa de um esquema independente de linguagem, como OpenAPI ou GraphQL.
// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumersVisão geral
O fluxo é: definir procedimentos em um roteador, exportar o tipo do roteador, conectar um adaptador HTTP e criar um client tipado a partir desse tipo. Cada chamada é verificada em relação ao contrato do servidor, sem nenhum código gerado. As próximas lições desenvolvem cada parte.
// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for authConfie no compilador
A mudança de mentalidade é a seguinte: o contrato da API está nos tipos, aplicados pelo compilador, e não apenas na documentação ou na validação em tempo de execução. Se o código compila, client e servidor estão de acordo. É isso que significa "segurança de tipos de ponta a ponta".
// If client.ts compiles, it matches the current server.Verificação rápida
Teste sua compreensão da arquitetura do tRPC.
Recapitulação
Você aprendeu o modelo do tRPC.
- O roteador é o contrato; seu tipo é a única fonte de verdade.
- O servidor exporta apenas o tipo
AppRouter, não o código. - Uma query lê, uma mutation escreve; a execução usa JSON sobre HTTP.
- A segurança de tipos vem da inferência, sem uma etapa de geração de código.
Próximo: definir roteadores e procedimentos.
Perguntas Frequentes
A aula “A Arquitetura tRPC” é grátis?
Sim — o texto completo de “A Arquitetura tRPC” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.
O que vou aprender em “A Arquitetura tRPC”?
Entenda como o tRPC elimina a duplicação de esquemas de API. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “A Arquitetura tRPC”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- A Arquitetura tRPC
- Definindo Roteadores e Procedimentos
- Inferência de Tipos entre Cliente e Servidor
- Middleware e Contexto