RFC: Custom Routes

[Timer]

Goals

• Support Redirects
• Support Rewrites
• Support Headers
• Provide an API for next-routes and related libraries (and eventual migration path)
• Reduce the necessity of a custom server

Background

Next.js has a file system-based router, which supports both static and dynamic routes. This router is normally powerful enough to cover most needs, but sometimes isn't the best fit.

Presently, it is not possible to extend Next.js' router within the framework — this means any custom routing or user-land routing libraries require you to use a custom server, and there is currently no way to incrementally migrate away from libraries like next-routes as they still require a custom server.

Custom servers were always meant to be reserved for the most advanced or specialized use cases. When you use them, you're partially removed from the framework's pit of success.

When talking with companies and users who use Next.js in production, we found custom servers were most commonly used for redirects and rewrites. While dynamic routes introduced in Next.js 9 cover the majority of use cases, there are still a few cases that have to be covered.

Therefore, it makes sense for Next.js to support these two features — allowing users to remove their usage of a custom server in many cases.

Let's dive into more about what we mean by a redirect, a rewrite, and a header.

Redirects

By redirects, we mean HTTP Redirects (aka URL forwarding). Redirects are most commonly used when a website is reorganized — ensuring search engines and bookmarks are forwarded to their new locations.

Next.js currently does not support redirects as a primitive. As a result, users rely on a custom server or "redirect pages" to implement them. Neither of these solutions are sufficiently ergonomic.

Rewrites

Rewrites are the most commonly used form of custom routing — they're used for dynamic routes (pretty URLs), user-land routing libraries (e.g. next-routes), internationalization, and other advanced use cases.

For example, the route /user/:id rendering a specific user's profile page is a rewrite.

Rendering your company's about page for both /about and /es/acerca is also a rewrite.

We introduced file system-based dynamic routing in Next.js 9 to provide a convention-based way to cover the majority of rewrite use cases. However, some use cases sometimes need more flexibility, especially related to i18n use-cases.

Headers

Headers allow you to set route specific headers like CORS headers, content-types, and any other headers that may be needed. They are applied at the very top of the routes

Proposal

Redirects

Next.js should allow users to create an async redirects() { ... } function in their next.config.js. This function would allow you to return an ordered list of redirects.

Next.js allows you to specify whether the redirect is permanent or not with the permanent field. This is required unless you need to specify the statusCode manually

When permanent is set to true we use a status code of 308 and also set a Refresh header for backwards compatibility with IE11.

When permanent is set to false we use a status code of 307 which is not cached by browsers and signifies the redirect is temporary.

Next.js only permits the following status codes:

• 301 Moved Permanently
• 302 Found
• 303 See Other
• 307 Temporary Redirect
• 308 Permanent Redirect

Please let us know if we missed any redirection status codes.

Shape of a Redirect:

• source: string: the request URL to match, parsed with path-to-regexp
• destination: string: the destination URL (internal or external)
• statusCode?: number: the redirect status code
• permanent: boolean: whether the redirect is permanent (required unless statusCode is provided)

<Link> components should validate the specified as does not match a redirect. If it does, we should render an error client-side.

next export does not have any special behavior for redirects. Meaning, we do not emit redirect pages with <meta http-equiv=refresh content=... />.

Redirects for next export-powered websites should be configured manually and varies by hosting provider. These are automatically handled on ZEIT Now as applications.

Example Usage

// next.config.js
module.exports = {
  async redirects() {
    return [
      // 307 temporary redirect
      {
        source: "/",
        destination: "/under-construction",
        permanent: false,
      },
      // 308 permanent redirect
      {
        source: "/posts",
        destination: "/blog",
        permanent: true // permanent redirect
      },
      // With parameter and custom status code
      {
        source: "/photos/:id",
        destination: "/photo/:id",
        statusCode: 303 // see other
      }
    ];
  }
};

Rewrites

Next.js should allow users to create an async rewrites() { ... } function in their next.config.js. This function would allow you to return an ordered list of rewrites.

Rewrites always continue down the matching chain, and merge in the last-matched query objects (overwrite previous matches).

Shape of a Rewrite:

• source: string: the request URL to match, parsed with path-to-regexp
• destination: string: the destination path (internal or external); these rewrites chain down the list in-order unless external

next export does not have any special behavior for rewrites. Rewrites for next export-powered websites should be configured manually and varies by hosting provider. These are automatically handled on ZEIT Now.

Example Usage

// next.config.js
module.exports = {
  async rewrites() {
    return [
      // Basic `path-to-regexp` usage
      // Query object shape: { id: string }
      { source: "/user/:id", destination: "/user_profile" },

      // Optional Language
      // Query object shape: { lang?: string }
      { source: "/:lang(en|es)?/about", destination: "/about" },

      // Advanced rewrite
      // Query object shape: { id: string } (in addition to dynamic route param)
      { source: "/u/:id", destination: "/user/:id" }
    ];
  }
};

Headers

Next.js should allow users to create an async headers() { ... } function in their next.config.js. This function would allow you to return an ordered list of headers.

Headers always continue down the matching chain, and overwrite any previous matches' headers.

Shape of a Header:

• source: string: the request URL to match, parsed with path-to-regexp
• headers: Array<{ key: string, value: string }>: an array of header key/value pairs

Example Usage

// next.config.js
module.exports = {
  async headers() {
    return [
      { source: "/user/:id", headers: [{ key: "x-path", value: "hi" }] },

      {
        source: "/:lang(en|es)?/about",
        headers: [
          { key: "x-path", value: "hi" },
          { key: "x-another", value: "hi-again" }
        ]
      }
    ];
  }
};

[eps1lon]

Would rewrites allow overwriting how next.js handles /api routes i.e. resolve #8123?

[timneutkens]

Yep you'd be able to route /api to something else.

Eg:

{ source: '/api/:rest*', destination: '/api-docs/:rest*' }

[Muskos]

+1

[denu5]

@Muskos will not read the whole discussion, perhaps there are better suggestions below.

That`s how I solved it for individual routes.

            beforeFiles: [
                // Exposes /health instead of /api/health
                {
                    source: '/health',
                    destination: '/api/health',
                },

perhaps you are fine with rewriting it generally from /fe-api to nextjs/api.
this would allow to have both "real backend /api" and the one in nextjs to live in peace.

[Muskos]

@denu5 It works for me. I rewrite it in a similar way. But /api/health/ still available. And I actually don't understand whether it is ok?

[denu5]

@Muskos in my project its accepted because the api gateway doesn't expose that anyway, so nothing will be hitting /api/health from the outside

[Muskos]

@denu5 thank you for sharing

[stormy251]

Hey Tim,

I am just thinking out loud here, but one thing that may be really powerful about this approach would be the ability to have the destination be a functional argument, that could return a different destination based on some logic.

A/B Testing Example:
{
source: '/home',
destination () {
if (USER_IS_IN_AB_TEST_A) {
return '/home_versionA'
}
return '/home_versionB'
}
};

NOTE this is more or less just brainstorming something potentially useful 🤷‍♂ haha

Absolutely love this direction you and team are headed!

[timneutkens]

@stormy251 This won't work as the output has to be static at build time. Eg for the serverless target.

[stormy251]

I see, I had assumed that there was a reason for static remapping here. 👍 Thanks for the great work! I hope to free up some time to contribute to this project soon!

[danielcondemarin]

Great work 👌🏼
Aside from redirects or rewrites, would be nice if users could set headers for source routes, particularly useful for caching, i.e.

  {
     source: "/photos/*",
     headers: { 
        "cache-control": "s-maxage=604800"
     }
  }

[timneutkens]

@danielcondemarin I brought that up when @Timer and me were discussing the spec (before it was posted) but don't think it's necessary for the initial implementation, it can be a separate RFC after this is shipped 👍

[codinronan]

This scenario is the last reason I use a custom server for one of my apps. It's a fairly complex application and we've just converted it to Next 9 and ripped out all of the custom server and the only bit that remains is a custom router to do this:

/acerca => /about
/promociones => /promotions

etc., since for SEO on this particular site these matter.

With this RFC I could eliminate the custom server completely and that would be amazing, it is a huge headache to maintain the build stack for it.

[BrianAtIgloo]

Very useful proposal and something our team could use as well.

I suggest breaking this proposal into two separate RFC's; one for Redirects and one for Rewrites. This might allow for easier collaborating and keep the discussion focused.

[vsc-github]

Happy to see this RFC.

We use a custom server to point different routes to the same page, redirects in next.config could take care of it now.

[Janpot]

Far out of the scope of this RFC, but I'd like this idea to be out there. Some day I'd love to be able to implement something like the following:

// next.config.js
const path = require('path')
module.exports = {
  async rewrites() {
    return [
      {
        source: "/en/:path*",
        destination: "/:path",
        buildEnv: { LOCALE: 'en' }
      },
      {
        source: "/fr/:path*",
        destination: "/:path",
        buildEnv: { LOCALE: 'fr' }
      }
    ];
  },
  webpack (config, options) {
    config.resolve.alias['messages'] = 
      path.join(__dirname, 'messages', options.buildEnv.LOCALE || 'en');
    config.plugins.unshift(new webpack.DefinePlugin({
      'process.env.CURRENT_LOCALE': options.buildEnv.LOCALE || 'en'
    }));
    return config
  }
};

// /pages/welcome.jsx
import WelcomeMsg from 'messages/welcome'

export function () {
  return (
    <div>
      Localized welcome message: <WelcomeMsg />
    </div>
  )
}

The idea behind it would be to have pregenerated components for localized strings from a separate build step. Then next would build a bundle for each specific locale. Some of the advantages would be:

• performance, the localized bundle works as if it was handwritten
• avoids the need for I18n contexts that need to be preloaded with messages.
• avoids importing too many messages
• avoids importing too few messages, the bundle wouldn't compile if one was missing

EDIT:

Actually, I think rewrites should probably only do path rewriting. Though, I think there is a missing functionality in next.js that makes the above impossible. Can't quite lay my finger yet on what would be the right way to solve this.

[Dreamdealer]

I was just about to start setting up a custom server to handle routing for our new e-commerce client serving 40k merchants with millions of products and a gazillion different URL's, so this RFC is perfectly timed!

[pkrawc]

So redirects I get, but aren't rewrites already covered in the dynamic /path/[some_id] syntax?

[Timer]

@pkrawc most rewrites cases are already handled by dynamic routes (/blog/[posId]), correct!

This feature would be for more advanced rewrites that validate parameters, etc.

/:lang(en|es)/blog/:parts+

[james2406]

Has anyone been able to update response headers when targeting serverless? It doesn't seem to work for me with the following configuration:

module.exports = {
  experimental: {
    async headers() {
      return [
        {
          source: '/(.*)?',
          headers: [
            {
              key: 'Access-Control-Allow-Origin',
              value: '*',
            },
            {
              key: 'Access-Control-Allow-Methods',
              value: 'GET',
            },
          ],
        },
      ];
    },
  },
  target: 'serverless',
};

The local server response displays the headers specified:

However, you can see the live serverless response has removed the headers:

I also created a test on the Lambda. You can see the headers created are not included in the response:

[pix2D]

I have this rewrite: { source: '/next/:locale(de|es|fr)', destination: '/next' }

When I'm on /next if I navigate to /next/de with a <Link> it works but with a browser reload. If from there I navigate to /next there is no browser reload and it works like normal.

The following cause reloads:
<Link href="/next" as="/next/de">
<Link href="/next?locale=de" as="/next/de">

This does not, but of course that's not the URL I want:
<Link href="/next?locale=de">

Am I doing something wrong? Or is this expected behavior? When loading /next/de manually the rewrite works fine. The page uses getServerSideProps so not sure if that may have something to do with it or not.

[linkurzweg]

@pix2D I'm having the same problem. Did you manage to find a solution for this?

[ijjk]

Hi can you provide a link to a repo with a minimal reproduction for the above behavior you are seeing? A full page transition is not expected when using next/link properly

[joafeldmann]

Has anyone successfully used the custom routes (rewrites) on vercel? See: #13347

[ijjk]

Hi @joafeldmann, the new custom routes in next.config.js already work automatically with Vercel and are being used in production on sites. Can you provide a reproduction where they are not working for you?

[ivanpetrushev]

Hi guys. What is the status of this proposal and can we have some documentation on redirects/rewrites?

[balazsorban44]

#13353 (comment)

[luknl]

https://nextjs.org/docs/api-reference/next.config.js/rewrites

[linkurzweg]

Hello. How can we use custom routes accordingly with next/link without triggering a reload?

In our case, we're trying to move our news websites to next.js. They have category and article pages. Categories are reachable under /category/subcategory and articles under /category/subcategory/article.

There can be an infinite number of subcategories that can be created by our editors, so we don't know the structure of the nesting in advance. This works fine with our current setup. We're trying to replicate this with next.js without having to resort to a custom server.
All article slugs end with an id in the form of a number, so that's how they can be differentiated from category pages.

I set up rewrites in next.config.js that look like this:

experimental: {
    async rewrites() {
        return [
            { source: '/(.*)(\\d+)', destination: '/articles/[...article]' },
            { source: '/(.*)(\\d+).html', destination: '/articles/[...article]' },
        ];
     },
 },

This works fine when I enter the url directly, so I can open an article with /category/subcategory/slug. But if I try using this with nex/link it doesn't work properly.

If I set href to /articles/[...article] and hrefAs to /category/subcategory/slug I get

Error: The provided as value (/category/subcategory/slug) is incompatible with the href value (/articles/[...article])

If I just use /category/subcategory/slug for both href and hrefAs, the pages reloads instead of just routing to the article.

How can I achieve the desired behavior with custom routes and next/link? Is it even possible? Thanks!

[pix2D]

Are you by chance using getServerSideProps? I switched to using getInitialProps because of a unrelated issue and that made things work for me (without the redirect below, but with the same <Link> like below).

The problem with getServerSideProps is that when a link is clicked it tries to load a URL like this:

/_next/data/:deployment/:locale/page.json

instead of

/_next/data/:deployment/page.json

For some reason URLs with _next don't work in rewrites, but they do work in redirects. So if you add a redirect like this:

{
  source: '/_next/data/:deployment/:locale/page.json',
  destination: '/_next/data/:deployment/page.json?locale=:locale',
  permanent: true,
},

Then it should work. Adjust to your own page names etc. From the top of my head the link then looked something like this:

<Link href="/page?locale=de" as="/de/page">
  <a>Click me</a>
</Link>

I think PR #14667 may be related also when it comes to linking.

[linkurzweg]

@pix2D thanks for your reply! We're not using getServerSideProps. However, what you wrote confuses me. How would I apply that to my example with the categories/articles above? Thank you!

[linkurzweg]

I updated to next.js 9.5 but the problem remains. @timneutkens maybe you could shed some light on this? That would be very nice, thanks in advance!

[ijjk]

Hi @linkurzweg, see my reply here #16014 (comment) for how to handle this for rewrites and next/link currently

[linkurzweg]

Thanks again! :)

[isaachinman]

Hi all, just wanted to mention that we have successfully leveraged rewrites in next-i18next@beta to deploy a serverless i18next solution that includes locale subpaths, on Vercel: i18next/next-i18next#274 (comment).

You can find the source code here.

[luknl]

Hi all! I think this issue has been fixed with Next JS 9.5? With this new feature: Support for Rewrites, Redirects, and Headers

[timneutkens]

Correct!

[valpinkman]

I'm having issues with this, it works in local but not on deployment. My subroutes /something/:slug just get a 404 :(

I can provide any infos you need, because I need to move to v2 right now

[ijjk]

@valpinkman additional info would be needed to assist, can you provide a repo with a reproduction so we can take a look?

[valpinkman]

I believe it was misconfiguration on my part, using <Link href={} as={} />, where href would just suffice. I will keep you updated

[valpinkman]

so still no luck:
here is the deployment: https://vercel.com/valpinkman/tamarindo-v2/edvem190r
and the repo to the current commit: https://github.com/valpinkman/new-tama

all the routes

• /our-products/:product
• /nos-produits/:product
• /prodotti/:product

are mapped to /products/:product which is reflected in my folder pages/products/[product].tsx

Everything else works, it does indeed work in local environment, but not in prod.

Any help is very welcome

Edit

Problem resolved, it seems that one of my resource was empty and thus breaking.

[lfades]

Support for Custom Routes Support (Rewrites, Redirects, and Headers) has been released in Next.js 9.5 🥳

Check out the official docs to learn more about the usage:

• Rewrites
• Redirects
• Headers

Before using Rewrites, Redirects or Headers, update to the latest version:

npm install next@latest

# or with yarn

yarn install next@latest

If you were using custom routes during its beta phase, migrating to the stable release consists of moving the feature out of experimental in next.config.js:

module.exports = {
  experimental: {},

  // rewrites, redirects, and headers are out of `experimental`
  async rewrites() {
    // ...
  },
}

[hisunilkumarr]

When dev = false in server.js (express - custom server). rewrite feature is not working! with basePath: false in next.js 9.5.1

server.js

const dev = false;
const nextJsApp = next({ dev, dir: './folderName' });

next.config.js

module.exports = {
  basePath: '/folderName',
  distDir: 'build',
  async rewrites() {
    return [
      {
        source: '/post/post',
        destination: '/post/post',
        basePath: false
      }
    ];
  },

Note: same scenario when dev = true then rewrite feature is working fine! with basePath: false

can anyone help with this problem!

[dbedoyat]

Guys, how i can remove ".html" extension on rewrite with next js?

Edit: Here the solution if you need it

module.exports = {
async redirects() {
    return [
      {
        source: "/:slug*.html",  // Old url with .html
        destination: "/:slug*", // Redirect without .html
        permanent: true,
      },
    ];
  }
  },

[hisunilkumarr]

When dev = false in server.js (express - custom server). rewrite feature is not working! with basePath: false in next.js 9.5.1

server.js

const dev = false;
const nextJsApp = next({ dev, dir: './folderName' });

next.config.js

module.exports = {
  basePath: '/folderName',
  distDir: 'build',
  async rewrites() {
    return [
      {
        source: '/post/post',
        destination: '/post/post',
        basePath: false
      }
    ];
  },

Note: same scenario when dev = true then rewrite feature is working fine! with basePath: false

can anyone help with this problem!

[arnaudjnn]

What about SEO?

If I redirect example.com/shop/my-products to example.com/my-product doest it creates duplicate content?

[lfades]

@arnaudjnn Redirects don't create duplicated content

[arnaudjnn]

Sorry, I spoke about Rewrites

[lfades]

Rewrites can cause duplicated content if there are links pointing to both versions, if that's the case you can also use headers or meta tags to avoid indexing some paths

[CanRau]

@arnaudjnn As far as I understand it's best practice to include the canonical meta tag in the HTML anyway https://support.google.com/webmasters/answer/139066 you "just" have to decide on one canonical URL for all

[xaun]

How do Rewrites work under the hood?

[VinayaSathyanarayana]

How can I create a custom logic for rewrites - something more than just a lookup. See #22012 and #22333.

Ability to modify slugs and reuse the already pre-rendered page has multiple use cases.

[aralroca]

I see that having a custom server the rewrites and redirects features don't apply. I think this would be very useful to be able to do a proper gradually migration, it would be great if rewrites and redirects would work together with custom server.

[timneutkens]

Can you create a new issue with a complete reproduction? The request handler for custom server / next start is the same so it should work as-is.

[aralroca]

Thanks @timneutkens for the fast response. I created the issue here with a reproducible example. Hope it helps!

[aralroca]

@timneutkens I realize that using trailingSlash: true in the configuration I must write the source of redirects and rewrites with trailingSlash... After this change, it works fine.