Things you might not know about tag revalidation in Nextjs

This week, I had an interesting experience with Next.js and tag revalidation. Suddenly, after a new feature release, we started to get a side effect every time a tag was revalidated: the main content of the page was changing even though the revalidated tag was completely unrelated to it. Here is what I learned while investigating the issue:

When you call revalidateTag, the whole page is executed on the server

Let's talk about a common scenario: a shopping cart mutation in an e-commerce. You are implementing the product listing page and want the cart to update when the user adds a product. So what do you do? You tag the cart fetch request, and then in the server action that mutates the cart, you revalidate it. Like the code below:

async function Page() {
  // get the cart
  const cart = await fetch('/api/cart', {
    next: {
      // tagging it
      tags: ['cart'],
    },
  }).then((res) => res.json());

  // get the product list
  const products = await fetch('api/products').then((res) => res.json());

  return (
    <div>
      <Cart items={cart.items} />

      <ProductList items={products} />
    </div>
  );
}

// actions/add-to-cart.ts

'use server';

function addToCart(id: string) {
  // mutate the cart
  await fetch('api/cart', {
    method: 'POST',
  });

  // revalidate its tag
  revalidateTag('cart');
}

When I first read about tag revalidation, my assumption was that Next.js would only rerender components associated with the revalidated tag. However, that's not always the case. The entire page is rendered on the server, and then on the client side, only the components that changed are rerendered. So, if after the tag revalidation, a random component changes due to another fetch call, this component is also going to be rerendered, causing an unexpected side effect.

Tag revalidation is all about data cache invalidation

Once you understand that, things start to make sense. You shouldn't associate tag revalidation with rerendering a specific component after a mutation—that is not what actually happens. The revalidateTag function invalidates the data cache associated with a tag. As a consequence, the entire page rerenders on the server to get rid of stale data, and components that are associated to this tag might rerender if the output differs from the previous render. Going back to the e-commerce example, if you don't cache the call that gets the products for the page and the data changes often, there's a high probability of having a side effect where the product listing changes when the cart tag is revalidated. So, to mitigate this issue, you would have to cache the product listing data. Now, for how long—that is a different story.

const products = await fetch('api/products', {
  // caching the product list call for 1 hour (3600 seconds)
  next: { revalidate: 3600 },
}).then((res) => res.json());

What is data cache in Next.js?

In short, the data cache is the cache that is persisted by the server so that it can be reused across different server requests. For that to work, the cache needs to be stored somewhere. By default, Next.js stores the cache as files on disk. That means if you self-host your application and have multiple server instances running, you should implement your own cache storage so it can be shared across instances. If you use Vercel, you don't need to worry about that since they have their own cache storage implementation out of the box. To implement a custom cache handler, you can follow this doc.

How do I cache my data?

Caching data in Next.js is still a bit confusing. You can use different options when calling fetch, use unstable_cache to cache functions, or use the use cache directive to cache functions or components. So, I recommend checking the documentation to see which approach suits you best. Keep in mind that the API is still under development and they might introduce breaking changes from time to time.

• Fetch cache
• unstable_cache
• use cache directive

Key takeaways

In short, when using tag revalidation, keep in mind:

• The server runs the whole page when revalidateTag is called, but the client rerenders only the components that have changed.
• revalidateTag invalidates the data cache for a given tag, and as a consequence, components dependent on this data are rerendered.
• A data that is not cached will be refetched every time a tag revalidation happens, even if the tag has nothing to do with it.
• Caching data prevents side effects when using tag revalidation. Managing cache properly is not an easy task though.

Alright, that's all I wanted to share with you about tag revalidation and data cache in Next.js. I hope you have learned something new. See you next time!