redirects

Core Idea

Redireciona um path de requisição para um destino diferente, definido via função redirects() em next.config.js. Redirects são verificados antes do filesystem (páginas e /public).

Key Concepts

• redirects(): função sync ou async, retorna array de objetos { source, destination, permanent, ... }.
• source: pattern do path de entrada. destination: path de destino.
• permanent: true → status 308 (cache permanente por clients/search engines); false → 307 (temporário, não cacheado). Next.js usa 307/308 em vez de 301/302 para preservar o método HTTP original (evita que POST vire GET no redirect).
• statusCode: alternativa a permanent para casos raros de status customizado (mutuamente exclusivo com permanent). Um header Refresh é adicionado automaticamente pro 308 (compatibilidade IE11).
• basePath: false: exclui o basePath do matching (só para redirects externos).
• locale: false: exclui locale do matching.
• has / missing: arrays de objetos { type, key, value } para condicionar o redirect a header/cookie/host/query. type é 'header', 'cookie', 'host' ou 'query'. value pode ser regex nomeada ((?<paramName>.*)) capturável no destination via :paramName.
• No Pages Router, redirects NÃO se aplicam a client-side routing (Link, router.push) a não ser que exista proxy casando o path.
• Query params da requisição original são propagados ao destino automaticamente.

Path Matching

• /old-blog/:slug casa /old-blog/first-post, não casa paths aninhados (/old-blog/a/b) nem prefixados (/archive/old-blog/x) — patterns são ancorados no início.
• Modificadores: * (zero ou mais), + (um ou mais), ? (zero ou um). Ex.: /blog/:slug* casa /blog, /blog/a, /blog/a/b/c.
• Regex: /post/:slug(\\d{1,}) casa só dígitos. Caracteres especiais ( ) { } : * + ? usados literalmente no source precisam de escape \\.

Code Examples

module.exports = {
  redirects() {
    return [
      { source: '/about', destination: '/', permanent: true },
      { source: '/old-blog/:slug*', destination: '/news/:slug*', permanent: true },
      {
        source: '/:path((?!another-page$).*)',
        has: [{ type: 'header', key: 'x-redirect-me' }],
        permanent: false,
        destination: '/another-page',
      },
    ]
  },
}

• O que demonstra: redirect simples permanente, wildcard com parâmetro propagado, e redirect condicional por header via has.

Reference Tables

Campo	Tipo	Descrição
source	string	pattern de entrada
destination	string	path de saída
permanent	boolean	308 (true) vs 307 (false)
statusCode	number	alternativa a permanent
basePath	false|undefined	exclui basePath do matching
locale	false|undefined	exclui locale do matching
has/missing	array	condições extra de header/cookie/host/query

Version History

Versão	Mudança
v13.3.0	missing adicionado.
v10.2.0	has adicionado.
v9.5.0	redirects adicionado.

Anti-patterns

• Esquecer a / antes de : em path parameters no source/destination causa risco de redirect infinito (o path vira string literal).

Connects To

• rewrites (ch239): mesmo mecanismo de matching (has/missing, regex, wildcard), mas mascara a URL em vez de trocá-la.
• basePath: prefixa source/destination automaticamente a menos que basePath: false.
• proxy: necessário para redirects afetarem client-side routing no Pages Router.