Skip to main content
Version: Next

cacheTag Function

The cacheTag function allows you to add tags to your cache entries, making it easier to manage and invalidate related cache entries together.

Basic Usage

async function fetchUserData(userId: string) {
'use cache';

// Add a tag to this cache entry
cacheTag(`user:${userId}`);

const userData = await db.users.findOne(userId);
return userData;
}

Why Use Tags?

Tags are useful when you want to:

  • Group related cache entries
  • Invalidate multiple cache entries at once
  • Manage cache entries by category
  • Implement targeted cache invalidation

Example Use Cases

async function fetchGuildData(guildId: string) {
'use cache';

// Tag all guild-related data
cacheTag(`guild:${guildId}`);

const [settings, members, roles] = await Promise.all([
db.guilds.findOne(guildId),
db.members.find({ guildId }),
db.roles.find({ guildId }),
]);

return { settings, members, roles };
}

Categorizing Cache Entries

async function fetchUserStats(userId: string) {
'use cache';

// Add multiple tags for different categories
cacheTag(`user:${userId}`);
cacheTag('stats');

const stats = await calculateUserStats(userId);
return stats;
}

Targeted Revalidation

// Later in your code
import { revalidateTag } from '@commandkit/cache';

// This will invalidate all cache entries tagged with 'user:123'
await revalidateTag('user:123');

Best Practices

  1. Use Consistent Naming:

    • Follow a consistent pattern (e.g., type:id)
    • Make tags descriptive and meaningful
    • Use hierarchical tags when appropriate
  2. Group Related Data:

    • Tag related cache entries with the same tag
    • Use multiple tags for cross-category entries
    • Consider data relationships when tagging
  3. Avoid Over-tagging:

    • Don't add unnecessary tags
    • Use tags purposefully
    • Consider the impact on revalidation

Common Patterns

Resource-based Tags

async function fetchUserResources(userId: string) {
'use cache';

// User resources
cacheTag(`user:${userId}`);
cacheTag(`user:${userId}:profile`);
cacheTag(`user:${userId}:settings`);

return await Promise.all([
fetchUserProfile(userId),
fetchUserSettings(userId),
]);
}

async function fetchGuildResources(guildId: string) {
'use cache';

// Guild resources
cacheTag(`guild:${guildId}`);
cacheTag(`guild:${guildId}:members`);
cacheTag(`guild:${guildId}:roles`);

return await Promise.all([
fetchGuildMembers(guildId),
fetchGuildRoles(guildId),
]);
}

Category-based Tags

async function fetchContent() {
'use cache';

// Content categories
cacheTag('content:announcements');
cacheTag('content:rules');
cacheTag('content:welcome');

return await Promise.all([
fetchAnnouncements(),
fetchRules(),
fetchWelcomeMessage(),
]);
}

async function fetchSystemData() {
'use cache';

// System categories
cacheTag('system:config');
cacheTag('system:stats');
cacheTag('system:logs');

return await Promise.all([fetchConfig(), fetchStats(), fetchLogs()]);
}