Incremental Jamstack: Updating Only Changed Pages with On‑Demand Revalidation

The problem: full rebuilds slow down large Jamstack sites

When every content change triggers a complete site rebuild, a catalog with thousands of product pages or a documentation hub can take many minutes to republish. Authors wait for the build to finish, and the platform consumes build minutes even when only a single item has changed. This latency becomes a bottleneck as the page count grows.

Thesis: incremental regeneration with on‑demand revalidation limits work to the changed page

Modern Jamstack platforms can cache each pre‑rendered page at the edge and rebuild only the URLs whose source data changed. A webhook from the CMS calls a protected endpoint that tells the framework to regenerate that specific path. The next visitor receives the fresh page, while all other pages remain served from the existing cache.

How on‑demand revalidation works

Two common models exist:

• Build‑time diffing: during a deploy the system compares the new data set with the previous one and rebuilds only the pages whose source changed.
• Runtime stale‑while‑revalidation: the edge CDN serves the cached copy immediately and triggers a background rebuild. The first request after a change may see stale content; subsequent requests get the freshly regenerated page.

Both approaches rely on the framework’s revalidation API (e.g., revalidatePath in Next.js) and a webhook that can call a protected route.

Worked example: updating a single product page in a Next.js site hosted on Netlify

Assume a Next.js project with getStaticProps fetching product data from a CMS. The product page uses export const revalidate = 60 for background revalidation, but we want instant updates on CMS publish.

// pages/api/revalidate.js
import { verifyWebhookSignature } from './lib/webhookUtils'; // your verification logic

export default async function handler(req, res) {
  // 1. Verify the webhook (shared secret, HMAC, etc.)
  if (!verifyWebhookSignature(req)) {
    return res.status(401).json({ message: 'Invalid signature' });
  }

  // 2. Expect JSON payload { slug: 'awesome‑product' }
  const { slug } = req.body;
  if (!slug) {
    return res.status(400).json({ message: 'Missing slug' });
  }

  // 3. Call Next.js revalidation for the specific path
  try {
    await res.revalidate(`/products/${slug}`);
    return res.status(200).json({ revalidated: true });
  } catch (err) {
    // 500 if revalidation fails
    return res.status(500).json({ message: 'Revalidation error' });
  }
}

Place this file under pages/api/ so it is reachable at https://your‑site.netlify.app/api/revalidate. The CMS must be configured to POST to that URL whenever a product is published or updated, including a signature header that your verifyWebhookSignature function checks.

After the webhook succeeds, the edge node invalidates the cached /products/awesome‑product URL. The next request triggers a regeneration of that page using the latest CMS data, while all other product pages continue to be served from the existing cache.

Checking that only the target page rebuilt

You can verify the behavior without relying on rebuild logs:

1. Deploy the site and note the Age or Cache‑Control header of a product page (e.g., Age: 1200).
2. Trigger the webhook for a single product.
3. Immediately request that same product page and observe a low Age (indicating a fresh render).
4. Request a different product page that was not part of the webhook; its Age should remain high, showing it was not rebuilt.

If the Age of the untouched page changes, you likely triggered a full rebuild instead of isolated revalidation.

Trade‑offs and limitations

• Staleness window: with stale‑while‑revalidation the first visitor after a change may see the old version until the background rebuild finishes.
• Cache‑key correctness: query strings, draft flags, or preview mode can create separate cache entries, causing unintended duplicates or missed invalidations.
• Platform lock‑in: the revalidation API (revalidatePath, Netlify On‑Demand Builders, Gatsby Cloud builds) is tied to the framework and host; migrating to another provider may require rewriting the webhook handler.
• Failure modes: if the webhook is missed, silently fails, or returns an error, the page stays stale until the next scheduled rebuild or manual purge.

For sites where builds finish in seconds (under a few hundred pages) the simplicity of a full rebuild often outweighs the added complexity. Incremental revalidation pays off when you have thousands of pages, long build times, or frequent content updates.

Actionable closing

1. Measure your current full‑rebuild time on a representative branch; if it exceeds a minute, consider incremental revalidation.
2. Add a protected API route that calls your framework’s revalidation function, securing it with a shared secret or JWT.
3. Configure your CMS to send a POST with the changed page’s identifier (slug, ID, etc.) to that route on every publish event.
4. Validate the rollout by checking cache headers before and after a webhook trigger, as described above.
5. Document the staleness tolerance for your team and decide whether to accept the brief window or switch to client‑side fetching for truly volatile data.

By limiting work to the changed URL, you keep builds fast, reduce wasted compute minutes, and give editors near‑instant visibility of their updates—while being aware of the consistency and operational trade‑offs involved.