Netlify On-demand Builders for ISR-like Caching on Static Sites

Problem: fresh data without full rebuilds

Static sites are fast, but when a page needs data that changes occasionally—like product listings or blog previews—you either rebuild the whole site on every change or hit the origin on every request. Both options add latency or cost. On-demand Builders give you a middle ground: the first request runs a Netlify function, Netlify caches the response, and later requests get the cached copy instantly until you purge it.

How On-demand Builders work

When a request matches a path marked as a builder, Netlify checks its cache. On a miss, it invokes the associated Node.js function, stores the returned response, and serves it. On a hit, Netlify returns the cached response without invoking the function again. The cache is shared across all visitors and is not tied to a user or session.

When this pattern fits

Choose a builder for read‑heavy endpoints where the underlying data changes infrequently and you can reliably signal when it has changed. Good candidates are product feeds, documentation pages, or aggregated API responses. Avoid builders for personalized or authenticated data because the cached response would be served to everyone.

Worked example: cached product feed

Create a function at netlify/functions/products.js that fetches from a CMS and returns JSON.

// netlify/functions/products.js\nexports.handler = async (event, context) => {\n  const cmsUrl = process.env.CMS_API_URL;\n  const resp = await fetch(cmsUrl);\n  const data = await resp.json();\n\n  return {\n    statusCode: 200,\n    headers: { 'content-type': 'application/json' },\n    body: JSON.stringify(data),\n  }\n};\n

Mark the function as a builder in your Netlify configuration (see the current docs for the exact syntax). After the CMS publishes new content, call Netlify's purge API for the path /api/products from a privileged token (deploy:purge scope) in your CI or webhook. The purge removes the cached entry; the next request triggers a fresh function run and populates the cache again.

Trade‑offs and verification

Cache invalidation is explicit, so a failed or delayed purge can serve stale data. Builder execution consumes function runtime and counts toward your monthly limits, which may affect cost for high‑traffic endpoints compared to a truly static file. The cache is shared, so never store user‑specific or sensitive data in a builder response.

To verify the behavior:

1. Deploy a preview with the builder function and request the endpoint. Check the function logs; you should see one invocation.
2. Make a second request to the same path; the logs should show no new invocation, indicating a cache hit.
3. Trigger a purge via the API (or dashboard) and request the endpoint again; a new function invocation should appear, confirming the cache was cleared.

Always consult the latest Netlify documentation for current limits, supported runtimes, and purge semantics before relying on this pattern in production.