Caching

Caching Skill

Purpose

This skill enforces the project caching conventions automatically during cache implementation. It ensures consistent patterns across the 4-layer caching strategy:

1. React cache() - Same-request deduplication (e.g., getCurrentClerkUserId, getOptionalUserId)
2. Next.js unstable_cache() - Cross-request caching with tag-based invalidation (primary)
3. Upstash Redis - High-traffic public data, distributed locks, rate limiting, view tracking
4. Cloudinary - Image transformation and CDN-level caching

Activation

This skill activates when:

• Working with CacheService domain-specific helpers (.bobbleheads, .collections, .users, .search, .redisSearch, .analytics, .featured)
• Implementing cached data fetching in facades
• Setting up cache invalidation after mutations using CacheRevalidationService
• Working with Redis operations via RedisOperations class
• Using REDIS_KEYS for view tracking, locks, or rate limiting
• Configuring cache tags and TTL values
• Using CACHE_KEYS, CACHE_CONFIG, REDIS_TTL, or CacheTagGenerators
• Implementing request-level deduplication with React cache()

Workflow

1. Detect caching work (imports from CacheService, CacheRevalidationService, CACHE_KEYS, or CacheTagGenerators)
2. Load references/Caching-Conventions.md
3. Generate/modify code following all conventions
4. Scan for violations of caching patterns
5. Auto-fix all violations (no permission needed)
6. Report fixes applied

Key Patterns

CacheService Domain Helpers

• Use CacheService.bobbleheads.{method}() for bobblehead caching
• Use CacheService.collections.{method}() for collection caching
• Use CacheService.users.{method}() for user caching
• Use CacheService.search.{method}() for search caching (Next.js unstable_cache)
• Use CacheService.redisSearch.{method}() for high-traffic public search (Redis)
• Use CacheService.analytics.{method}() for analytics caching
• Use CacheService.featured.{method}() for featured content caching

Cache Invalidation

• Use CacheRevalidationService.{domain}.on{Operation}() for coordinated invalidation
• Use CacheService.invalidateByTag() for direct tag-based invalidation
• Always invalidate cache after mutations in server actions
• Check RevalidationResult.isSuccess and log failures to Sentry as warnings

Constants and Utilities

• Use CACHE_KEYS.{DOMAIN}.{METHOD}() for cache key generation
• Use CacheTagGenerators.{domain}.{method}() for tag generation
• Use CACHE_CONFIG.TTL.{LEVEL} for TTL values:
  • REALTIME (30s), SHORT (5 min), MEDIUM (30 min), LONG (1 hr)
  • EXTENDED (4 hr), PUBLIC_SEARCH (10 min), DAILY (24 hr), WEEKLY (7 days)
• Use REDIS_KEYS.{NAMESPACE}.{METHOD}() for Redis-specific keys (VIEW_TRACKING, LOCKS, RATE_LIMIT)
• Use REDIS_TTL.{CATEGORY} for Redis-specific TTL values
• Use createHashFromObject() for generating option hashes in cache keys

Usage Pattern Reference

Caching Layer Selection Guide

References

• references/Caching-Conventions.md - Complete caching conventions