Revalidating Data And Paths

Time-Based Revalidation (ISR)

Set `export const revalidate = 60` on a route or `next: { revalidate: 60 }` on fetch to regenerate content at most once per interval after first request. Subsequent requests serve cached version until window expires.

ISR balances performance and freshness for content that changes periodically — product catalogs, blog posts, marketing pages — without rebuilding entire site on every edit.

• revalidate seconds on route or fetch
• Serve stale while regenerating
• Ideal for periodic content updates

On-Demand Revalidation

`revalidatePath('/blog/[slug]', 'page')` invalidates cached pages matching the path. `revalidateTag('posts')` invalidates all fetches tagged during retrieval. Call from CMS webhooks, Server Actions after mutations, or admin tools.

On-demand is precise — only affected content refreshes. Prefer over lowering global revalidate intervals when updates are event-driven.

• revalidatePath for route cache bust
• revalidateTag for data cache bust
• Trigger from webhooks and mutations

'use server';
import { revalidateTag } from 'next/cache';
export async function publishPost() {
  await savePost();
  revalidateTag('posts');
}

Scope The Refresh

Invalidate narrowly — revalidate specific post tag, not entire site. Broad invalidation causes thundering herd on origin as many pages regenerate simultaneously.

Stagger webhook-triggered revalidation for bulk CMS publishes. Queue invalidation jobs for large content updates rather than synchronous mass bust.

• Narrow invalidation scope
• Avoid site-wide bust on single edit
• Queue bulk invalidation jobs

Stale-While-Revalidate Semantics

After revalidate window expires, first request still receives stale content while regeneration happens in background. Subsequent requests get fresh content. This prevents slow regeneration from blocking users.

For must-never-stale content (stock prices, auth state), use force-dynamic instead of ISR. ISR accepts brief staleness for performance gains.

• Stale served during background regen
• Not for must-fresh data
• force-dynamic when staleness unacceptable

Testing Revalidation

Verify revalidation in staging with production-like caching enabled — development mode caching differs. Test webhook → revalidateTag → fresh content flow end-to-end.

Document which tags map to which content types so CMS integrations invalidate correctly. Tag registry in code comments or ADRs prevents orphan caches.

• Test caching in staging environment
• End-to-end webhook revalidation tests
• Document tag-to-content mapping