redirects

Core Idea

Redirects an incoming request path to a different destination path, defined via the redirects key in next.config.js (Pages Router). Checked before the filesystem.

Key Concepts

• source / destination: incoming path pattern and target path (path-to-regexp syntax, same as headers/rewrites).
• permanent: true → 308 status (cached forever by clients/search engines), false → 307 (temporary, not cached). Mutually exclusive with statusCode (for custom codes, e.g. old HTTP clients).
• 307/308 vs 301/302: Next.js uses 307/308 specifically to preserve the original HTTP method (302/301 caused browsers to coerce the method to GET).
• basePath / locale: false to opt a redirect out of automatic basePath/locale prefixing.
• has / missing: conditional matching on header, cookie, host, query (same shape as headers/rewrites).
• Query passthrough: query params from the original request are passed through to the destination automatically, unless the destination consumes named params.
• Client-side routing: in Pages Router, redirects do NOT apply to Link/router.push unless a matching Proxy is present.

Code Examples

module.exports = {
  redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/news/:slug',
        permanent: true,
      },
    ]
  },
}

• O que demonstra: redirect permanente com captura de parâmetro reaproveitado no destino; /old-blog/post-1?hello=world vira /news/post-1?hello=world.

Reference Tables

Version	Changes
v13.3.0	missing added
v10.2.0	has added
v9.5.0	redirects added

Anti-patterns

• Omitir a / antes de :param no source/destination: trata o path como string literal e pode causar loop infinito de redirect.
• Usar permanent e statusCode juntos: são mutuamente exclusivos.

Key Takeaways

1. Path matching não cobre paths aninhados por padrão (/old-blog/:slug não pega /old-blog/a/b), use * para isso.
2. Query string é preservada automaticamente no redirect, a menos que parâmetros nomeados já sejam usados no destination.
3. Redirects client-side (Link/router.push) exigem Proxy configurado; a config redirects() sozinha só cobre navegação servidor.
4. Também é possível redirecionar programaticamente dentro de API Routes/Route Handlers, getStaticProps e getServerSideProps.

Connects To

• headers / rewrites: mesma sintaxe de source, path matching, has/missing.
• proxy.js: necessário para redirects afetarem roteamento client-side.