tRPC Fundamentos: Guia Completo
Domine os conceitos essenciais do tRPC: type safety automático, eliminação de bugs de produção e desenvolvimento 3x mais rápido. Primeira implementação prática passo a passo.
🎯 O que é tRPC e Por que Usar?
🎯 Por que tRPC é fundamental para devs full-stack?
Problema atual: APIs REST geram dessincronia entre frontend e backend. Mudanças na API quebram o frontend silenciosamente.
Solução tRPC: Type safety end-to-end. Erros detectados em tempo de compilação, não em produção.
⚠️ Conceitos Fundamentais para Entender
Type Safety: Garantia de que os tipos definidos no backend sejam automaticamente disponíveis no frontend.
RPC (Remote Procedure Call): Chamada de função remota como se fosse local, com tipos preservados.
Inferência de Tipos: TypeScript deduz automaticamente os tipos sem necessidade de definições manuais.
React Query: Gerenciamento de estado server-side com cache, invalidação e sincronização automática.
✅ Vantagens do tRPC sobre REST/GraphQL
Zero Boilerplate
Não precisa gerar SDKs, escrever schemas ou manter documentação separada.
DX Excepcional
Autocompletar perfeito, refatoração segura e detecção de erros em tempo real.
Type Safety End-to-End
Mudanças no backend são refletidas instantaneamente no frontend.
Performance Otimizada
Apenas os dados necessários são transferidos, com cache inteligente.
🔍 REST vs tRPC: Comparação Prática
❌ REST Tradicional
// Backend
app.get('/users/:id', async (req, res) => {
const user = await getUser(req.params.id);
res.json(user);
});
// Frontend
const response = await fetch('/users/123');
const user = await response.json();
// user é 'any' - sem type safety!✅ tRPC
// Backend
const userRouter = router({
getUser: publicProcedure
.input(z.string())
.query(({ input }) => getUser(input))
});
// Frontend
const user = trpc.user.getUser.useQuery("123");
// user é tipado automaticamente!🎯 Quando usar tRPC?
Aplicações Full-Stack TypeScript:Quando você controla tanto frontend quanto backend.
Projetos com React Query:Perfeita integração com gerenciamento de estado server-side.
Equipes pequenas/médias:Onde a comunicação entre frontend e backend é frequente.
Evite quando:Já tem API REST estabelecida ou precisa de cache HTTP complexo.
🛠️ Primeira API tRPC: Tutorial Prático
1. Definindo o Router no Backend
Criar o primeiro router tRPC com uma query simples
// 📁 server/trpc/router.ts
import { z } from 'zod';
import { router, publicProcedure } from './trpc';
// 🎯 Router principal da aplicação
export const appRouter = router({
// 🔍 Query para buscar usuário por ID
getUser: publicProcedure
.input(z.string()) // ⚡ Validação automática com Zod
.query(async ({ input }) => {
// 💾 Buscar usuário no banco (simulado)
const user = {
id: input,
name: 'João Silva',
email: 'joao@example.com',
createdAt: new Date()
};
console.log('🔐 Buscando usuário:', input);
return user; // ✅ Retorno tipado automaticamente
}),
// 📝 Mutation para criar usuário
createUser: publicProcedure
.input(z.object({
name: z.string(),
email: z.string().email()
}))
.mutation(async ({ input }) => {
// 🌐 Criar usuário no banco
const newUser = {
id: Math.random().toString(36),
...input,
createdAt: new Date()
};
console.log('✅ Usuário criado:', newUser);
return newUser;
})
});
// 🎯 Exportar tipo do router para o frontend
export type AppRouter = typeof appRouter;🧠 Pontos Importantes desta Implementação
Type Safety Automático:O TypeScript infere todos os tipos do backend para o frontend automaticamente.
Validação com Zod:Entrada validada automaticamente, erros claros se dados inválidos.
React Query Integration:Cache, loading states e error handling gerenciados automaticamente.
Developer Experience:Autocompletar, refatoração segura e detecção de erros em tempo real.
🛠️ Live mode
🔴 Live Demo: tRPC em Ação
Esta demonstração usa a configuração tRPC real do projeto. Todas as operações são type-safe e funcionam em tempo real.
Buscar Usuário por ID
Criar Novo Usuário
🔍 O que está acontecendo aqui?
Query: trpc.user.get.useQuery() busca usuário automaticamente
Mutation: trpc.user.create.useMutation() cria usuário com validação
Type Safety: Todos os tipos são inferidos automaticamente do backend
Estados: Loading, error e success gerenciados pelo React Query
📋 Resumo da Aula
✅ O que Você Conquistou Nesta Aula
Entendimento Sólido do tRPC
Você compreende o que é tRPC, seus benefícios e quando usar.
Primeira API Funcionando
Implementou um exemplo completo de query e mutation com type safety.
Integração React Query
Domina como usar tRPC com React Query para gerenciar estado server-side.
Type Safety End-to-End
Experimenta na prática como mudanças no backend refletem no frontend.
🚀 Próximos Passos
Aula 2: Configuração Avançada
Setup completo de projeto com Next.js, configurações de desenvolvimento e produção.
Aula 3: Roteamento e Organização
Como organizar routers complexos, aninhamento e melhores práticas.
Aula 4: Validação com Zod
Validação avançada de entrada, transformações e mensagens de erro customizadas.
💪 Desafio Prático
Agora é sua vez de praticar! Implemente uma API tRPC com as seguintes funcionalidades:
- • getPosts - listar todos os posts
- • getPost - buscar post por ID
- • createPost - criar novo post
- • updatePost - atualizar post existente
- • deletePost - deletar post
- • Título obrigatório (mín. 3 caracteres)
- • Conteúdo obrigatório (mín. 10 caracteres)
- • Autor obrigatório
- • Data de criação automática
- • Lista de posts com paginação
- • Formulário de criação
- • Botão de edição inline
- • Confirmação de exclusão
🎯 Checkpoint de Progresso
Você agora tem as bases sólidas para construir aplicações full-stack type-safe com tRPC.