caching

JasonPaff's avatarfrom JasonPaff

Enforces Head Shakers 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.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 5, 2025
[Code Generation]

When & Why to Use This Skill

This Claude skill automates and enforces standardized caching strategies across React and Next.js applications. By integrating React cache(), Next.js unstable_cache, Upstash Redis, and Cloudinary, it ensures consistent implementation of cache keys, TTL settings, and invalidation patterns, significantly reducing architectural debt and improving application performance.

Use Cases

  • Implementing a robust 4-layer caching strategy (React, Next.js, Redis, Cloudinary) to optimize data fetching and minimize server latency.
  • Standardizing cache key generation and TTL configurations using project-specific constants to prevent cache collisions and ensure data consistency.
  • Automating cache invalidation workflows by seamlessly injecting RevalidationService calls into server actions following data mutations.
  • Detecting and auto-fixing architectural violations in caching patterns to maintain code quality and performance standards across large-scale web projects.
namecaching
descriptionEnforces 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.

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