Caching and Incremental Regeneration for Headless WordPress

Write down how long a visitor may reasonably see an older version. A general article might tolerate a short delay, while a correction to important legal information needs a more deliberate release check. Price, stock and account data introduce additional rules that a generic blog caching recipe does not solve.

Build-time generation produces files during deployment. Request-time rendering performs work for the request. ISR reuses generated output and refreshes it according to supported invalidation rules. None of these labels tells you whether a separate WordPress plugin, reverse proxy or browser cache is also serving an older response.

Create a short map of the layers you actually operate: the WordPress API, frontend data cache, generated route, hosting cache and browser. Record who can invalidate each one. This is more useful during an incident than a promise that the site has “a cache” without knowing which copy a visitor received.

Runtime ISR needs a deployment that supports the framework’s runtime behavior. A directory of exported HTML on ordinary static hosting does not gain a Next.js regeneration process because a revalidation interval appears in source code. Confirm the capabilities of your host or adapter and test them in a production-mode deployment.

For a static export, a scheduled or webhook-triggered rebuild can be a valid alternative. That workflow has its own publication latency: the build must complete, pass verification and be deployed. Avoid promising instant updates if the actual delivery mechanism is a full deployment queue.

This portfolio itself uses a Vite build with prerendered HTML, so it publishes through a new build rather than Next.js ISR. The distinction matters when choosing a headless frontend for a client. Use the headless WordPress hosting guide to compare operational requirements before selecting a cache API.

In the documented Next.js ISR model without Cache Components, a generated page can remain cached until its revalidation interval has elapsed. A later request can receive the stale version while regeneration happens in the background. The next successful regeneration supplies fresh output for subsequent requests.

That is not the same as a background timer rebuilding every page exactly on the minute. A rarely visited URL may stay unchanged until a request causes the refresh path to run. Explain that behavior to editors so they know why a saved correction and their first public request might not look identical.

Choose an interval based on the content and operating cost. A very short interval can put avoidable load on WordPress, especially across many routes. A very long interval makes a missed invalidation more visible. Treat the interval as a fallback freshness policy and measure the actual delay in your deployment.

An editorial event can notify a server-side frontend endpoint that relevant content changed. Authenticate that request and limit it to permitted actions. Never accept an arbitrary public request to purge every route or expose a shared secret in client-side JavaScript. Use the sender’s documented signature or another server-to-server authentication mechanism.

WordPress hooks can run for revisions, autosaves and updates that do not represent a new public article. Decide which state transitions matter. Publishing, editing public content, moving it back to draft, changing its slug and deleting it can all require different invalidations. The post ID alone is not always enough to identify the old public URL.

In the App Router, revalidatePath invalidates the specified path, but regeneration is associated with a subsequent visit rather than proof that a new page already exists at webhook response time. Treat acknowledgement, invalidation and fresh public output as separate observations. A deployment check should request the public route and verify the changed content.

A single WordPress article may appear on its own page, the blog index, a category listing and a related-content block. Invalidating only the detail page leaves other surfaces inconsistent. Maintain a dependency map that identifies the lists and derived metadata affected by a change.

Next.js supports tagging cached data and invalidating by tag. Its current documentation demonstrates revalidateTag with the max profile for stale-while-revalidate behavior. Do not assume every tag invalidation forces every caller to block until fresh data arrives. Check the API supported by your installed version and select semantics that match the freshness requirement.

Keep tags understandable: a resource-level tag for an article and broader tags for relevant collections are easier to reason about than an unbounded collection of ad hoc strings. Avoid purging the entire site for every typo unless that is a conscious, measured tradeoff. Category changes must consider both the old and new category.

An editor needs to see unpublished changes, while an anonymous visitor should receive only public content. A preview route must verify access before fetching draft data. Ensure that authentication credentials and draft responses do not enter a shared cache intended for anonymous traffic.

Use the framework’s supported draft or preview mode and document the WordPress credentials it needs. Test the same URL in an authenticated editorial session and a fresh anonymous browser. Seeing the correct preview while logged in does not establish that the anonymous route is safe.

Apply the same discipline to personalised account data and commerce interactions. A public article cache strategy is not an appropriate default for a cart. Follow the headless preview setup guide for the editorial workflow, then review the caching behavior of any custom API fetches that workflow introduces.

Next.js documents that if regeneration throws an error, the last successfully generated content can continue to be served and a later request can retry. That can protect availability during a WordPress outage, but only when a usable cached result exists. A newly requested route without cached output may still fail.

Distinguish an upstream timeout from a confirmed removal. Returning an empty success object for every API failure can replace valid content with an accidental blank page. Conversely, preserving an old article forever after it is intentionally removed is also wrong. Define how confirmed deletion and unpublished content should produce an appropriate public response.

Webhooks can be lost through configuration mistakes or delivery failures. Keep a fallback such as time-based revalidation or periodic reconciliation of changed resource IDs. For renamed slugs, handle the old URL deliberately with a redirect or removal policy and invalidate affected lists. Cache invalidation alone is not a complete URL migration.

Development servers often handle caching differently, so test a production build and the actual hosting adapter. Publish a distinctive test revision in a controlled environment, inspect the first request after invalidation and then request again. Record when the public content changes and which upstream requests occurred.

Test a normal edit, a new article, a category move, a slug change, an unpublished article and a WordPress outage. Include a deliberately failed invalidation and recovery. Observe status codes and page content together: a 200 response containing the old title does not prove publication succeeded.

Keep logs focused on resource IDs, event identities, invalidated paths, timings and outcomes. Avoid logging draft content or secrets. Finish the handover with an editor-facing explanation of the expected delay and a developer-facing recovery procedure. The Next.js setup guide and WordPress caching guide provide the broader implementation context.