Cache Tag

createCacheTag is the core function for creating cache tags that help you manage Next.js cache invalidation and updates. This library works with Next.js's "use cache" directive and cacheTag function to provide a more ergonomic API for cache management.

Basic Usage

import { createCacheTag } from "next-cache-tools";

const usersListTag = createCacheTag("users-list");

async function getUsers() {
  "use cache";
  
  usersListTag.tag();
  
  return [{ id: "1", name: "User 1" }, { id: "2", name: "User 2" }];
}

Dynamic Cache Tags

For cache tags that need to handle dynamic parameters (like user IDs, slugs, etc.), use getCacheId to generate unique cache keys:

const userTag = createCacheTag("user", {
  getCacheId: ({ id }: { id: string }) => id,
});

async function getUser(id: string) {
  "use cache";
  
  userTag.tag({ id });
  
  return { id, name: `User ${id}` };
}

The getCacheId function receives the arguments passed to .tag() and returns a string that uniquely identifies this cache entry.

Revalidation & Updates

You can invalidate or update cached data using .revalidate() and .update() methods:

const userTag = createCacheTag("user", {
  getCacheId: ({ id }: { id: string }) => id,
});

// Revalidate all user cache entries
userTag.revalidate();

// Revalidate a specific user
userTag.revalidate({ filter: { id: "user-123" } });

// Update a specific user
userTag.update({ filter: { id: "user-123" } });

For tags without getCacheId, you can revalidate or update the entire tag:

const usersListTag = createCacheTag("users-list");

// Revalidate the entire users list cache
usersListTag.revalidate();

// Update the entire users list cache
usersListTag.update();

Both methods support filter and predicate options for selective operations. See Revalidation & Updates for detailed examples.

Cache Life

Setting a Default Profile

You can set a default cache life profile when creating the tag:

const userTag = createCacheTag("user", {
  getCacheId: ({ id }: { id: string }) => id,
  cacheLife: "max", // Default profile for this tag
});

When you call .tag(), it automatically calls .life() for you. This means you don't need to call .life() separately unless you want to override the default behavior:

async function getUser(id: string) {
  "use cache";
  
  // Automatically uses "max" profile
  userTag.tag({ id });
  
  return { id, name: `User ${id}` };
}

Overriding Cache Life

You can override the default cache life by calling .life() explicitly after .tag():

const userTag = createCacheTag("user", {
  getCacheId: ({ id }: { id: string }) => id,
  cacheLife: "default", // Default profile
});

async function getUser(id: string) {
  "use cache";
  
  userTag.tag({ id });
  userTag.life({ profile: "max" }); // Override with "max"
  
  return { id, name: `User ${id}` };
}

Cache Life Profiles

Cache tags integrate with Next.js's cacheLife function to manage cache timing. You can set a default profile when creating a tag using the cacheLife option, or override it per-usage with .life().

Learn more about cache profiles and timing in the Next.js cacheLife documentation.

You can also use custom profiles:

userTag.life({
  profile: {
    stale: 5,      // Stale after 5 seconds
    revalidate: 60, // Revalidate after 60 seconds
    expire: 300,    // Expire after 300 seconds
  },
});

Methods

`.tag(args?)`

Tags the cache with the provided arguments. Automatically calls .life() with the default profile.

userTag.tag({ id: "user-123" });

`.life(options?)`

Sets the cache lifecycle profile. If called without options, uses the default profile set when creating the tag.

userTag.life({ profile: "max" });

`.revalidate(options?)`

Invalidates the cache tag. See Revalidation & Updates for details.

`.update(options?)`

Updates the cache tag. See Revalidation & Updates for details.

Cache Tag

On this page