Para que é usado o middleware do Next.js?

Question

Accepted Answer

**Middleware** é código que executa **antes de uma solicitação ser concluída** — na Edge, antes da página ou manipulador de rota ser renderizado. Ele permite inspecionar e reescrever/redirecionar solicitações, definir cabeçalhos ou verificar autenticação para muitas rotas em um único lugar.

## Definindo middleware

```ts
// middleware.ts (at the project root)
import { NextRequest, NextResponse } from "next/server";

export function middleware(req: NextRequest) {
  const token = req.cookies.get("session")?.value;

// protect /dashboard — redirect unauthenticated users to login
  if (req.nextUrl.pathname.startsWith("/dashboard") && !token) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
  return NextResponse.next(); // allow the request to proceed
}

// only run on these paths (performance — don't run on every asset)
export const config = { matcher: ["/dashboard/:path*", "/account/:path*"] };
```

## O que o middleware pode fazer

```ts
NextResponse.redirect(url);          // send the user elsewhere (auth gates)
NextResponse.rewrite(url);           // serve different content, URL unchanged (A/B, i18n)
NextResponse.next();                  // continue, optionally with modified headers
// req.geo / req.cookies / req.headers — inspect location, auth, etc.
```

Usos comuns: **autenticação**, **redirecionamentos** (baseados em localidade/localização geográfica, www→apex), **testes A/B** via reescritas, definição de **cabeçalhos de segurança** e flags de bot/recurso.

## Restrições principais

```text
⚠️ Runs on the EDGE runtime → no Node.js APIs (no fs, limited libraries)
⚠️ Must be FAST — it runs before every matched request; heavy work adds latency
⚠️ Can't access the database directly for complex auth — do lightweight checks
   (e.g. verify a JWT/cookie exists); do full auth in the page/handler
```

A configuração `matcher` é importante: limite o middleware apenas às rotas que precisam dele, para que não execute em ativos estáticos e não deixe tudo mais lento.

## Por que isso importa

Middleware é o único ponto de controle para lógica de solicitação transversal — redirecionamentos de autenticação, roteamento de localidade, reescritas e cabeçalhos — aplicados em muitas rotas sem repetir código em cada página.

Conhecer suas restrições de Edge (rápido, sem APIs Node, apenas verificações leves) e o escopo do `matcher` é o que permite usá-lo corretamente para preocupações com gatekeeping e roteamento.