Agent-Skills.md

Agent Skills: Caching Architecture

Configure the 4 caching layers in Next.js: request memoization, data cache, full-route cache, and router cache. Use when setting revalidation strategies, invalidating cached data with tags, or diagnosing stale data bugs. (triggers: **/page.tsx, **/layout.tsx, **/action.ts, unstable_cache, revalidateTag, Router Cache, Data Cache)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nextjs-caching

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nextjs/nextjs-caching

Skill Files

Browse the full folder contents for nextjs-caching.

Download Skill

Loading file tree…

skills/nextjs/nextjs-caching/SKILL.md

Skill Metadata

Name
nextjs-caching
Description
Configure Next.js cache layers, invalidation, and cache-component APIs. Use when choosing `fetch` caching, `use cache`, tags, or stale-data debugging in Next.js.

Caching Architecture

Priority: P1 (HIGH)

Decision Map

  • HTTP reads: start with fetch cache controls (force-cache, no-store, next.revalidate, tags). For content updated a few times per day, ISR with revalidate is often the right default.
  • Custom function/component caching: prefer use cache with cacheLife() and cacheTag() when the project uses cache components.
  • Per-render dedupe: use React cache() for repeated server reads in one render pass.
  • Mutation invalidation: revalidateTag() for data ownership, revalidatePath() for route-level refresh, router.refresh() for client view refresh after mutation.

Recipe

  1. Classify the read: static, periodically fresh, request-specific, or user-specific.
  2. Pick the narrowest cache: request memoization before persistent cache, tag invalidation before path-wide invalidation.
  3. Tag what mutates together: align tags with data ownership, not page names by habit.
  4. Keep personal data private: avoid broad route caching for request-specific state.
  5. Test stale paths: mutation -> invalidation -> refreshed UI.

Verify

  • [ ] Cache choice matches data ownership and freshness needs.
  • [ ] Mutations revalidate the tags or paths they invalidate.
  • [ ] User-specific data does not leak into shared cache.
  • [ ] Slow reads stream behind Suspense instead of blocking the whole route.
  • [ ] Existing code using unstable_cache has a migration note if cache components are now enabled.

| Layer | Where | Control | | :---------------------- | :----- | :----------------------------- | | Request Memoization | Server render | React cache() | | Data Cache | Server | fetch, use cache, tags | | Full Route Cache | Server | static rendering / revalidation | | Router Cache | Client | router.refresh() |

Anti-Patterns

  • No shared cache for personal data: request-specific state needs a private strategy or no-store path.
  • No path-wide invalidation by habit: prefer tags when data ownership is narrower.
  • No mutation without revalidation: stale writes are correctness bugs.
  • No cache folklore: verify with official cache docs for the project's enabled features.

References