cache-components · diff
git:20260222.9a170d8 to git:20260603.c42511a
5 added, 0 removed. Audit C to A.
+ ---
+ name: cache-components
+ description: "Build correct cached/dynamic boundaries in the Next.js App Router when Cache Components or PPR are enabled. Use when working with cacheComponents, Partial Prerendering (PPR), 'use cache', cacheLife, cacheTag, updateTag, or revalidateTag, to avoid request-context leaks and enforce proper cache invalidation. Not for the Pages Router or when Cache Components/PPR are off."
+ ---
+
# 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
```ts
"use cache";
import { cacheLife, cacheTag } from "next/cache";
export async function getProducts(category: string) {
cacheLife("minutes");
cacheTag("products");
cacheTag(`products:${category}`);
}
```
### Dynamic Suspense boundary
```tsx
import { Suspense } from "react";
export default function Page() {
return (
<>
<MainCached />
<Suspense fallback={null}>
<UserPanel />
</Suspense>
</>
);
}
```
### Mutation invalidation
```ts
"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`