rewrites

Core Idea

Maps an incoming request path to a different destination path while masking the URL shown to the user (unlike redirects, which change the visible URL). Configured via the rewrites key in next.config.js, applies to client-side routing too.

Key Concepts

• source / destination: same path-to-regexp syntax as headers/redirects.
• Array vs object return: returning a plain array applies rewrites after filesystem checks and before dynamic routes. Returning { beforeFiles, afterFiles, fallback } (since v10.1) gives fine-grained control over ordering.
• beforeFiles: checked after headers/redirects, before filesystem/pages — can override page files. All beforeFiles are checked before filesystem, even after a match.
• afterFiles: checked after pages/public files, before dynamic routes.
• fallback: checked after both static files and dynamic routes — good for incremental migration (proxy leftover routes to a legacy site). Skipped if getStaticPaths uses fallback: true/'blocking'.
• Rewrite parameters: unused params in destination are auto-passed as query; if any param IS used in destination, none are auto-passed (must add manually, e.g. /:first?second=:second).
• External URL rewrites: destination can point to a full external URL, useful for incremental adoption of Next.js in front of a legacy site.
• has / missing: same conditional matching as headers/redirects.

Code Examples

module.exports = {
  rewrites() {
    return {
      beforeFiles: [
        { source: '/some-page', destination: '/somewhere-else', has: [{ type: 'query', key: 'overrideMe' }] },
      ],
      afterFiles: [
        { source: '/non-existent', destination: '/somewhere-else' },
      ],
      fallback: [
        { source: '/:path*', destination: `https://my-old-site.com/:path*` },
      ],
    }
  },
}

• O que demonstra: as três fases de rewrite controlando precedência sobre filesystem, dynamic routes, e fallback pra site legado.

module.exports = {
  rewrites() {
    return {
      fallback: [
        { source: '/:path*', destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*` },
      ],
    }
  },
}

• O que demonstra: adoção incremental do Next.js, deixando o fallback proxiar tudo que ainda não tem rota no Next.js pro site antigo.

Reference Tables

Ordem de checagem de rotas: 1) headers, 2) redirects, 3) beforeFiles rewrites, 4) arquivos estáticos (public, _next/static, páginas não-dinâmicas), 5) afterFiles rewrites, 6) rotas dinâmicas, 7) fallback rewrites (antes do 404).

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

Anti-patterns

• Usar trailingSlash: true sem ajustar source: precisa incluir a barra final no source (e no destination se o servidor de destino também exigir).
• Esperar beforeFiles parar no primeiro match: todos os beforeFiles continuam sendo checados até o fim antes de ir pro filesystem.

Key Takeaways

1. Rewrites preservam a URL visível, redirects não, essa é a diferença central.
2. beforeFiles/afterFiles/fallback dão controle preciso sobre onde a rewrite entra na cadeia de resolução de rota.
3. fallback é o padrão certo para "strangler fig" migration de um site legado para Next.js incremental.
4. Params não usados no destination viram query automaticamente; params usados não.

Connects To

• redirects / headers: mesma sintaxe base de matching.
• getStaticPaths fallback: interação direta com o fallback rewrite (mutuamente exclusivos em certos casos).