nextjs-caching

Next.js Caching (Cache Components)

Requires: cacheComponents: true in next.config.ts (Next.js 16).

---

Project Detection

grep -r "cacheComponents" next.config.* 2>/dev/null

---

Enable

// next.config.ts
const nextConfig: NextConfig = { cacheComponents: true };
export default nextConfig;

---

Decision Steps

1. Does component fetch data? No → skip. Yes → continue.
2. Depends on cookies()/headers()/searchParams? No → step 3. Yes → step 4.
3. Same data for all users? Yes → 'use cache' + cacheTag() + cacheLife(). No → <Suspense>.
4. Can extract runtime data as args? Yes → pass outside cache. No → 'use cache: private' (last resort).

---

Core APIs

'use cache' Directive

async function BlogPosts() {
  'use cache';        // MUST be first statement; function MUST be async
  cacheTag('posts');
  cacheLife('hours');
  return await db.posts.findMany();
}

cacheLife() Profiles

cacheLife('seconds');  // stale:30s  | revalidate:1s   | expire:1m
cacheLife('minutes');  // stale:5m   | revalidate:1m   | expire:1h
cacheLife('hours');    // stale:5m   | revalidate:1h   | expire:1d
cacheLife('days');     // stale:5m   | revalidate:1d   | expire:1w
cacheLife('weeks');    // stale:5m   | revalidate:1w   | expire:30d
cacheLife('max');      // stale:5m   | revalidate:30d  | expire:1y
// Custom:
cacheLife({ stale: 60, revalidate: 3600, expire: 86400 });

By content type: news → seconds, blog/docs → hours, marketing → days, legal → max

cacheTag() + Invalidation

// Tag
async function ProductList({ category }: { category: string }) {
  'use cache';
  cacheTag('products', `category-${category}`);
  cacheLife('hours');
  return await db.products.findMany({ where: { category } });
}

// Invalidate — Server Action (immediate, read-your-own-writes)
'use server';
export async function createProduct(formData: FormData): Promise<void> {
  await db.products.create({ data: parseFormData(formData) });
  updateTag('products');
}

// Invalidate — Route Handler / webhook (stale-while-revalidate)
export async function POST(request: Request) {
  const { tag } = await request.json();
  revalidateTag(tag, 'max');  // two-arg form — single arg is DEPRECATED
  return Response.json({ revalidated: true });
}