Cache Components (Next.js) — Skill

Name: cache-components Purpose: Build correct cached/dynamic boundaries in Next.js App Router when Cache Components or PPR are in use. Use this skill to avoid request-context leaks and to enforce proper cache invalidation.

Applies when: cacheComponents: true, Partial Prerendering (PPR), 'use cache', cacheLife, cacheTag, updateTag, revalidateTag. Do not use when: Working in the Pages Router or when Cache Components/PPR are not enabled.

Rules

• •Cached vs dynamic: Shared data should be cached; request/user-specific data must be dynamic and streamed behind <Suspense>.
• •No request context inside cache: Never call cookies(), headers(), or auth/session inside a 'use cache' scope.
• •Cached functions must be async: Any 'use cache' function/component must be async.
• •Prefer code-local caching: Favor 'use cache', cacheLife, cacheTag over route-segment config (revalidate, dynamic).
• •Mutations must invalidate tags: Use updateTag for immediate consistency or revalidateTag for background refresh.
• •PPR + generateStaticParams: Do not return empty arrays; keep request-specific logic out of the shell.

Workflow

1. •Classify each data dependency as shared or request-specific.
2. •For shared data, add 'use cache' + cacheTag (and cacheLife if needed).
3. •For request/user-specific data, keep it dynamic and render behind <Suspense>.
4. •Split cached logic from request logic if needed.
5. •Invalidate tags after mutations.

Checklists

Implementation checklist

• • Shared data uses 'use cache'
• • Cached scopes have cacheTag
• • No request data inside cached scopes
• • Dynamic UI is isolated behind <Suspense>
• • Cached functions are async
• • Mutations invalidate correct tags

Review checklist

• • Route segment config avoided unless required
• • PPR shells do not include request-specific logic

Minimal examples

Cached function

"use cache";

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

export async function getProducts(category: string) {
  cacheLife("minutes");
  cacheTag("products");
  cacheTag(`products:${category}`);
}

Dynamic Suspense boundary

import { Suspense } from "react";

export default function Page() {
  return (
    <>
      <MainCached />
      <Suspense fallback={null}>
        <UserPanel />
      </Suspense>
    </>
  );
}

Mutation invalidation

"use server";

import { updateTag } from "next/cache";

export async function updateProduct(id: string) {
  updateTag(`product:${id}`);
  updateTag("products");
}

Common mistakes / pitfalls

• •Reading cookies/headers/session inside 'use cache'
• •Missing cache tags on cached functions
• •Rendering request-specific data outside <Suspense>
• •Forgetting to invalidate tags after mutations
• •Returning an empty array from generateStaticParams