O middleware do Next.js fica entre a requisicao de entrada e sua aplicacao. Ele roda antes da pagina renderizar, antes da API route executar, antes de qualquer outra coisa. Isso o torna o ponto de interceptacao mais poderoso de uma aplicacao Next.js.
Como funciona o middleware do Next.js
E um unico arquivo: middleware.ts na raiz do seu projeto. Exporta uma funcao que recebe um NextRequest e deve retornar um NextResponse. Roda no Edge Runtime, nao no Node.js.
Padrao 1: Guards de autenticacao
Em vez de verificar auth em cada componente de pagina ou API route, centralize no middleware. Verifique o token de sessao nos cookies e redirecione para /login se nao existir ou expirou.
Padrao 2: Redirects por geolocalizacao
Quando sua app e implantada na Vercel ou Cloudflare, o edge fornece dados de geolocalizacao automaticamente via request.geo. Voce pode usar para redirects de locale, conteudo regional ou compliance.
Padrao 3: Rate Limiting
Rate limiting no middleware protege suas API routes de abuso antes que o request chegue ao handler. Para deployments distribuidos, use Upstash Rate Limit ou outra solucao Redis compativel com edge.
Padrao 4: A/B Testing com cookies
Middleware pode atribuir usuarios a grupos experimentais antes da pagina renderizar, habilitando A/B testing do lado do servidor sem layout shift.
O que middleware NAO pode fazer
- Sem acesso a banco de dados com drivers nativos
- Sem acesso ao file system
- Sem operacoes de longa duracao
- Nao pode medir o tempo de resposta das suas API routes
Onde instrumentation.ts complementa o middleware
Middleware opera no edge antes do request. O hook de instrumentacao roda no runtime do Node.js quando o servidor inicia. E projetado especificamente para observabilidade: tracing, logging e monitoramento.
Pense no middleware como o porteiro na porta e instrumentacao como as cameras de seguranca dentro. Voce precisa dos dois para o panorama completo.
Registrando OpenTelemetry em instrumentation.ts (por exemplo com registerOTel do @vercel/otel) cada rota fica rastreada, e você acompanha tempos de resposta, taxa de erros e status codes no backend de observabilidade que já usa.
Um alerta: se o middleware é sua única camada de auth, uma falha no matcher ou um bypass deixa rotas abertas. Cheque auth de novo dentro dos handlers sensíveis. O pentester com IA da Nurbak escaneia seu repo em busca de endpoints sem checagem de auth e outros bugs exploráveis, e pode abrir um PR com a correção. Seu primeiro scan é grátis.