caching

name	caching
description	Enforces project caching conventions when implementing cache layers using React cache(), Next.js unstable_cache, Upstash Redis, and Cloudinary. This skill ensures consistent patterns for cache keys, tags, TTL configuration, cache invalidation, and domain-specific CacheService helpers.
user-invocable	false

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

Use Case	CacheService Helper	Invalidation Service
Bobblehead by ID	CacheService.bobbleheads.byId()	CacheRevalidationService.bobbleheads.onUpdate()
Collection list	CacheService.collections.byUser()	CacheRevalidationService.collections.onCreate()
User profile	CacheService.users.profile()	CacheRevalidationService.users.onProfileUpdate()
Public search	CacheService.redisSearch.publicDropdown()	CacheService.search.invalidatePublic()
Analytics	CacheService.analytics.viewCounts()	CacheRevalidationService.analytics.onViewRecord()
Social (likes)	Tag-based via CacheTagGenerators	CacheRevalidationService.social.onLikeChange()
View tracking	REDIS_KEYS.VIEW_TRACKING.* + Redis ops	TTL-based expiry (no explicit invalidation)

Caching Layer Selection Guide

Use Case	Recommended Layer	Rationale
Same-request deduplication	React cache()	Prevents redundant calls within single render (implemented for auth)
Entity data (bobbleheads, collections)	unstable_cache	Tag-based invalidation, automatic revalidation
High-traffic public search	Redis	Distributed, fast, handles scale
View tracking deduplication	Redis	Distributed, TTL-based expiry
Rate limiting	Redis	Distributed counters, automatic TTL expiry
Distributed locks	Redis	Prevents concurrent updates
Image transformations	Cloudinary	CDN-level caching, on-the-fly transforms

References

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