ISR Deep Dive: Making Headless WordPress Lightning Fast

Incremental Static Regeneration (ISR) is the killer feature that makes Next.js perfect for headless WordPress. But understanding when and how to use it can be tricky.

What is ISR?

ISR lets you update static pages after build time without rebuilding your entire site. You get the speed of static generation with the freshness of server-side rendering.

Here’s how it works: Next.js generates static HTML at build time. After deployment, when someone requests a page, they get the cached version. In the background, Next.js regenerates the page and updates the cache.

Time-Based vs On-Demand Revalidation

Next.js offers two ISR strategies:

Time-based revalidation regenerates pages after a specified interval:

export const revalidate = 3600; // 1 hour

This is great for content that updates predictably, like archive pages or dashboards.

On-demand revalidation regenerates pages when triggered by an API call. This is what FlatWP uses. When you save a post in WordPress, our plugin immediately triggers revalidation:

await fetch('/api/revalidate', {
  method: 'POST',
  body: JSON.stringify({ paths: ['/blog/my-post'] })
});

The FlatWP Approach

We use different strategies for different content types:

• Blog posts: On-demand ISR (update immediately when edited)
• Static pages: No revalidation (fully static)
• Archives: Short time-based ISR (5 minutes)
• Homepage: Very short ISR or server component

This gives you instant updates where they matter, without sacrificing performance.

Performance Impact

With ISR, first-time visitors get sub-100ms page loads. The page is pre-rendered, served from the edge, and cached globally. Subsequent visitors get even faster loads from CDN cache.

Compare this to server-side rendering, which queries WordPress on every request. ISR gives you the best of both worlds.