How to Use revalidateTag in Next.js for Cache Control

In Next.js, revalidateTag is used to mark cache tags for revalidation, allowing you to update cached data selectively. You call revalidateTag('tagName') in server actions or API routes to trigger cache refresh for components using that tag.

Syntax

The revalidateTag function takes a single string argument representing the cache tag you want to refresh. This tag must match the one used in your components with cacheTags or fetch options.

• revalidateTag(tag: string): Promise - triggers revalidation for the given tag.

typescript

import { revalidateTag } from 'next/cache';

// Usage example
await revalidateTag('my-cache-tag');

Example

This example shows a Next.js API route that updates some data and then calls revalidateTag to refresh components tagged with 'products'. The page component uses fetch with cacheTags to mark its cache.

typescript

import { revalidateTag } from 'next/cache';

// API route to update product data
export async function POST(request) {
  // Imagine updating product data here

  // Revalidate cache tagged 'products'
  await revalidateTag('products');

  return new Response('Products updated and cache revalidated');
}

// In a server component
export default async function Products() {
  const res = await fetch('https://api.example.com/products', {
    next: { tags: ['products'] }
  });
  const products = await res.json();

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

Output

<ul><li>Product 1</li><li>Product 2</li><li>Product 3</li></ul>

Common Pitfalls

• Not matching the tag name between revalidateTag and the component's cacheTags causes no cache refresh.
• Calling revalidateTag on the client side or outside server actions/API routes will not work.
• Forgetting to await revalidateTag can cause race conditions where cache is not updated in time.

typescript

import { revalidateTag } from 'next/cache';

// Wrong: tag name mismatch
await revalidateTag('wrong-tag'); // Does not refresh 'products' cache

// Correct:
await revalidateTag('products');

Quick Reference

Function	Description	Usage Example
revalidateTag(tag: string)	Triggers cache revalidation for the given tag	await revalidateTag('products')
cacheTags (fetch option)	Tags cache for a fetch request to enable selective revalidation	fetch(url, { next: { tags: ['products'] } })
Usage context	Only works in server actions, API routes, or server components	Use inside async server functions

Key Takeaways

Use revalidateTag with the exact tag name used in your component's cacheTags to refresh cache.

Call revalidateTag only in server actions or API routes, never on the client side.

Always await revalidateTag to ensure cache updates before responding.

Combine revalidateTag with fetch cacheTags for efficient selective cache control.

Mismatched tags or calling in wrong context will prevent cache revalidation.