Redirects

This feature was introduced in Next.js 9.5 and up. If you’re using older versions of Next.js, please upgrade before trying it out.

Examples

Redirects allow you to redirect an incoming request path to a different destination path.

Redirects are only available on the Node.js environment and do not affect client-side routing.

To use Redirects you can use the redirects key in next.config.js:

  1. module.exports = {
  2.   async redirects() {
  3.     return [
  4.       {
  5.         source: '/about',
  6.         destination: '/',
  7.         permanent: true,
  8.       },
  9.     ]
  10.   },
  11. }

redirects is an async function that expects an array to be returned holding objects with source, destination, and permanent properties:

  • source is the incoming request path pattern.
  • destination is the path you want to route to.
  • permanent if the redirect is permanent or not.

Path Matching

Path matches are allowed, for example /old-blog/:slug will match /old-blog/hello-world (no nested paths):

  1. module.exports = {
  2.   async redirects() {
  3.     return [
  4.       {
  5.         source: '/old-blog/:slug',
  6.         destination: '/news/:slug', // Matched parameters can be used in the destination
  7.         permanent: true,
  8.       },
  9.     ]
  10.   },
  11. }

Wildcard Path Matching

To match a wildcard path you can use * after a parameter, for example /blog/:slug* will match /blog/a/b/c/d/hello-world:

  1. module.exports = {
  2.   async redirects() {
  3.     return [
  4.       {
  5.         source: '/blog/:slug*',
  6.         destination: '/news/:slug*', // Matched parameters can be used in the destination
  7.         permanent: true,
  8.       },
  9.     ]
  10.   },
  11. }

Regex Path Matching

To match a regex path you can wrap the regex in parenthesis after a parameter, for example /blog/:slug(\\d{1,}) will match /blog/123 but not /blog/abc:

  1. module.exports = {
  2.   async redirects() {
  3.     return [
  4.       {
  5.         source: '/old-blog/:post(\\d{1,})',
  6.         destination: '/blog/:post', // Matched parameters can be used in the destination
  7.         permanent: false,
  8.       },
  9.     ]
  10.   },
  11. }

Redirects with basePath support

When leveraging basePath support with redirects each source and destination is automatically prefixed with the basePath unless you add basePath: false to the redirect:

  1. module.exports = {
  2.   basePath: '/docs',
  4.   async redirects() {
  5.     return [
  6.       {
  7.         source: '/with-basePath', // automatically becomes /docs/with-basePath
  8.         destination: '/another', // automatically becomes /docs/another
  9.         permanent: false,
  10.       },
  11.       {
  12.         // does not add /docs since basePath: false is set
  13.         source: '/without-basePath',
  14.         destination: '/another',
  15.         basePath: false,
  16.         permanent: false,
  17.       },
  18.     ]
  19.   },
  20. }

In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the statusCode property instead of the permanent property, but not both. Note: to ensure IE11 compatibility a Refresh header is automatically added for the 308 status code.