asymmetric-al/.cursor/skills/cache-components

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