tRPC e a revolucao mais silenciosa do ecossistema TypeScript: APIs type-safe end-to-end sem geracao de codigo, sem schemas duplicados, sem contratos REST. Quando combinado com agentes de IA, o tRPC agentes IA leva a produtividade a outro nivel — Claude Code e Codex geram routers, procedures e middlewares que sao consumidos pelo frontend com tipos 100% inferidos automaticamente. Este tutorial mostra como criar uma API tRPC completa com agentes de IA no Windows 11.
Setup do tRPC com Claude Code
Claude Code configura o tRPC em um projeto Next.js com todo o boilerplate necessario:
Criacao do projeto
claude "Crie um projeto Next.js 16 com tRPC. Inicialize com create-next-app (TypeScript, App Router). Instale: @trpc/server, @trpc/client, @trpc/react-query, @trpc/next, @tanstack/react-query, zod, superjson. Crie a estrutura: src/server/ (router, context, procedures), src/trpc/ (client, provider, server client)."
Estrutura do servidor
claude "Crie os arquivos base do servidor tRPC: - src/server/context.ts: cria o contexto com req, res e sessao do usuario - src/server/trpc.ts: inicializa tRPC com t.init(), define procedure publica e protegida, configura superjson como transformer - src/server/routers/_app.ts: router raiz que agrega todos os sub-routers - src/app/api/trpc/[trpc]/route.ts: Route Handler do Next.js que handle a requisicao tRPC"
Configuracao do cliente
claude "Crie os arquivos do cliente tRPC: - src/trpc/client.ts: cria o cliente tRPC para Server Components - src/trpc/provider.tsx: Provider React Query para Client Components - src/trpc/server-client.ts: cliente para Server Components com cookies"
Routers e procedures com Claude Code
Com o setup pronto, Claude Code cria os routers e procedures — o coracao da API tRPC Claude Code:
Router de tarefas
claude "Crie src/server/routers/task-router.ts com: - Router: taskRouter - Procedures: - list: query que lista tarefas do usuario logado, com filtro opcional por status - getById: query que busca tarefa por ID, verifica se pertence ao usuario - create: mutation que cria tarefa com validacao Zod - update: mutation que atualiza campos, retorna erro se nao encontrar - delete: mutation que deleta tarefa, retorna erro se nao pertencer ao usuario - Use o contexto para acessar o usuario logado - Trate erros com TRPCError"
Router de usuario
claude "Crie src/server/routers/user-router.ts com: - Router: userRouter - Procedures: - me: query que retorna dados do usuario logado (sem senha) - updateProfile: mutation que atualiza nome e avatar - getStats: query que retorna estatisticas (total tasks, tasks por status) - Procedures protegidas (exigem autenticacao) - Select especifico para nao vazar dados sensiveis"
Agregacao dos routers
claude "Atualize src/server/routers/_app.ts para agregar: - taskRouter em 'task' - userRouter em 'user' - Exporte type AppRouter para o frontend consumir"
Schemas de validacao com Codex e Zod
No tRPC, as validacoes sao feitas com Zod diretamente nas procedures. Codex e excelente para gerar esses schemas:
Schemas de tarefa
opencode "Crie src/server/schemas/task-schema.ts com schemas Zod:
- createTaskSchema: titulo (string min 3 max 200), descricao (string optional),
prioridade (number int min 1 max 3 optional default 2)
- updateTaskSchema: todos campos opcionais, pelo menos um presente
- taskQuerySchema: status (enum optional), page (number optional default 1),
pageSize (number optional default 10)
- taskIdSchema: id (string uuid)
Exporte os tipos inferidos: type CreateTaskInput = z.infer<>"
Schemas de usuario
opencode "Crie src/server/schemas/user-schema.ts: - updateProfileSchema: name (string 3-100 optional), avatar (string url optional) - loginSchema: email (email valido), password (string min 8) - registerSchema: name (string 3-100), email, password (min 8, 1 number, 1 uppercase), confirmPassword (refine para igualar password)"
Com schemas definidos uma unica vez no servidor, o frontend herda os tipos automaticamente — sem duplicacao, sem inconsistencia.
Middleware de autenticacao
tRPC permite criar middlewares reutilizaveis. Claude Code configura a autenticacao:
Middleware isAuthenticated
claude "Crie um middleware isAuthenticated em src/server/trpc.ts:
- Verifica se ctx.user existe (colocado pelo contexto no login)
- Se nao existir, lanca TRPCError code UNAUTHORIZED
- Se existir, prossegue com next({ ctx: { user } })
- Crie a procedure protegida: protectedProcedure = publicProcedure.use(isAuthenticated)
Use protectedProcedure em todas as rotas que exigem login."
Contexto com autenticacao
claude "Atualize src/server/context.ts para:
- Extrair token JWT do header Authorization ou cookie
- Verificar e decodificar o token
- Buscar usuario no banco pelo ID do token
- Retornar { user, session } no contexto
- Se token invalido ou ausente, user = null (nao lancar erro aqui)"
Integracao com React Query
A magia do tRPC acontece quando o frontend consome as procedures com tipos inferidos automaticamente. Codex gera os hooks React Query:
Hooks de tarefa
opencode "Crie hooks tRPC em componentes React:
- useTaskList(status?): usa trpc.task.list.useQuery() com filtro
- useTask(id): usa trpc.task.getById.useQuery({ id }) com enabled quando id existe
- useCreateTask(): usa trpc.task.create.useMutation() com onSuccess invalidando list
- useUpdateTask(): usa trpc.task.update.useMutation() com onSuccess
- useDeleteTask(): usa trpc.task.delete.useMutation() com onSuccess
Todos os hooks sao type-safe — tipagem inferida do servidor."
Componente de lista
opencode "Crie src/components/TaskList.tsx com os hooks tRPC: - useTaskList() para buscar tarefas - Loading state enquanto carrega - Empty state quando nao ha tarefas - Lista com TaskCard para cada tarefa - Botao de deletar que chama useDeleteTask - Atualizacao em tempo real com invalidation"
O resultado e um frontend que consome a API com tipos perfeitos — se o servidor mudar o schema, o TypeScript acusa erro no frontend na compilacao.
Exemplo pratico: App full-stack com tRPC
Vamos unir tudo em um app funcional com tRPC, Prisma e Next.js.
Estrutura completa
claude "Crie a estrutura completa do app: - src/server/context.ts: contexto com autenticacao - src/server/trpc.ts: procedimentos publico e protegido - src/server/schemas/: schemas Zod - src/server/routers/: routers de tarefas e usuarios - src/trpc/: cliente e provider React Query - src/app/page.tsx: landing page - src/app/dashboard/page.tsx: dashboard com lista - src/components/TaskList.tsx: lista com queries tRPC - src/components/CreateTaskForm.tsx: formulario com mutation tRPC - prisma/schema.prisma: modelos do banco"
Com Claude Code e Codex orquestrados, voce tem um app full-stack com tRPC — tipo seguro do banco ao frontend, sem duplicacao de tipos, sem geracao de codigo, sem contratos REST.
FAQ — Perguntas Frequentes
tRPC substitui REST ou GraphQL?
tRPC nao substitui — e uma alternativa. Ele e ideal para projetos full-stack TypeScript onde frontend e backend sao mantidos pela mesma equipe. Para APIs publicas consumidas por clientes externos, REST ou GraphQL ainda sao mais adequados.
Preciso configurar esquemas de validacao separados no frontend e backend?
Nao. Com tRPC, voce define os schemas de validacao (geralmente com Zod) uma unica vez no backend, e o frontend herda os tipos automaticamente. Claude Code e Codex geram esses schemas no backend, e o frontend os consome sem duplicacao.
Claude Code e Codex conhecem tRPC v11?
Sim. Ambos conhecem a sintaxe do tRPC v11, incluindo a nova API com createTRPCRouter, publicProcedure, protectedProcedure, middleware e merged routers.
tRPC funciona com Next.js Server Components?
Sim. tRPC v11 tem suporte a Server Components. Claude Code pode configurar o tRPC para funcionar tanto em Server Components (chamadas diretas) quanto em Client Components (via tRPC React Query).
Vale a pena usar tRPC para projetos pequenos?
Sim. Para projetos pequenos e MVPs, tRPC e ainda mais vantajoso porque elimina a necessidade de definir rotas REST, serializacao manual e tipos duplicados. O ganho de produtividade e perceptivel desde a primeira procedure.
Comece com tRPC e agentes hoje
tRPC agentes IA e a combinacao mais type-safe do ecossistema TypeScript. Com Claude Code para routers, procedures e middlewares, e Codex para schemas Zod e hooks React Query, voce cria APIs completas com tipos inferidos automaticamente — sem duplicacao, sem erros de compatibilidade.
O Orquestra no Windows 11 e o ambiente ideal para esse workflow — conecte Claude Code e Codex no mesmo canvas, com o servidor tRPC rodando em um terminal e o frontend Next.js em outro.
Baixe o Orquestra para Windows 11 e comcece seu teste gratis de 7 dias.
Links internos recomendados
- APIs REST com Agentes de IA — comparacao entre REST e tRPC
- Prisma ORM com Agentes de IA — ORM usado no backend tRPC
- Next.js 16 com Agentes de IA — frontend ideal para tRPC
Links externos recomendados
- tRPC Documentation — documentacao oficial do tRPC
- Zod Documentation — biblioteca de validacao de schemas
- TanStack React Query — gerenciamento de estado servidor
Pronto para orquestrar seus agentes?
Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Gratis por 7 dias.