Next.js redirect permanent property creates a cache

This might be a less known property to the Nextjs redirect's permanent: true status which might catch you off guard if you are changing the URL of your website often.

Redirect with permanent vs statusCode

While working on a client's website this week, I noticed something interesting about how the permanent property of Nextjs' redirect works. What I wanted to do is to redirect to the newest URL path of the page.

For example, Prismic stores all old ids which allow those old URL paths to be rendered. This might ensure that content doesn't result in a 404, but it also means that users might end up going to an old URL path, leading to bad UX and confusion.

This is the code I had initially:

// within getStaticProps()

// If the URL path of the page changes, redirect to the newest URL path
if (doc.slug !== slug) {
  return {
    redirect: {
      permanent: true,
      destination: `/${doc.slug}`,
    },
  };
}

This would cause /old-path/ to redirect to /new-path/. But then I decided to change /new-path/ to /new-new-path/

To my suprise, when I opened /old-path/, the page redirected once again to /new-path/ instead of /new-new-path/. I spent a long time figuring out what is happening, even though this behaviour is clearly documented within Next.js documentation.

permanent - if `true` will use the 308 status code which instructs clients/search engines to cache the redirect forever.

Pay attention to the cache the redirect forever part of the documentation. This means that the page redirect will cache forever within that user's browser and if I then change the URL again, they might get a 404.

This Github issue helped me solve the problem. I decided to use the statusCode instead which doesn't cause the redirect to cache within the user's browser. My final solution ended up looking like this:

// within getStaticProps()

// If the URL path of the page changes, redirect to the newest URL path
if (doc.slug !== slug) {
  return {
    redirect: {
      statusCode: 301,
      destination: `/${doc.slug}`,
    },
  };
}

This will cause old URL paths to always redirect to the newest version, regardless of how many times the URL has changed, ie /old-path/ -> /newest-path/.

This might not be the most performant solution since we don't cache the redirect, but it will always ensure that your page URLs are always redirected to the latest and greatest URL path.

When to use redirect's permanent property

• when you're migrating an old website to a new website and changing the overall website URL structure
• when you're quite certain that you won't update the URL of the page in the foreseeable future

When to use redirect's statusCode property

• when the URL path changes relatively frequently
• when you don't have control over the URL path (eg if you are building a headless CMS website for a client)

How to reset your cache in your browser

You have probably strumbled on this article after you have experienced this edge case. To clear your cache, you can do a hard refresh in your browser (Cmd + Shift + R). You can also open the developer tools and in the network tab check the disable cache option.