reescrituras (rewrites)

Los rewrites te permiten mapear una ruta de solicitud entrante a una ruta de destino diferente.

Los rewrites actúan como un proxy de URL y enmascaran la ruta de destino, haciendo parecer que el usuario no ha cambiado su ubicación en el sitio. En contraste, los redirects redirigirán a una nueva página y mostrarán los cambios en la URL.

Para usar rewrites puedes utilizar la clave rewrites en next.config.js:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/about',
        destination: '/',
      },
    ]
  },
}

Los rewrites se aplican al enrutamiento del lado del cliente, un <Link href="/about"> tendrá el rewrite aplicado en el ejemplo anterior.

rewrites es una función asíncrona que espera devolver un array o un objeto de arrays (ver abajo) que contenga objetos con las propiedades source y destination:

source: String - es el patrón de ruta de solicitud entrante.
destination: String - es la ruta a la que deseas redirigir.
basePath: false o undefined - si es false, el basePath no se incluirá al hacer coincidencias, solo puede usarse para rewrites externos.
locale: false o undefined - indica si la configuración regional no debe incluirse al hacer coincidencias.
has: array de objetos has con las propiedades type, key y value.
missing: array de objetos missing con las propiedades type, key y value.

Cuando la función rewrites devuelve un array, los rewrites se aplican después de verificar el sistema de archivos (páginas y archivos /public) y antes de las rutas dinámicas. Cuando la función rewrites devuelve un objeto de arrays con una forma específica, este comportamiento puede cambiarse y controlarse con más precisión, a partir de la versión v10.1 de Next.js:

next.config.js

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        // Estos rewrites se verifican después de headers/redirects
        // y antes de todos los archivos, incluyendo archivos _next/public, lo que
        // permite sobrescribir archivos de página
        {
          source: '/some-page',
          destination: '/somewhere-else',
          has: [{ type: 'query', key: 'overrideMe' }],
        },
      ],
      afterFiles: [
        // Estos rewrites se verifican después de los archivos pages/public
        // pero antes de las rutas dinámicas
        {
          source: '/non-existent',
          destination: '/somewhere-else',
        },
      ],
      fallback: [
        // Estos rewrites se verifican después de los archivos pages/public
        // y las rutas dinámicas
        {
          source: '/:path*',
          destination: `https://my-old-site.com/:path*`,
        },
      ],
    }
  },
}

Nota importante: los rewrites en beforeFiles no verifican el sistema de archivos/rutas dinámicas inmediatamente después de coincidir con un source, continúan hasta que todos los beforeFiles hayan sido verificados.

El orden en que Next.js verifica las rutas es:

Se verifican/aplican los headers
Se verifican/aplican los redirects
Se verifican/aplican los rewrites beforeFiles
Se verifican/sirven archivos estáticos del directorio public, archivos _next/static y páginas no dinámicas
Se verifican/aplican los rewrites afterFiles, si uno de estos rewrites coincide, verificamos las rutas dinámicas/archivos estáticos después de cada coincidencia
Se verifican/aplican los rewrites fallback, estos se aplican antes de renderizar la página 404 y después de verificar las rutas dinámicas/todos los recursos estáticos. Si usas fallback: true/'blocking' en getStaticPaths, los rewrites fallback definidos en tu next.config.js no se ejecutarán.

Parámetros en rewrites

Cuando se usan parámetros en un rewrite, los parámetros se pasarán en la query por defecto cuando ninguno de los parámetros se use en el destination.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-about/:path*',
        destination: '/about', // El parámetro :path no se usa aquí, por lo que se pasará automáticamente en la query
      },
    ]
  },
}

Si un parámetro se usa en el destination, ninguno de los parámetros se pasará automáticamente en la query.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: '/:path*', // El parámetro :path se usa aquí, por lo que no se pasará automáticamente en la query
      },
    ]
  },
}

Aún puedes pasar los parámetros manualmente en la query si uno ya se usa en el destination especificando la query en el destination.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/:first/:second',
        destination: '/:first?second=:second',
        // Como el parámetro :first se usa en el destination, el parámetro :second
        // no se agregará automáticamente en la query, aunque podemos agregarlo manualmente
        // como se muestra arriba
      },
    ]
  },
}

Nota importante: Las páginas estáticas de Optimización Estática Automática o prerenderizado con parámetros de rewrites se analizarán en el cliente después de la hidratación y se proporcionarán en la query.

Coincidencia de rutas

Se permiten coincidencias de rutas, por ejemplo /blog/:slug coincidirá con /blog/hello-world (sin rutas anidadas):

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog/:slug',
        destination: '/news/:slug', // Los parámetros coincidentes pueden usarse en el destination
      },
    ]
  },
}

Coincidencia de rutas con comodín

Para coincidir con una ruta comodín puedes usar * después de un parámetro, por ejemplo /blog/:slug* coincidirá con /blog/a/b/c/d/hello-world:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*', // Los parámetros coincidentes pueden usarse en el destination
      },
    ]
  },
}

Coincidencia de rutas con regex

Para coincidir con una ruta regex puedes envolver la regex entre paréntesis después de un parámetro, por ejemplo /blog/:slug(\\d{1,}) coincidirá con /blog/123 pero no con /blog/abc:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-blog/:post(\\d{1,})',
        destination: '/blog/:post', // Los parámetros coincidentes pueden usarse en el destination
      },
    ]
  },
}

Los siguientes caracteres (, ), {, }, :, *, +, ? se usan para coincidencia de rutas regex, por lo que cuando se usan en el source como valores no especiales deben escaparse agregando \\ antes de ellos:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        // esto coincidirá con `/english(default)/something` cuando se solicite
        source: '/english\\(default\\)/:slug',
        destination: '/en-us/:slug',
      },
    ]
  },
}

Coincidencia de cabeceras, cookies y queries

Para que un rewrite solo coincida cuando los valores de cabecera, cookie o query también coincidan, se puede usar el campo has o el campo missing para que no coincidan. Tanto el source como todos los elementos has deben coincidir, y todos los elementos missing no deben coincidir para que se aplique el rewrite.

Los elementos has y missing pueden tener los siguientes campos:

type: String - debe ser header, cookie, host o query.
key: String - la clave del tipo seleccionado con la que coincidir.
value: String o undefined - el valor a verificar, si es undefined cualquier valor coincidirá. Se puede usar una cadena tipo regex para capturar una parte específica del valor, por ejemplo, si el valor first-(?<paramName>.*) se usa para first-second, entonces second se podrá usar en el destination con :paramName.

next.config.js

module.exports = {
  async rewrites() {
    return [
      // si la cabecera `x-rewrite-me` está presente,
      // se aplicará este rewrite
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // si la cabecera `x-rewrite-me` no está presente,
      // se aplicará este rewrite
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-rewrite-me',
          },
        ],
        destination: '/another-page',
      },
      // si coinciden el source, query y cookie,
      // se aplicará este rewrite
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // el valor page no estará disponible en el
            // destination ya que se proporciona value y no
            // usa un grupo de captura nombrado, ej. (?<page>home)
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        destination: '/:path*/home',
      },
      // si la cabecera `x-authorized` está presente y
      // contiene un valor coincidente, se aplicará este rewrite
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        destination: '/home?authorized=:authorized',
      },
      // si el host es `example.com`,
      // se aplicará este rewrite
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        destination: '/another-page',
      },
    ]
  },
}

Rewriting a una URL externa

Ejemplos

Los rewrites permiten redirigir a una URL externa. Esto es especialmente útil para la adopción incremental de Next.js. El siguiente es un ejemplo de rewrite para redirigir la ruta /blog de tu aplicación principal a un sitio externo.

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog',
        destination: 'https://example.com/blog',
      },
      {
        source: '/blog/:slug',
        destination: 'https://example.com/blog/:slug', // Los parámetros coincidentes pueden usarse en el destination
      },
    ]
  },
}

Si estás usando trailingSlash: true, también necesitas insertar una barra diagonal al final en el parámetro source. Si el servidor de destino también espera una barra diagonal al final, debe incluirse en el parámetro destination.

next.config.js

module.exports = {
  trailingSlash: true,
  async rewrites() {
    return [
      {
        source: '/blog/',
        destination: 'https://example.com/blog/',
      },
      {
        source: '/blog/:path*/',
        destination: 'https://example.com/blog/:path*/',
      },
    ]
  },
}

Adopción incremental de Next.js

También puedes hacer que Next.js recurra a redirigir a un sitio web existente después de verificar todas las rutas de Next.js.

De esta manera no tienes que cambiar la configuración de rewrites cuando migres más páginas a Next.js.

next.config.js

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

Rewrites con soporte para basePath

Cuando se usa basePath con rewrites, cada source y destination se prefija automáticamente con el basePath a menos que agregues basePath: false al rewrite:

next.config.js

module.exports = {
  basePath: '/docs',

  async rewrites() {
    return [
      {
        source: '/with-basePath', // automáticamente se convierte en /docs/with-basePath
        destination: '/another', // automáticamente se convierte en /docs/another
      },
      {
        // no agrega /docs a /without-basePath ya que basePath: false está establecido
        // Nota: esto no puede usarse para rewrites internos, ej. `destination: '/another'`
        source: '/without-basePath',
        destination: 'https://example.com',
        basePath: false,
      },
    ]
  },
}

Rewrites con soporte para i18n

Cuando se usa i18n con rewrites, cada source y destination se prefija automáticamente para manejar los locales configurados a menos que agregues locale: false al rewrite. Si se usa locale: false, debes prefijar el source y destination con un locale para que coincida correctamente.

next.config.js

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },

  async rewrites() {
    return [
      {
        source: '/with-locale', // maneja automáticamente todos los locales
        destination: '/another', // pasa automáticamente el locale
      },
      {
        // no maneja locales automáticamente ya que locale: false está establecido
        source: '/nl/with-locale-manual',
        destination: '/nl/another',
        locale: false,
      },
      {
        // esto coincide con '/' ya que `en` es el defaultLocale
        source: '/en',
        destination: '/en/another',
        locale: false,
      },
      {
        // es posible hacer coincidir todos los locales incluso cuando locale: false está establecido
        source: '/:locale/api-alias/:path*',
        destination: '/api/:path*',
        locale: false,
      },
      {
        // esto se convierte a /(en|fr|de)/(.*) por lo que no coincidirá con las rutas
        // de nivel superior `/` o `/fr` como lo haría /:path*
        source: '/(.*)',
        destination: '/another',
      },
    ]
  },
}

Historial de versiones

Versión	Cambios
`v13.3.0`	Se agregó `missing`.
`v10.2.0`	Se agregó `has`.
`v9.5.0`	Se agregaron cabeceras.

On this page