tRPC Full-Stack

Visão Geral

tRPC permite que você crie APIs totalmente seguras por tipo sem escrever um esquema ou etapa de geração de código. Seus tipos TypeScript fluem do roteador do servidor diretamente para o cliente — assim, cada chamada de API tem autocompletar, validação em tempo de compilação e é segura para refatoração. Use essa habilidade ao construir monorepos TypeScript, aplicativos Next.js ou qualquer projeto onde o servidor e o cliente compartilham uma base de código.

Quando Usar Esta Habilidade

• Use ao construir um aplicativo full-stack TypeScript (Next.js, Remix, Express + React) onde o cliente e o servidor compartilham um único repositório
• Use quando quiser segurança de ponta a ponta em chamadas de API sem a sobrecarga de esquema REST/GraphQL
• Use ao adicionar recursos em tempo real (assinaturas) a uma configuração tRPC existente
• Use ao projetar middleware de várias etapas (autenticação, limitação de taxa, escopo de locatário) em procedimentos tRPC
• Use ao migrar uma API REST/GraphQL existente para tRPC incrementalmente

Conceitos Principais

Roteadores e Procedimentos

Um roteador agrupa procedimentos relacionados (pense: endpoints). Procedimentos são funções tipadas — query para leituras, mutation para escritas, subscription para fluxos em tempo real.

Validação de Entrada com Zod

Todas as entradas de procedimento são validadas com esquemas Zod. A entrada validada e tipada está disponível no manipulador de procedimento — sem análise manual.

Contexto

context é um estado compartilhado passado para cada procedimento — sessão de autenticação, cliente de banco de dados, cabeçalhos de solicitação, etc. Ele é construído uma vez por solicitação em uma fábrica de contexto. Importante: O App Router e o Pages Router do Next.js exigem fábricas de contexto separadas porque os manipuladores do App Router recebem um fetch Request, não um Node.js NextApiRequest.

Middleware

Cadeias de middleware são executadas antes de um procedimento. Use-as para autenticação, log e enriquecimento de solicitação. Elas podem estender o contexto para procedimentos subsequentes.

Como Funciona

Etapa 1: Instalar e Inicializar

npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod

Crie a instância tRPC e os construtores reutilizáveis:

// src/server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { type Context } from './context';
import { ZodError } from 'zod';

const t = initTRPC.context<Context>().create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    };
  },
});

export const router = t.router;
export const publicProcedure = t.procedure;
export const middleware = t.middleware;

Etapa 2: Definir Duas Fábricas de Contexto

Os manipuladores do App Router do Next.js recebem um fetch Request (não um Node.js NextApiRequest), portanto, o contexto deve ser construído de forma diferente dependendo do local da chamada. Defina uma fábrica por superfície:

// src/server/context.ts
import { type FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';
import { auth } from '@/server/auth'; // Next-Auth v5 / your auth helper
import { db } from './db';

/**
 * Context for the HTTP handler (App Router Route Handler).
 * `opts.req` is the fetch Request — auth is resolved server-side via `auth()`.
 */
export async function createTRPCContext(opts: FetchCreateContextFnOptions) {
  const session = await auth(); // server-side auth — no req/res needed
  return { session, db, headers: opts.req.headers };
}

/**
 * Context for direct server-side callers (Server Components, RSC, cron jobs).
 * No HTTP request is involved, so we call auth() directly from the server.
 */
export async function createServerContext() {
  const session = await auth();
  return { session, db };
}

export type Context = Awaited<ReturnType<typeof createTRPCContext>>;

Etapa 3: Criar um Middleware de Autenticação e um Procedimento Protegido

// src/server/trpc.ts (continued)
const enforceAuth = middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: {
      // Narrows type: session is non-null from here
      session: { ...ctx.session, user: ctx.session.user },
    },
  });
});

export const protectedProcedure = t.procedure.use(enforceAuth);

Etapa 4: Criar Roteadores

// src/server/routers/post.ts
import { z } from 'zod';
import { router, publicProcedure, protectedProcedure } from '../trpc';
import { TRPCError } from '@trpc/server';

export const postRouter = router({
  list: publicProcedure
    .input(
      z.object({

…