Next.js Caching skill for Codex

Done well means: every cached thing has an owner, a lifetime and a tag that a mutation invalidates; uncached request data streams behind Suspense instead of making the whole route dynamic; and you can prove what is cached from the build output and headers, not from guesses.

Step 1: find out which model the project uses

Run the bundled inventory script from the skill folder (Node 20+, no dependencies):

node scripts/cache_inventory.mjs <project-root>           # report
node scripts/cache_inventory.mjs <project-root> --strict  # exit 1 if any warning

It reports whether cacheComponents is on, every segment config, "use cache" directive, cacheLife/cacheTag call, fetch cache option, unstable_cache, and invalidation call, and warns about deprecated or incompatible usage.

Inventory says	Model	Defaults
cacheComponents: true (Next 16+)	Cache Components	Nothing is cached unless inside "use cache"; the static shell is prerendered and dynamic parts stream
Not enabled, Next 15	Previous model	fetch not cached unless cache: "force-cache"; GET route handlers not cached; routes static unless they read request data
Not enabled, Next 14 or older	Previous model, old defaults	fetch cached by default; upgrade before reasoning about anything else

Also read AGENTS.md and check the hosting target. Self-hosting on several instances needs a shared cache handler; default in-memory caches are per instance.

Cache Components model (recommended for new work on Next 16)

Enable in next.config.ts:

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

Recent 16.x releases also expect an explicit partialPrefetching setting next to it; follow the warning the dev server prints for the installed version.

Cache a data function, a component, or a whole page with the directive:

import { cacheLife, cacheTag } from "next/cache";

export async function getProduct(id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag("products", `product:${id}`);
  return db.product.findUnique({ where: { id } });
}

Rules for "use cache" scopes:

• Arguments and closed-over values become part of the cache key. They and the return value must be serializable.
• Do not call cookies(), headers() or read searchParams inside the scope. Read them outside and pass the needed value in as an argument (it then becomes part of the key). For per-user data that must not be shared, use "use cache: private" or leave it uncached.
• Default storage is in memory and per deployment. For a cache that survives instance restarts or is shared across instances, use "use cache: remote" with a configured cache handler.
• Built-in cacheLife profiles: seconds, minutes, hours, days, weeks, max (and default). Define custom profiles under cacheLife in next.config.ts instead of scattering raw numbers.

Uncached data and request APIs must sit inside <Suspense> so the rest of the route can prerender. The dev overlay reports “blocking” insights naming the component; the fix is either cache it or wrap it:

export default function Page({ params }: PageProps<"/product/[id]">) {
  return (
    <>
      <ProductDetails params={params} /> {/* cached via getProduct */}
      <Suspense fallback={<StockSkeleton />}>
        <LiveStock params={params} /> {/* uncached, streams per request */}
      </Suspense>
    </>
  );
}

new Date(), Math.random() and crypto.randomUUID() during prerender are build errors. Move them into a Suspense-wrapped component that first awaits connection() from next/server, or into a client component.

Migrating segment configs

With cacheComponents on, dynamic, revalidate, fetchCache, dynamicParams and runtime exports error. Replace them:

Old	Cache Components equivalent
dynamic = "force-dynamic", revalidate = 0, noStore()	delete; uncached is the default
dynamic = "force-static"	"use cache" + cacheLife("max") on the page or data
revalidate = 3600	"use cache" + cacheLife("hours")
fetch(url, { next: { revalidate, tags } })	wrap in a "use cache" function with cacheLife and cacheTag
unstable_cache(fn, keys, { tags, revalidate })	keeps working; migrate later to a "use cache" function
dynamicParams = false	delete; call notFound() for unknown params
generateStaticParams returning []	return at least one real param
runtime = "edge" or "nodejs"	delete; Cache Components runs on Node.js

For a large app, adopt incrementally: newer 16.x versions support export const instant = false on a segment to defer validation, plus a codemod that adds it everywhere; check the installed version’s migration guide before relying on it. Note that fetch’s old Data Cache and unstable_cache persisted across deployments, while default "use cache" storage does not; budget for a cold cache after each deploy.

Previous model (Next 15 without Cache Components)

Layer	What it holds	Control
Request memoization	duplicate fetch/React.cache calls in one render	automatic
Data Cache	fetch responses and unstable_cache results across requests	cache: "force-cache", next.revalidate, next.tags
Full Route Cache	prerendered HTML and RSC payload for static routes	static unless request APIs or uncached fetch are used; revalidate export
Router Cache (client)	RSC payloads of visited segments in the browser	experimental.staleTimes, router.refresh()

Invalidation

Situation	Call
Server action; the user must see their own write immediately	updateTag("posts") (server actions only)
Content can be briefly stale (CMS publish, catalog import)	revalidateTag("posts", "max")
Webhook or route handler that needs data gone now	revalidateTag("posts", { expire: 0 })
A specific URL or layout regardless of tags	revalidatePath("/blog/[slug]", "page")
Client view of the current route after a mutation	handled by the action response; router.refresh() from client code if needed

• revalidateTag(tag) with one argument is deprecated in Next 16; always pass a profile.
• Tag at two granularities: collection (posts) for lists and entity (post:123) for detail views. A mutation invalidates both.
• Webhook endpoints that call revalidateTag must verify a signature or secret; an open revalidation endpoint lets anyone flush your cache.

Gotchas

• A page that reads cookies() at the top level becomes fully dynamic (previous model) or blocks the shell (Cache Components). Push the read into the smallest component.
• Caching a function that returns user-specific data with plain "use cache" shares it across users if the user ID is not an argument. Treat this as a data leak.
• Tags are case-sensitive and limited to 256 characters; longer tags are silently never attached.
• Stale-after-mutation bugs are usually a missing tag on the read side, not a missing call on the write side. Compare the tags in both places.
• With Cache Components, routes stay mounted in <Activity> when navigating away, so useActionState results and form inputs persist on return; reset them explicitly.

Verification

• next build route table: each route shows the intended mode (static, dynamic or partial prerender). Record it before and after.
• Add logging: { fetches: { fullUrl: true } } to next.config in development to see fetch cache hits and misses.
• On a production build (next build && next start), mutate data and confirm the next request shows it (updateTag) or shows it after one stale request (max).
• Self-hosted ISR pages expose x-nextjs-cache (HIT, STALE, MISS) response headers; check them with curl -sI.
• node scripts/cache_inventory.mjs . --strict exits 0.

Output

| Data / route | Cached? | Lifetime | Tags | Invalidated by |
|---|---|---|---|---|
| getProduct(id) | use cache | hours | products, product:{id} | updateProduct action (updateTag) |
| /product/[id] stock | no, streams | - | - | - |
| /blog list | use cache | max | posts | CMS webhook (revalidateTag 'max') |

Follow the table with any routes whose rendering mode changed and why.