nextjs-cache-architecture

Use this skill whenever the user wants to design or implement caching in a Next.js 16+ App Router project — setting up the "use cache" directive, building a…

installs

stars

karma

view original SKILL.md from skills.shclick to expand

Next.js Cache Architecture

Architect caching in a Next.js 16+ App Router project from day one — not just
dropping "use cache" where it happens to fit, but structuring the tag
registry, revalidation utilities, Suspense boundaries, and mutation wiring so
the cache stays correct as the codebase grows.

How to use this skill

Apply every rule and template below to the user's actual project. Replace
placeholders like [Entity] and [collection] with names from their codebase
before writing any code.

$ARGUMENTS

Where to look next
Most implementations only need this file. Load a reference when the task
calls for it.

If the user is...
Read

Asking how cache keys are derived, what cacheLife profiles mean, or hitting a "use cache" limitation
references/core-concepts.md

Caching anything that depends on a logged-in user
references/personalized-content.md

Reporting stale data, or doing a final review pass
references/debugging-and-checklist.md

Migrating an existing codebase off unstable_cache
references/migration-from-unstable-cache.md

Drop-in templates in assets/ (rename placeholders to match the user's
codebase):

assets/tags.ts → lib/cache/tags.ts

assets/revalidate.ts → lib/cache/revalidate.ts

assets/SuspenseOnSearchParams.tsx → components/SuspenseOnSearchParams.tsx

The architecture in one breath

A correct cache implementation has three load-bearing pieces. Build all three
on day one — adding them later is much harder than getting them right up
front.

Tag registry (lib/cache/tags.ts) — every tag string lives here. No
raw strings anywhere else.

Revalidation utilities (lib/cache/revalidate.ts) — every
updateTag() lives here. Mutations import from this file.

Cache placement on data, not on pages — "use cache" goes on
data-fetching functions or cached child components. Page components
orchestrate Suspense boundaries; the children fetch.

Once those three are in place, the rest is just applying them consistently.

Step 1 — Enable Cache Components

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

Step 2 — Build the cache tag registry

File: lib/cache/tags.ts (template: assets/tags.ts)

Use the assets/tags.ts template. The as const satisfies TagRegistry shape
gives literal types and rejects malformed entries at compile time.

// lib/cache/tags.ts (skeleton — full template in assets/tags.ts)

export const CACHE_TAGS = {
  // Collection tags — one per logical data group, always present.
  [collection]: "[collection]",

  // Entity tag factories — only when a mutation targets a single entry.
  [entity]: (id: string | number) => `[entity]:${id}`,
} as const;

Step 3 — Build revalidation utilities

File: lib/cache/revalidate.ts (template: assets/revalidate.ts)

All updateTag() calls live here. Mutations import these functions — they
never call updateTag() directly.

// lib/cache/revalidate.ts
"use server";

import { updateTag } from "next/cache";
import { CACHE_TAGS } from "./tags";

function updateTags(tags: string[]) {
  for (const tag of tags) updateTag(tag);
}

// Bulk — any entry in the collection changed.
export async function revalidate[Collection]Cache() {
  updateTags([CACHE_TAGS.[collection]]);
}

// Surgical — one specific entry changed.
// Only write this if `CACHE_TAGS.[entity]` factory exists in the registry.
export async function revalidate[Entity]Cache(id: string | number) {
  updateTags([
    CACHE_TAGS.[collection], // always invalidate the parent collection too
    CACHE_TAGS.[entity](id),
  ]);
}

Step 4 — Implement data fetching

Place "use cache" in data-fetching functions. Never fetch inside page
components — page components orchestrate, they do not fetch.

// lib/data/[domain].ts
import { cacheLife, cacheTag } from "next/cache";
import { CACHE_TAGS } from "@/lib/cache/tags";

const BASE_URL = process.env.API_BASE_URL!;

// Good: collection fetch.
export async function get[Collection]() {
  "use cache";
  cacheLife("hours");
  cacheTag(CACHE_TAGS.[collection]);

  const res = await fetch(`${BASE_URL}/[endpoint]`);
  return res.json();
}

// Good: entity fetch.
export async function get[Entity](id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag(CACHE_TAGS.[collection]);
  // Add CACHE_TAGS.[entity](id) only if a mutation calls updateTag on this entry.

  const res = await fetch(`${BASE_URL}/[endpoint]/${id}`);
  return res.json();
}

// Bad: fetching in a page component bypasses caching and invalidation.
export default async function Page() {
  const res = await fetch("/api/items");
  const data = await res.json();
  return <View data={data} />;
}

Step 5 — Structure rendering boundaries

Every page follows this shape:

Page component (sync, orchestration only — no data fetching)
  ├── Static shell (layout, nav — no data)
  ├── <Suspense> → cached shared content
  └── <Suspense> → dynamic personalized content

Standard page

// app/[route]/page.tsx
import { Suspense } from "react";
import { cacheLife, cacheTag } from "next/cache";
import { CACHE_TAGS } from "@/lib/cache/tags";
import { get[Collection] } from "@/lib/data/[domain]";

export default function AnyPage() {
  return (
    <>
      <StaticShell />

      <Suspense fallback={<SharedSkeleton />}>
        <SharedContent />
      </Suspense>

      <Suspense fallback={<PersonalizedSkeleton />}>
        <PersonalizedSection />
      </Suspense>
    </>
  );
}

async function SharedContent() {
  "use cache";
  cacheLife("hours");
  cacheTag(CACHE_TAGS.[collection]);

  const data = await get[Collection]();
  return <[Collection]List data={data} />;
}

Dynamic route page

// app/[domain]/[id]/page.tsx
import { Suspense } from "react";
import { cacheLife, cacheTag } from "next/cache";
import { CACHE_TAGS } from "@/lib/cache/tags";
import { get[Entity] } from "@/lib/data/[domain]";

export default function EntityPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  return (
    <Suspense fallback={<EntitySkeleton />}>
      <EntityDetail params={params} />
    </Suspense>
  );
}

async function EntityDetail({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return <CachedEntityView id={id} />;
}

async function CachedEntityView({ id }: { id: string }) {
  "use cache";
  cacheLife("hours");
  cacheTag(CACHE_TAGS.[collection]);
  // Add CACHE_TAGS.[entity](id) only if a mutation needs surgical invalidation.

  const item = await get[Entity](id);
  return <[Entity]View item={item} />;
}

Filtered / search params page

// app/[route]/page.tsx
import { cacheLife, cacheTag } from "next/cache";
import { CACHE_TAGS } from "@/lib/cache/tags";
import { get[Collection]ByFilter } from "@/lib/data/[domain]";
import SuspenseOnSearchParams from "@/components/SuspenseOnSearchParams";

export default function FilteredPage({
  searchParams,
}: {
  searchParams: Promise<Record<string, string>>;
}) {
  return (
    <SuspenseOnSearchParams fallback={<FilteredListSkeleton />}>
      <FilteredList searchParams={searchParams} />
    </SuspenseOnSearchParams>
  );
}

async function FilteredList({
  searchParams,
}: {
  searchParams: Promise<Record<string, string>>;
}) {
  "use cache";
  cacheLife("minutes");
  cacheTag(CACHE_TAGS.[collection]);
  // searchParams is an argument → auto-keyed per unique param combination.

  const { q = "", page = "1" } = await searchParams;
  return await get[Collection]ByFilter(q, page);
}

A standard <Suspense> does not re-trigger its fallback on client-side
navigation when only searchParams changes. Use SuspenseOnSearchParams
(template: assets/SuspenseOnSearchParams.tsx) on every page with search or
filter params.

Step 6 — Handle personalized content

Read cookies() / headers() / auth() outside the cache boundary and
pass the value as a prop. The argument becomes part of the auto-generated
cache key, so each user gets their own entry. Calling any of those APIs
inside a "use cache" function throws or produces wrong behavior.

See references/personalized-content.md for the full read-outside / cache-inside
pattern and the rare "use cache: private" exception.

Step 7 — Wire mutations to invalidation

Mutations call revalidation utilities and never reach for updateTag()
themselves. This keeps the cache layer mechanical and auditable from one
file, and lets you add observability (logging, tracing) in one place.

// app/actions/[domain].ts
"use server";

import {
  revalidate[Collection]Cache,
  revalidate[Entity]Cache,
} from "@/lib/cache/revalidate";

export async function create[Entity](payload: unknown) {
  await db.[entity].create(payload);
  await revalidate[Collection]Cache();
}

export async function update[Entity](id: string | number, payload: unknown) {
  await db.[entity].update(id, payload);
  await revalidate[Entity]Cache(id); // requires the surgical utility to be exported
}

updateTag vs revalidateTag

Two APIs for two different needs:

API
Effect
Call from

updateTag(tag)
Immediate — the same request sees fresh data
Server actions, via revalidate.ts

revalidateTag(tag, "max")
Background stale-while-revalidate — next request sees fresh data
Route handlers, webhooks

revalidateTag always takes a second argument ("max" for
stale-while-revalidate, { expire: 0 } for immediate hard expiry). The
single-argument form is deprecated and silently does nothing in some
configurations.

Common mistakes

When the cache misbehaves, walk these in order. The first six catch nearly
everything; only run next build after the rest pass. The full debug walk
and a sign-off checklist are in references/debugging-and-checklist.md.

Symptom or smell
Fix

Function runs uncached on every request
"use cache" is after an await — move it to be the first statement.

Cached function throws or returns wrong data per user
Move cookies() / headers() / auth() outside; pass values as arguments.

updateTag does nothing
Tag string typo, or no cacheTag ever registered the matching tag.

Mutation completes but the list still reads stale
Revalidation utility called before the write, or not called at all.

Whole page re-renders even though only one section changed
A dynamic child sits inside a cached parent — split with <Suspense>.

Filter UI doesn't show a loading state on navigation
Plain <Suspense> — switch to SuspenseOnSearchParams.

Page marked dynamic when you expected static
Run next build; trace the leaked dynamic API in the route's source tree.

Page component fetches data directly
Move the fetch into a cached child; pages should orchestrate, not fetch.

For the full debug walk and a sign-off checklist, see
references/debugging-and-checklist.md. To verify the static parts of a
finished implementation against the user's project, run
scripts/audit.mjs <project-root> — usage and what it checks are documented
in README.md.

don't have the plugin yet? install it then click "run inline in claude" again.

added explicit inputs section with env vars and edge cases, broke out procedure into seven numbered steps with clear input/output for each, extracted decision trees for common scenarios and error states, defined output contract with file locations and completeness criteria, and outcome signal with verifiable success metrics.

intent

architect caching in a next.js 16+ app router project from day one, not just dropping "use cache" where it happens to fit. structure the tag registry, revalidation utilities, suspense boundaries, and mutation wiring so the cache stays correct as the codebase grows. use this skill whenever the user wants to design or implement caching in a next.js 16+ app router project, migrate from unstable_cache, debug stale data, or review cache placement for correctness.

inputs

next.js version: 16+ with app router enabled.
cacheComponents flag: must be set to true in next.config.ts before starting.
environment variables: API_BASE_URL or equivalent for data-fetching functions.
database or API access: to understand mutation triggers and what tags need invalidation.
existing codebase structure: project root, lib/, app/, and components/ directories (or equivalents).
edge cases to handle: rate limits on cache invalidation, network timeouts on fetch, auth expiry between requests, empty result sets, typos in tag strings, stale-while-revalidate vs immediate expiry semantics.

procedure

step 1: enable cache components

input: next.config.ts file.

open next.config.ts.
set cacheComponents: true in the config object.
verify the file exports a valid NextConfig. output: next.config.ts with cacheComponents enabled; next build will not error.

step 2: build the cache tag registry

input: list of data domains (e.g., products, users, orders) and their entities (e.g., product, user, order).

create lib/cache/tags.ts.
use the template at assets/tags.ts as a starting point.
define CACHE_TAGS object with collection-level tags (always present) and entity-level tag factories (only if a mutation targets a single entry).
use as const satisfies TagRegistry to get literal types and compile-time validation.
replace [collection] and [entity] placeholders with actual names from the codebase (e.g., products, product). output: lib/cache/tags.ts with all collection and entity tags defined; no raw tag strings anywhere else in the project.

step 3: build revalidation utilities

input: tag registry from step 2; list of all mutations that modify data.

create lib/cache/revalidate.ts.
use the template at assets/revalidate.ts as a starting point.
implement updateTags() helper to loop over an array and call updateTag() on each.
write one revalidate[Collection]Cache() function per collection (bulk invalidation).
write one revalidate[Entity]Cache(id) function per entity (surgical invalidation), but only if updateTag will be called on the specific entity tag in mutations.
always invalidate the parent collection tag alongside the entity tag (to catch any list-level side effects).
mark the file "use server" at the top. output: lib/cache/revalidate.ts with all revalidate*Cache() functions exported; mutations will import and call these, never updateTag() directly.

step 4: implement data fetching functions

input: api endpoints, database queries, or external data sources; cacheLife and cacheTag requirements from the business logic.

create or edit lib/data/[domain].ts for each data domain.
write async functions for collection fetches (getCollection) and entity fetches (getEntity).
place "use cache" as the first statement (before any await or side effects).
call cacheLife() with a duration (e.g., "hours", "minutes", "days") based on how fresh the data needs to be.
call cacheTag() with the collection tag from CACHE_TAGS; add the entity tag only if a mutation will call revalidate[Entity]Cache(id).
perform the fetch or database query after the cache directives.
return parsed JSON or the query result. output: lib/data/[domain].ts with caching applied to all data-fetching functions; each function caches its result and participates in tag-based invalidation.

step 5: structure rendering boundaries

input: page components, shared content sections, personalized sections, and their data dependencies.

for each page component, identify static content (layout, navigation), shared cached content, and dynamic personalized content.
wrap each distinct section in a boundary with a fallback UI.
move data fetching out of the page component itself; page components orchestrate only.
create async child components (or cached server components) that hold "use cache" directives and call data-fetching functions.
for standard (non-dynamic) pages, place one for shared content and one for personalized content.
for dynamic routes ([id]/page.tsx), wrap the entity detail in a and fetch inside an async child component.
for pages with search or filter params, use the SuspenseOnSearchParams component (template: assets/SuspenseOnSearchParams.tsx) instead of plain , because plain does not re-trigger its fallback when only searchParams changes on client-side navigation.
set cacheLife("minutes") for filtered results (higher churn) and cacheLife("hours") for collections and entities (lower churn). output: page and component files with clear Suspense boundaries; data fetching isolated to cached child components; page components reduced to orchestration only.

step 6: handle personalized content

input: cookies, headers, or auth state that varies per user; cached components that need user-specific data.

call cookies(), headers(), or auth() outside the "use cache" boundary (at the page or parent component level).
extract the needed value (e.g., user ID, role, auth token) and pass it as a prop to the cached child component.
the cached child receives that prop and uses it in the fetch or computation inside "use cache".
the cache key automatically includes the prop value, so each user gets their own cache entry.
if cookies() or headers() is called inside a "use cache" function, next.js will throw or produce incorrect caching behavior.
for the rare case of truly private, request-scoped data, use "use cache: private" (documented in references/personalized-content.md). output: personalized content correctly cached per user; no auth APIs called inside cache boundaries.

step 7: wire mutations to invalidation

input: server actions or route handlers that create, update, or delete data; revalidation utilities from step 3.

create or edit app/actions/[domain].ts for each domain.
mark the file "use server" at the top.
for each mutation (create[Entity], update[Entity], delete[Entity]), import the corresponding revalidate*Cache() functions from lib/cache/revalidate.ts.
inside the mutation, perform the database write or API call first.
call revalidate[Collection]Cache() for bulk invalidation (after any create or delete that affects the list).
call revalidate[Entity]Cache(id) for surgical invalidation (after an update to a specific entry), if the utility exists.
return the result or a success signal. output: app/actions/[domain].ts with all mutations calling revalidate*Cache() functions; updateTag() never called directly from the codebase.

decision points

if the user asks about updateTag vs revalidateTag: use updateTag() inside server actions via revalidate.ts for immediate invalidation (same request sees fresh data). use revalidateTag() in route handlers or webhooks for background stale-while-revalidate (next request sees fresh data). revalidateTag always requires a second argument ("max" for stale-while-revalidate, { expire: 0 } for immediate hard expiry); the single-argument form is deprecated and silently does nothing in some configurations.

if the user is migrating from unstable_cache: see references/migration-from-unstable-cache.md. the migration pattern is (1) move unstable_cache calls into data-fetching functions with "use cache" instead, (2) extract tag strings into CACHE_TAGS, (3) replace revalidatePath() with updateTag() calls in revalidate.ts.

if the user reports stale data after a mutation: check in order: (1) is the mutation calling revalidate[Collection]Cache() or revalidate[Entity]Cache()? (2) does the tag string in the mutation match exactly the tag registered in CACHE_TAGS? (3) did the mutation complete before the fetch, or is the mutation still in flight? (4) is updateTag being called at all, or only revalidateTag (which is background)? if still unresolved, see references/debugging-and-checklist.md.

if the filter or search params UI does not show a loading state on client-side navigation: the page is using plain . switch to SuspenseOnSearchParams (assets/SuspenseOnSearchParams.tsx) so the fallback re-triggers when searchParams change.

if a cached function throws or returns wrong data per user: check whether cookies(), headers(), or auth() is called inside the "use cache" boundary. move those calls outside; pass the extracted value as a prop.

if "use cache" is not working: verify (1) "use cache" is the first statement in the function (before any await), (2) cacheComponents: true is set in next.config.ts, (3) next build completes without marking the route dynamic.

output contract

the implementation is complete and correct when:

lib/cache/tags.ts exists with all collection and entity tags defined as const entries; no raw tag strings appear elsewhere in the codebase.
lib/cache/revalidate.ts exists with updateTags() helper and one revalidate*Cache() function per domain; every mutation imports from this file.
lib/data/[domain].ts files exist with getCollection and getEntity functions; each function has "use cache" as the first statement, followed by cacheLife(), cacheTag(), and the fetch or query.
page and component files follow the structure: page orchestrates, wraps sections, async children own the "use cache" directives and data fetching.
filtered or search params pages use SuspenseOnSearchParams instead of plain .
personalized content reads cookies(), headers(), or auth() outside the cache boundary and passes values as props.
app/actions/[domain].ts files exist with server actions that call revalidate*Cache() after writes; no updateTag() called directly.
next build completes successfully without marking routes dynamic that should be static.
scripts/audit.mjs (if available) passes or reports only minor lint-like issues, not structural errors.

outcome signal

the skill worked when:

data-fetching functions run once per cache window (verify by checking server logs or network tab: same endpoint called only on first request, then cached).
after a mutation, stale data disappears immediately on the next page load or component re-render (not on the next user session).
filtered or search results show a loading skeleton when searchParams change on client-side navigation (if SuspenseOnSearchParams is in use).
personalized content (e.g., user-specific lists) is correctly cached per user; user A sees user A's data, user B sees user B's data, no cross-user leaks.
next build output shows all routes marked as either fully static or correctly dynamic (no unexpected "routes with incompatible config" warnings).
when you run next build and then inspect the .next/cache/data directory, tag-based cache entries exist and correspond to the tags in CACHE_TAGS.