Middleware

Q: Onde vai o arquivo middleware.ts?

Na raiz do projeto, ao lado do diretório app/ ou src/. Existe apenas um arquivo middleware.ts por projeto. Você não pode ter arquivos de middleware por rota.

Q: Qual runtime o middleware usa e quais são as limitações?

Middleware executa no Edge Runtime APIs do Node.js como fs, path e a maioria dos pacotes npm não estão disponíveis Você só pode usar APIs da Web Você não pode acessar o corpo da requisição Você não pode renderizar componentes React

Q: Armadilha: Como evitar loops infinitos de redirecionamento no middleware?

Se você redireciona /login para /en/login e o middleware também corresponde a /en/login, você obtém um loop infinito. Exclua os caminhos de destino do matcher ou adicione verificações condicionais para pular caminhos já processados.

Q: Qual a diferença entre NextResponse.redirect e NextResponse.rewrite?

redirect() envia uma resposta de redirecionamento (302 por padrão, 301 para permanente) e altera a URL do navegador rewrite() serve o conteúdo de uma rota diferente sem alterar a URL do navegador

Q: Cookies definidos no middleware estão disponíveis em Server Components?

Sim. Cookies definidos no middleware estão disponíveis via cookies() de next/headers em Server Components.

Q: Como lidar com lógicas diferentes para rotas diferentes em um único arquivo de middleware?

Use verificações condicionais em request.nextUrl.pathname dentro da função de middleware, já que você só pode ter um arquivo de middleware.

Q: Quais propriedades estão disponíveis em NextRequest?

request.nextUrl -- URL analisada com pathname e searchParams request.cookies -- Instância de RequestCookies request.headers -- objeto Headers padrão request.geo -- cidade, país, região (apenas Vercel) request.ip -- IP do cliente (apenas Vercel)

Q: Armadilha: NextResponse.next() interrompe a função de middleware?

Não. O código após NextResponse.next() ainda é executado. Se você quiser parar o processamento, deve explicitamente return a resposta.

Q: Quando usar redirecionamentos de middleware vs. redirecionamentos de next.config.js?

Use redirecionamentos de next.config.js para regras estáticas que não precisam de lógica em tempo de execução Use redirecionamentos de middleware quando precisar de lógica condicional baseada em cookies, cabeçalhos ou outros dados de requisição

Middleware executa antes de cada requisição correspondente, permitindo redirecionamentos, reescritas, modificações de cabeçalho e verificações de autenticação na edge.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// middleware.ts (raiz do projeto, mesmo nível de app/)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(request: NextRequest) {
  // Redireciona, reescreve ou modifica cabeçalhos
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

Quando usar: Guardas de autenticação, detecção de idioma, testes A/B, redirecionamentos e qualquer lógica em nível de requisição que precise ser executada antes da renderização.

Exemplo de Trabalho

// middleware.ts - Guarda de autenticação com detecção de idioma
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
const protectedPaths = ["/dashboard", "/settings", "/billing"];
const defaultLocale = "en";
const supportedLocales = ["en", "fr", "de", "es"];
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // 1. Detecção de idioma - redireciona se não houver prefixo de idioma
  const pathnameHasLocale = supportedLocales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
 
  if (!pathnameHasLocale) {
    const locale =
      request.headers.get("accept-language")?.split(",")[0]?.split("-")[0] ?? defaultLocale;
    const detectedLocale = supportedLocales.includes(locale) ? locale : defaultLocale;
 
    return NextResponse.redirect(
      new URL(`/${detectedLocale}${pathname}`, request.url)
    );
  }
 
  // 2. Verificação de autenticação - redireciona usuários não autenticados
  const isProtected = protectedPaths.some((path) =>
    pathname.includes(path)
  );
  const token = request.cookies.get("session-token")?.value;
 
  if (isProtected && !token) {
    const loginUrl = new URL("/en/login", request.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }
 
  // 3. Adiciona cabeçalhos personalizados
  const response = NextResponse.next();
  response.headers.set("x-pathname", pathname);
  return response;
}
 
export const config = {
  matcher: [
    // Corresponde a todos os caminhos, exceto arquivos estáticos e internos do Next.js
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

// middleware.ts - Mapa simples de redirecionamentos
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
const redirects: Record<string, string> = {
  "/old-blog": "/blog",
  "/docs/v1": "/docs",
  "/legacy-api": "/api/v2",
};
 
export function middleware(request: NextRequest) {
  const redirect = redirects[request.nextUrl.pathname];
  if (redirect) {
    return NextResponse.redirect(new URL(redirect, request.url), 301);
  }
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/old-blog", "/docs/v1", "/legacy-api"],
};

Mergulho Profundo

Como Funciona

Middleware executa em cada requisição correspondente antes que o manipulador de rota ou a página seja renderizado. Ele executa no Edge Runtime por padrão.
Existe apenas um arquivo middleware.ts por projeto. Ele deve estar na raiz (ao lado de app/ ou src/). Você não pode ter arquivos de middleware por rota.
A configuração matcher filtra quais rotas acionam o middleware. Sem um matcher, o middleware executa em todas as requisições, incluindo ativos estáticos.
NextResponse.next() continua para a rota correspondente. Você pode modificar cabeçalhos de requisição/resposta ao passar.
NextResponse.redirect(url) envia uma resposta de redirecionamento (302 por padrão, passe 301 para permanente).
NextResponse.rewrite(url) serve o conteúdo de outra rota sem alterar a URL do navegador.
Middleware executa no Edge Runtime. APIs do Node.js como fs, path e a maioria dos pacotes npm não estão disponíveis. Use apenas APIs da Web.
Middleware pode ler e definir cookies. Use request.cookies.get() e response.cookies.set() para gerenciamento de sessão.
Middleware não pode renderizar componentes React. Ele opera no nível HTTP, antes que qualquer renderização React ocorra.

Variações

// Teste A/B baseado em reescrita
export function middleware(request: NextRequest) {
  const bucket = request.cookies.get("ab-bucket")?.value;
  const response = NextResponse.next();
 
  if (!bucket) {
    const newBucket = Math.random() > 0.5 ? "a" : "b";
    response.cookies.set("ab-bucket", newBucket, { maxAge: 60 * 60 * 24 * 30 });
  }
 
  const currentBucket = bucket ?? "a";
  if (request.nextUrl.pathname === "/pricing") {
    return NextResponse.rewrite(
      new URL(`/pricing/${currentBucket}`, request.url)
    );
  }
 
  return response;
}

// Limitação de taxa com cabeçalhos
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith("/api/")) {
    const ip = request.headers.get("x-forwarded-for") ?? "unknown";
    // Verifica limite de taxa (usando armazenamento externo como Upstash Redis)
    // Isto é pseudocódigo - use @upstash/ratelimit em produção
    const response = NextResponse.next();
    response.headers.set("X-RateLimit-Limit", "100");
    return response;
  }
  return NextResponse.next();
}

// Padrões de matcher
export const config = {
  matcher: [
    "/dashboard/:path*",          // /dashboard e todos os sub-caminhos
    "/api/:path*",                // Todas as rotas de API
    "/blog/:slug",                // Segmento dinâmico único
    "/((?!_next|static|api).*)",  // Tudo exceto _next, static, api
  ],
};

Notas TypeScript

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
// Assinatura da função de middleware
export function middleware(request: NextRequest): NextResponse | Response | undefined;
 
// NextRequest estende a API Web Request
// Propriedades chave:
//   request.nextUrl      - URL analisada com pathname, searchParams
//   request.cookies      - Instância de RequestCookies
//   request.headers      - objeto Headers padrão
//   request.geo          - { city, country, region } (apenas Vercel)
//   request.ip           - IP do cliente (apenas Vercel)
 
// Tipo de configuração
export const config: {
  matcher: string | string[];
};

Armadilhas

Apenas um arquivo de middleware por projeto. Se você precisar de lógicas diferentes para rotas diferentes, use verificações condicionais em request.nextUrl.pathname dentro de uma única função de middleware.
Middleware executa no Edge Runtime. Você não pode usar APIs específicas do Node.js. Bibliotecas como bcrypt, fs ou drivers de banco de dados não funcionarão - use alternativas compatíveis com edge.
Middleware também executa em ativos estáticos a menos que você use um matcher. Sempre configure um matcher para evitar execução desnecessária.
Loops infinitos de redirecionamento são fáceis de criar. Se você redireciona /login para /en/login e o middleware também corresponde a /en/login, você obtém um loop. Exclua os caminhos de destino do matcher.
NextResponse.next() não interrompe a execução. Outra lógica de middleware após ele ainda é executada. Retorne antecipadamente se necessário.
Cookies definidos no middleware estão disponíveis em Server Components via cookies() de next/headers.
Reescritas são invisíveis para o cliente. A URL do navegador permanece a mesma, mas o servidor renderiza uma rota diferente. Isso pode confundir a navegação do lado do cliente se não for tratado com cuidado.
Middleware não pode acessar o corpo da requisição. Ele opera apenas em cabeçalhos, cookies e URL.

Alternativas

Abordagem	Quando Usar
`next.config.js` redirects	Regras de redirecionamento estáticas que não precisam de lógica em tempo de execução
`next.config.js` rewrites	Regras de reescrita estáticas sem lógica condicional
`redirect()` em nível de rota	Redirecionar dentro de um Server Component após verificações de dados
Server Actions com autenticação	Proteger mutações em vez de rotas
Guardas de autenticação em nível de layout	Verificar autenticação em um layout e redirecionar

Exemplo do Mundo Real

De uma aplicação SaaS Next.js 15 / React 19 em produção (SystemsArchitect.io).

// Exemplo de produção: Middleware com reescritas, redirecionamentos, atualização de sessão e proteção de administrador
// Arquivo: middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { updateSession } from '@/utils/supabase/middleware';
 
const legacyRedirects: Record<string, string> = {
  '/old-docs': '/docs',
  '/blog/legacy-post': '/articles',
  '/pricing-old': '/pricing',
};
 
export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // 1. Reescrita de docs: serve /docs/[section] de uma rota interna diferente
  if (pathname.startsWith('/docs/')) {
    const url = request.nextUrl.clone();
    url.pathname = `/docs-internal${pathname.replace('/docs', '')}`;
    return NextResponse.rewrite(url);
  }
 
  // 2. Redirecionamentos legados (permanente 301)
  const redirect = legacyRedirects[pathname];
  if (redirect) {
    return NextResponse.redirect(new URL(redirect, request.url), 301);
  }
 
  // 3. Atualização de sessão - mantém a sessão de autenticação Supabase ativa
  const response = await updateSession(request);
 
  // 4. Proteção de rota de administrador
  if (pathname.startsWith('/admin')) {
    const session = request.cookies.get('sb-access-token')?.value;
    if (!session) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }
 
  return response;
}
 
export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

O que isso demonstra em produção:

A ordem de execução importa. As reescritas são executadas primeiro, depois os redirecionamentos legados, depois a atualização da sessão e, por fim, a proteção do administrador. Se você verificar a autenticação antes da reescrita, o usuário pode acessar a rota errada.
O código de status 301 nos redirecionamentos legados informa aos mecanismos de busca que a mudança é permanente. Usar o 302 padrão preservaria a URL antiga nos índices de pesquisa.
updateSession(request) é uma utilidade do Supabase que atualiza o cookie de sessão de autenticação a cada requisição. Isso evita que a sessão expire enquanto o usuário está navegando ativamente.
A regex do matcher /((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*) exclui ativos estáticos e imagens do processamento do middleware. Sem isso, o middleware seria executado em cada requisição de imagem e arquivo CSS, adicionando latência desnecessária.
A proteção de administrador verifica um cookie em vez de fazer uma chamada ao banco de dados. O middleware é executado no Edge Runtime, onde drivers de banco de dados não estão disponíveis. Verificações completas de autorização ocorrem em Server Components ou rotas de API.
Existe apenas um arquivo middleware.ts por projeto. Toda a lógica específica da rota deve ser tratada com verificações condicionais em pathname.

FAQs

Onde vai o arquivo middleware.ts?

Na raiz do projeto, ao lado do diretório app/ ou src/. Existe apenas um arquivo middleware.ts por projeto. Você não pode ter arquivos de middleware por rota.

Qual runtime o middleware usa e quais são as limitações?

Middleware executa no Edge Runtime
APIs do Node.js como fs, path e a maioria dos pacotes npm não estão disponíveis
Você só pode usar APIs da Web
Você não pode acessar o corpo da requisição
Você não pode renderizar componentes React

O que acontece se você não configurar um matcher?

O middleware executa em todas as requisições, incluindo ativos estáticos como imagens, CSS e arquivos JavaScript. Sempre configure um matcher para evitar execução desnecessária.

Armadilha: Como evitar loops infinitos de redirecionamento no middleware?

Se você redireciona /login para /en/login e o middleware também corresponde a /en/login, você obtém um loop infinito. Exclua os caminhos de destino do matcher ou adicione verificações condicionais para pular caminhos já processados.

Qual a diferença entre NextResponse.redirect e NextResponse.rewrite?

redirect() envia uma resposta de redirecionamento (302 por padrão, 301 para permanente) e altera a URL do navegador
rewrite() serve o conteúdo de uma rota diferente sem alterar a URL do navegador

Como ler e definir cookies no middleware?

export function middleware(request: NextRequest) {
  // Lê um cookie
  const token = request.cookies.get("session")?.value;
 
  // Define um cookie na resposta
  const response = NextResponse.next();
  response.cookies.set("visited", "true", { maxAge: 3600 });
  return response;
}

Cookies definidos no middleware estão disponíveis em Server Components?

Sim. Cookies definidos no middleware estão disponíveis via cookies() de next/headers em Server Components.

Como lidar com lógicas diferentes para rotas diferentes em um único arquivo de middleware?

Use verificações condicionais em request.nextUrl.pathname dentro da função de middleware, já que você só pode ter um arquivo de middleware.

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  if (pathname.startsWith("/api/")) { /* Lógica da API */ }
  if (pathname.startsWith("/admin")) { /* Lógica do admin */ }
  return NextResponse.next();
}

Qual é a assinatura TypeScript para a função de middleware?

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(
  request: NextRequest
): NextResponse | Response | undefined;
 
export const config: {
  matcher: string | string[];
};

Quais propriedades estão disponíveis em NextRequest?

request.nextUrl -- URL analisada com pathname e searchParams
request.cookies -- Instância de RequestCookies
request.headers -- objeto Headers padrão
request.geo -- cidade, país, região (apenas Vercel)
request.ip -- IP do cliente (apenas Vercel)

Armadilha: NextResponse.next() interrompe a função de middleware?

Não. O código após NextResponse.next() ainda é executado. Se você quiser parar o processamento, deve explicitamente return a resposta.

Quando usar redirecionamentos de middleware vs. redirecionamentos de next.config.js?

Use redirecionamentos de next.config.js para regras estáticas que não precisam de lógica em tempo de execução
Use redirecionamentos de middleware quando precisar de lógica condicional baseada em cookies, cabeçalhos ou outros dados de requisição

Relacionado

Noções Básicas do App Router - visão geral das convenções de arquivos
Navegação - redirect() e navegação programática
Grupos de Rotas - organização de rotas que o middleware protege
Rotas Dinâmicas - padrões de matcher para segmentos dinâmicos

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// middleware.ts (raiz do projeto, mesmo nível de app/)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(request: NextRequest) {
  // Redireciona, reescreve ou modifica cabeçalhos
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

Quando usar: Guardas de autenticação, detecção de idioma, testes A/B, redirecionamentos e qualquer lógica em nível de requisição que precise ser executada antes da renderização.

Exemplo de Trabalho

// middleware.ts - Guarda de autenticação com detecção de idioma
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
const protectedPaths = ["/dashboard", "/settings", "/billing"];
const defaultLocale = "en";
const supportedLocales = ["en", "fr", "de", "es"];
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // 1. Detecção de idioma - redireciona se não houver prefixo de idioma
  const pathnameHasLocale = supportedLocales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
 
  if (!pathnameHasLocale) {
    const locale =
      request.headers.get("accept-language")?.split(",")[0]?.split("-")[0] ?? defaultLocale;
    const detectedLocale = supportedLocales.includes(locale) ? locale : defaultLocale;
 
    return NextResponse.redirect(
      new URL(`/${detectedLocale}${pathname}`, request.url)
    );
  }
 
  // 2. Verificação de autenticação - redireciona usuários não autenticados
  const isProtected = protectedPaths.some((path) =>
    pathname.includes(path)
  );
  const token = request.cookies.get("session-token")?.value;
 
  if (isProtected && !token) {
    const loginUrl = new URL("/en/login", request.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }
 
  // 3. Adiciona cabeçalhos personalizados
  const response = NextResponse.next();
  response.headers.set("x-pathname", pathname);
  return response;
}
 
export const config = {
  matcher: [
    // Corresponde a todos os caminhos, exceto arquivos estáticos e internos do Next.js
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

// middleware.ts - Mapa simples de redirecionamentos
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
const redirects: Record<string, string> = {
  "/old-blog": "/blog",
  "/docs/v1": "/docs",
  "/legacy-api": "/api/v2",
};
 
export function middleware(request: NextRequest) {
  const redirect = redirects[request.nextUrl.pathname];
  if (redirect) {
    return NextResponse.redirect(new URL(redirect, request.url), 301);
  }
  return NextResponse.next();
}
 
export const config = {
  matcher: ["/old-blog", "/docs/v1", "/legacy-api"],
};

Mergulho Profundo

Como Funciona

Middleware executa em cada requisição correspondente antes que o manipulador de rota ou a página seja renderizado. Ele executa no Edge Runtime por padrão.
Existe apenas um arquivo middleware.ts por projeto. Ele deve estar na raiz (ao lado de app/ ou src/). Você não pode ter arquivos de middleware por rota.
A configuração matcher filtra quais rotas acionam o middleware. Sem um matcher, o middleware executa em todas as requisições, incluindo ativos estáticos.
NextResponse.next() continua para a rota correspondente. Você pode modificar cabeçalhos de requisição/resposta ao passar.
NextResponse.redirect(url) envia uma resposta de redirecionamento (302 por padrão, passe 301 para permanente).
NextResponse.rewrite(url) serve o conteúdo de outra rota sem alterar a URL do navegador.
Middleware executa no Edge Runtime. APIs do Node.js como fs, path e a maioria dos pacotes npm não estão disponíveis. Use apenas APIs da Web.
Middleware pode ler e definir cookies. Use request.cookies.get() e response.cookies.set() para gerenciamento de sessão.
Middleware não pode renderizar componentes React. Ele opera no nível HTTP, antes que qualquer renderização React ocorra.

Variações

// Teste A/B baseado em reescrita
export function middleware(request: NextRequest) {
  const bucket = request.cookies.get("ab-bucket")?.value;
  const response = NextResponse.next();
 
  if (!bucket) {
    const newBucket = Math.random() > 0.5 ? "a" : "b";
    response.cookies.set("ab-bucket", newBucket, { maxAge: 60 * 60 * 24 * 30 });
  }
 
  const currentBucket = bucket ?? "a";
  if (request.nextUrl.pathname === "/pricing") {
    return NextResponse.rewrite(
      new URL(`/pricing/${currentBucket}`, request.url)
    );
  }
 
  return response;
}

// Limitação de taxa com cabeçalhos
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith("/api/")) {
    const ip = request.headers.get("x-forwarded-for") ?? "unknown";
    // Verifica limite de taxa (usando armazenamento externo como Upstash Redis)
    // Isto é pseudocódigo - use @upstash/ratelimit em produção
    const response = NextResponse.next();
    response.headers.set("X-RateLimit-Limit", "100");
    return response;
  }
  return NextResponse.next();
}

// Padrões de matcher
export const config = {
  matcher: [
    "/dashboard/:path*",          // /dashboard e todos os sub-caminhos
    "/api/:path*",                // Todas as rotas de API
    "/blog/:slug",                // Segmento dinâmico único
    "/((?!_next|static|api).*)",  // Tudo exceto _next, static, api
  ],
};

Notas TypeScript

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
// Assinatura da função de middleware
export function middleware(request: NextRequest): NextResponse | Response | undefined;
 
// NextRequest estende a API Web Request
// Propriedades chave:
//   request.nextUrl      - URL analisada com pathname, searchParams
//   request.cookies      - Instância de RequestCookies
//   request.headers      - objeto Headers padrão
//   request.geo          - { city, country, region } (apenas Vercel)
//   request.ip           - IP do cliente (apenas Vercel)
 
// Tipo de configuração
export const config: {
  matcher: string | string[];
};

Armadilhas

Apenas um arquivo de middleware por projeto. Se você precisar de lógicas diferentes para rotas diferentes, use verificações condicionais em request.nextUrl.pathname dentro de uma única função de middleware.
Middleware executa no Edge Runtime. Você não pode usar APIs específicas do Node.js. Bibliotecas como bcrypt, fs ou drivers de banco de dados não funcionarão - use alternativas compatíveis com edge.
Middleware também executa em ativos estáticos a menos que você use um matcher. Sempre configure um matcher para evitar execução desnecessária.
Loops infinitos de redirecionamento são fáceis de criar. Se você redireciona /login para /en/login e o middleware também corresponde a /en/login, você obtém um loop. Exclua os caminhos de destino do matcher.
NextResponse.next() não interrompe a execução. Outra lógica de middleware após ele ainda é executada. Retorne antecipadamente se necessário.
Cookies definidos no middleware estão disponíveis em Server Components via cookies() de next/headers.
Reescritas são invisíveis para o cliente. A URL do navegador permanece a mesma, mas o servidor renderiza uma rota diferente. Isso pode confundir a navegação do lado do cliente se não for tratado com cuidado.
Middleware não pode acessar o corpo da requisição. Ele opera apenas em cabeçalhos, cookies e URL.

Alternativas

Abordagem	Quando Usar
`next.config.js` redirects	Regras de redirecionamento estáticas que não precisam de lógica em tempo de execução
`next.config.js` rewrites	Regras de reescrita estáticas sem lógica condicional
`redirect()` em nível de rota	Redirecionar dentro de um Server Component após verificações de dados
Server Actions com autenticação	Proteger mutações em vez de rotas
Guardas de autenticação em nível de layout	Verificar autenticação em um layout e redirecionar

Exemplo do Mundo Real

De uma aplicação SaaS Next.js 15 / React 19 em produção (SystemsArchitect.io).

// Exemplo de produção: Middleware com reescritas, redirecionamentos, atualização de sessão e proteção de administrador
// Arquivo: middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { updateSession } from '@/utils/supabase/middleware';
 
const legacyRedirects: Record<string, string> = {
  '/old-docs': '/docs',
  '/blog/legacy-post': '/articles',
  '/pricing-old': '/pricing',
};
 
export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // 1. Reescrita de docs: serve /docs/[section] de uma rota interna diferente
  if (pathname.startsWith('/docs/')) {
    const url = request.nextUrl.clone();
    url.pathname = `/docs-internal${pathname.replace('/docs', '')}`;
    return NextResponse.rewrite(url);
  }
 
  // 2. Redirecionamentos legados (permanente 301)
  const redirect = legacyRedirects[pathname];
  if (redirect) {
    return NextResponse.redirect(new URL(redirect, request.url), 301);
  }
 
  // 3. Atualização de sessão - mantém a sessão de autenticação Supabase ativa
  const response = await updateSession(request);
 
  // 4. Proteção de rota de administrador
  if (pathname.startsWith('/admin')) {
    const session = request.cookies.get('sb-access-token')?.value;
    if (!session) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }
 
  return response;
}
 
export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

O que isso demonstra em produção:

A ordem de execução importa. As reescritas são executadas primeiro, depois os redirecionamentos legados, depois a atualização da sessão e, por fim, a proteção do administrador. Se você verificar a autenticação antes da reescrita, o usuário pode acessar a rota errada.
O código de status 301 nos redirecionamentos legados informa aos mecanismos de busca que a mudança é permanente. Usar o 302 padrão preservaria a URL antiga nos índices de pesquisa.
updateSession(request) é uma utilidade do Supabase que atualiza o cookie de sessão de autenticação a cada requisição. Isso evita que a sessão expire enquanto o usuário está navegando ativamente.
A regex do matcher /((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*) exclui ativos estáticos e imagens do processamento do middleware. Sem isso, o middleware seria executado em cada requisição de imagem e arquivo CSS, adicionando latência desnecessária.
A proteção de administrador verifica um cookie em vez de fazer uma chamada ao banco de dados. O middleware é executado no Edge Runtime, onde drivers de banco de dados não estão disponíveis. Verificações completas de autorização ocorrem em Server Components ou rotas de API.
Existe apenas um arquivo middleware.ts por projeto. Toda a lógica específica da rota deve ser tratada com verificações condicionais em pathname.

FAQs

Onde vai o arquivo middleware.ts?

Na raiz do projeto, ao lado do diretório app/ ou src/. Existe apenas um arquivo middleware.ts por projeto. Você não pode ter arquivos de middleware por rota.

Qual runtime o middleware usa e quais são as limitações?

Middleware executa no Edge Runtime
APIs do Node.js como fs, path e a maioria dos pacotes npm não estão disponíveis
Você só pode usar APIs da Web
Você não pode acessar o corpo da requisição
Você não pode renderizar componentes React

O que acontece se você não configurar um matcher?

O middleware executa em todas as requisições, incluindo ativos estáticos como imagens, CSS e arquivos JavaScript. Sempre configure um matcher para evitar execução desnecessária.

Armadilha: Como evitar loops infinitos de redirecionamento no middleware?

Qual a diferença entre NextResponse.redirect e NextResponse.rewrite?

redirect() envia uma resposta de redirecionamento (302 por padrão, 301 para permanente) e altera a URL do navegador
rewrite() serve o conteúdo de uma rota diferente sem alterar a URL do navegador

Como ler e definir cookies no middleware?

export function middleware(request: NextRequest) {
  // Lê um cookie
  const token = request.cookies.get("session")?.value;
 
  // Define um cookie na resposta
  const response = NextResponse.next();
  response.cookies.set("visited", "true", { maxAge: 3600 });
  return response;
}

Cookies definidos no middleware estão disponíveis em Server Components?

Sim. Cookies definidos no middleware estão disponíveis via cookies() de next/headers em Server Components.

Como lidar com lógicas diferentes para rotas diferentes em um único arquivo de middleware?

Use verificações condicionais em request.nextUrl.pathname dentro da função de middleware, já que você só pode ter um arquivo de middleware.

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  if (pathname.startsWith("/api/")) { /* Lógica da API */ }
  if (pathname.startsWith("/admin")) { /* Lógica do admin */ }
  return NextResponse.next();
}

Qual é a assinatura TypeScript para a função de middleware?

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(
  request: NextRequest
): NextResponse | Response | undefined;
 
export const config: {
  matcher: string | string[];
};

Quais propriedades estão disponíveis em NextRequest?

request.nextUrl -- URL analisada com pathname e searchParams
request.cookies -- Instância de RequestCookies
request.headers -- objeto Headers padrão
request.geo -- cidade, país, região (apenas Vercel)
request.ip -- IP do cliente (apenas Vercel)

Armadilha: NextResponse.next() interrompe a função de middleware?

Não. O código após NextResponse.next() ainda é executado. Se você quiser parar o processamento, deve explicitamente return a resposta.

Quando usar redirecionamentos de middleware vs. redirecionamentos de next.config.js?

Use redirecionamentos de next.config.js para regras estáticas que não precisam de lógica em tempo de execução
Use redirecionamentos de middleware quando precisar de lógica condicional baseada em cookies, cabeçalhos ou outros dados de requisição

Relacionado

Noções Básicas do App Router - visão geral das convenções de arquivos
Navegação - redirect() e navegação programática
Grupos de Rotas - organização de rotas que o middleware protege
Rotas Dinâmicas - padrões de matcher para segmentos dinâmicos

Middleware

Buscar na documentação

Middleware