Next.js Documentation (Official Mirror)

The cacheTag function allows you to tag cached data for on-demand invalidation. By associating tags with cache entries, you can selectively purge or revalidate specific cache entries without affecting other cached data.

Usage

To use cacheTag, enable the cacheComponents flag in your next.config.js file:

filename="next.config.ts" switcher

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

filename="next.config.js" switcher
const nextConfig = {
  cacheComponents: true,
}

export default nextConfig

The cacheTag function takes one or more string values.

tsx

filename="app/data.ts" switcher

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

jsx

filename="app/data.js" switcher

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

You can then purge the cache on-demand using revalidateTag API in another function, for example, a route handler or Server Action:

tsx

filename="app/action.ts" switcher
'use server'


export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

jsx

filename="app/action.js" switcher
'use server'


export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

Good to know

Idempotent Tags: Applying the same tag multiple times has no additional effect.
Multiple Tags: You can assign multiple tags to a single cache entry by passing multiple string values to cacheTag.

tsx

cacheTag('tag-one', 'tag-two')

Limits: The max length for a custom tag is 256 characters and the max tag items is 128.

Examples

Tagging components or functions

Tag your cached data by calling cacheTag within a cached function or component:

tsx

filename="app/components/bookings.tsx" switcher

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

jsx

filename="app/components/bookings.js" switcher

export async function Bookings({ type = 'haircut' }) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

Creating tags from external data

You can use the data returned from an async function to tag the cache entry.

tsx

filename="app/components/bookings.tsx" switcher

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

jsx

filename="app/components/bookings.js" switcher

export async function Bookings({ type = 'haircut' }) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

Invalidating tagged cache

Using revalidateTag, you can invalidate the cache for a specific tag when needed:

tsx

filename="app/actions.ts" switcher
'use server'


export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}

jsx

filename="app/actions.js" switcher
'use server'


export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}