Nextjs Cache Architecture

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.

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.

1. Tag registry (lib/cache/tags.ts) — every tag string lives here. No raw strings anywhere else. 2. Revalidation utilities (lib/cache/revalidate.ts) — every updateTag() lives here. Mutations import from this file. 3. 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:

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.

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.

Core Concepts

Background reading for the nextjs-cache-architecture skill. Load this when the agent needs to explain why the architecture is shaped the way it is, or when the user asks how cache keys are derived, what cacheLife profiles mean, or what the hard limits of "use cache" are.

Contents

• Auto cache key generation
• `"use cache"` placement rules
• Cache duration reference
• Limitations

Auto cache key generation

Next.js generates a unique cache key for every "use cache" function automatically. You never construct cache keys manually.

// Good: every unique resourceId produces a separate cache entry — automatically.
async function Parent({ resourceId }: { resourceId: string }) {
  const fetchData = async (filter: string) => {
    "use cache";
    // key = [buildId] + [fn hash] + resourceId (closure) + filter (argument)
    return fetch(`/api/resources/${resourceId}?filter=${filter}`);
  };
  return fetchData("active");
}

Tags are for invalidation. Auto-keying handles scoping. These are different concerns and should not be conflated.

"use cache" placement rules

"use cache" must be the first statement in the function body — before any await. If it appears after an await, Next.js silently ignores it and the function runs uncached on every request.

Cache duration reference

For fine-grained control, pass an object instead of a profile name:

import { cacheLife } from "next/cache";

cacheLife({
  stale: 3600,      // serve stale for up to 1 hour
  revalidate: 7200, // background revalidation every 2 hours
  expire: 86400,    // hard expiration at 1 day
});

Limitations

• Edge runtime is not supported — "use cache" requires Node.js.
• Static export (output: "export") is not supported.
• Math.random() and Date.now() inside "use cache" execute once at build

time, not per request. They will appear "stuck" on a single value.

• cacheTag() accepts max 128 tags per call and max 256 characters per tag.

Tags exceeding these limits are silently dropped with a console warning.

For request-time non-determinism inside cached output, defer execution with connection():

import { connection } from "next/server";

async function DynamicContent() {
  await connection(); // defers execution to request time
  const id = crypto.randomUUID(); // different per request
  return <div>{id}</div>;
}

Debugging and Post-Implementation Checklist

Background reading for the nextjs-cache-architecture skill. Load this when cache behavior is wrong — stale data, no invalidation, unexpected freshness — or when reviewing an implementation before sign-off.

Contents

• Debugging order
• Post-implementation checklist

Debugging order

When cache behavior is wrong, walk these checks in order. The first six catch the vast majority of issues; only run next build after the rest pass.

1. Is "use cache" the first statement in the function body, before any await? If it appears after an await, Next.js ignores it. 2. Is a dynamic API (cookies, headers, auth) called inside a cached function? Move the read outside and pass the value as an argument. 3. Does the collection tag in cacheTag() exactly match the tag string in the registry? A typo silently creates a separate, never-invalidated tag. 4. If surgical invalidation is needed, does the entity tag factory exist in lib/cache/tags.ts? Calling updateTag with a string that no cacheTag ever registered is a no-op. 5. Is the revalidation utility actually called after the mutation completes? Calling it before the write means the cache repopulates with stale data. 6. Are Suspense boundaries correctly isolating dynamic from cached sections? A dynamic child inside a cached parent forces the parent to re-render too. 7. Run next build and inspect the static vs dynamic route output. Routes marked dynamic that you expected to be static usually point at a leaked request-time API.

Post-implementation checklist

Use this as a final review pass. Every item below should be checked off before treating the cache architecture as production-ready.

Migrating from unstable_cache

Background reading for the nextjs-cache-architecture skill. Load this when the user has existing code calling unstable_cache (Next.js 13/14/15) and wants to move to the "use cache" directive on Next.js 16.

Why migrate

unstable_cache is deprecated in Next.js 16. The new directive-based API fixes three architectural issues that made unstable_cache painful to use correctly:

• Manual cache keys were error-prone — closure variables silently leaked

into output. The new directive auto-keys on arguments and closures.

• String tags scattered across files had no single source of truth.

The architecture in SKILL.md centralizes them in lib/cache/tags.ts.

• `revalidate` as a number on every call site mixed lifecycle policy

with the fetch logic. cacheLife() separates the two.

The four mechanical rewrites

1. Function wrap → directive

// Bad: unstable_cache wrapper, manual key array.
import { unstable_cache } from "next/cache";

export const getPosts = unstable_cache(
  async () => {
    const res = await fetch(`${BASE_URL}/posts`);
    return res.json();
  },
  ["posts"],            // cache key — repeated everywhere
  { tags: ["posts"], revalidate: 3600 },
);

// Good: directive at the top of the function body.
import { cacheLife, cacheTag } from "next/cache";
import { CACHE_TAGS } from "@/lib/cache/tags";

export async function getPosts() {
  "use cache";
  cacheLife("hours");
  cacheTag(CACHE_TAGS.posts);

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

2. Manual key array → auto-keying

unstable_cache required a manual key array that had to include every variable the function depended on. The new directive auto-derives the key from arguments and closure variables, so the manual array goes away.

// Bad: easy to forget a variable, silently caches wrong values per user.
export const getUserPosts = unstable_cache(
  async (userId: string) => fetchUserPosts(userId),
  ["user-posts"],          // userId NOT in the key — every user shares cache
  { tags: ["posts"] },
);

// Good: userId is an argument, auto-included in the key.
export async function getUserPosts(userId: string) {
  "use cache";
  cacheLife("minutes");
  cacheTag(CACHE_TAGS.posts);
  return fetchUserPosts(userId);
}

3. revalidate: number → cacheLife()

See references/core-concepts.md for the full profile table.

4. tags: [...] option → cacheTag()

// Bad: string literals scattered in option objects, no central registry.
unstable_cache(fn, key, { tags: ["posts", `post:${id}`] });

// Good: centralized tags, registry-derived.
"use cache";
cacheLife("hours");
cacheTag(CACHE_TAGS.posts, CACHE_TAGS.post(id));

Common gotchas during migration

• Closures that worked before may now fail — "use cache" cannot capture

non-serializable values (class instances, functions, request-time symbols). If your unstable_cache body referenced db.client from an outer scope, pass the data the function needs as an explicit argument instead.

• `cookies()` / `headers()` inside the function body throws. Move the

read above the call site and pass the value as an argument. See references/personalized-content.md for the full pattern.

• **Math.random() and Date.now() inside the function body run once, at

build time.** If unstable_cache happened to mask this (because each cache miss re-ran it), the directive will surface the bug. Defer with await connection() if request-time non-determinism is required.

• `revalidatePath()` callers do not need to change, but consider whether

revalidateTag() (with the second-argument form) is a better fit now that tags are centralized.

Order of operations

1. Add cacheComponents: true to next.config.ts. 2. Create lib/cache/tags.ts with collection tags for every domain that currently appears in unstable_cache calls. 3. Create lib/cache/revalidate.ts and move every revalidateTag() call into it (the centralization step from SKILL.md). 4. Migrate one fetcher at a time. Run next build after each — it surfaces broken closures and dynamic-API leaks immediately. 5. Delete the now-unused unstable_cache imports. 6. Run scripts/audit.mjs (if shipped with this skill) to confirm no raw updateTag( / revalidateTag( calls remain outside revalidate.ts.

Personalized Content Near Cache Boundaries

Background reading for the nextjs-cache-architecture skill. Load this when the user is dealing with per-user data, cookies, headers, or auth — the most error-prone area of "use cache", because dynamic request APIs and cached functions interact in ways that look subtle but fail loudly.

The rule

Never call cookies(), headers(), or auth() inside a "use cache" function. Read them outside the cache boundary and pass the derived primitives as props. The arguments become part of the auto-generated cache key, so each user gets their own cache entry without any manual keying.

Pattern: read outside, cache inside

// app/dashboard/page.tsx
import { cookies } from "next/headers";
import { cacheLife } from "next/cache";

// Good: 1. Read request-time data outside the cache boundary.
async function PersonalizedSection() {
  const cookieStore = await cookies();
  const userId = cookieStore.get("userId")?.value;

  // Good: 2. Pass as a prop — auto-included in the cache key.
  return <CachedPersonalizedView userId={userId} />;
}

// Good: 3. Cache the stable rendering, keyed per user automatically.
async function CachedPersonalizedView({
  userId,
}: {
  userId: string | undefined;
}) {
  "use cache";
  cacheLife("minutes");
  // userId is an argument → auto-keyed per user

  const data = await getPersonalizedData(userId);
  return <div>{/* render */}</div>;
}

Anti-pattern

// Bad: dynamic API inside cached function — throws or produces wrong behavior.
import { cookies } from "next/headers";

async function CachedView() {
  "use cache";
  const cookieStore = await cookies();
  return <div />;
}

Exception: "use cache: private"

Use only when compliance requirements prevent refactoring to the props pattern (for example, the request-time secret cannot leave a specific function for audit reasons). The private variant scopes the cache to the current user session and allows dynamic APIs inside.

import { cookies } from "next/headers";

async function getData() {
  "use cache: private";
  const session = (await cookies()).get("session")?.value; // allowed inside private
  return fetchData(session);
}

Prefer the props pattern when both are viable — it shares cache entries across identical inputs, while private always keeps a per-session copy.