bh611627 Instructions
When to Use
- Use for revalidateTag, stampedes, Redis, fetch cache hierarchy.
- Prefer
next-server-patternsfor where caching sits in the tree. - Prefer
client-data-fetchingfor TanStack Query caches.
Design server-side caching for Next.js under load. Pair with next-server-patterns. Read server-caching-patterns.md.
Hierarchy
| Layer | Use for | Invalidate with |
|---|---|---|
| Full route static | Public marketing pages | rebuild / revalidatePath |
fetch / data cache tags |
Shared public data | revalidateTag |
unstable_cache / cache |
Expensive server compute | key + tags |
| External Redis | Cross-instance / cross-runtime | TTL + explicit delete |
| TanStack Query | Client interactive data | client-data-fetching |
- Classify data: public static, public dynamic, per-user - different keys and invalidation.
- Tags: granular
revalidateTagkeys; document which Server Actions invalidate which tags. - Stampedes: on expiry, many misses hit origin - singleflight, stale-while-revalidate, or TTL jitter.
unstable_cache/cache: wrap DB or HTTP fan-out; keys must include tenant and all inputs that affect output; verify API name against installed Next.- External Redis: cross-region or cross-runtime shared cache; serialization, TTL, namespacing; degrade vs fail-closed on Redis down.
- Personalization: never cache HTML that embeds private user data under a shared URL.
- Metrics: log cache hit/miss rates without PII (
observability-handbook).
Outcomes
- Tag table + invalidation flow + stampede strategy paragraph per hot route.
Output Rules
State Next version from lockfile; behavior differs by minor - say “verify against installed Next”.
Scope and boundaries
- In scope: Next cache APIs, tags, external cache integration design.
- Out of scope: CDN full-page rules at an edge provider unless the user names the product.
Safety
- read-only design; no production Redis URLs in output.
Troubleshooting
- Stale UI after mutation: missing
revalidatePath/ tag typo. - Redis memory: TTL mandatory; max entry size cap.
- Per-user leak: shared tag used for personalized HTML - split keys.
- Stampede after deploy: cold cache - warm critical tags or use SWR.
Related skills
next-server-patterns- cache placementclient-data-fetching- client vs server cacheobservability-handbook- cache miss metricsedge-runtime-handbook- Edge cache limits
GitHub: https://github.com/bh611627/skillcodex/tree/main/skills/server-caching-handbook/SKILL.md
npm: https://www.npmjs.com/package/@skillcodex/skills