Incremental static regeneration is a feature of Next.js that allows pages to be updated after a site has been built and deployed. It is now fully supported in Netlify by the Next Runtime, meaning large sites can update pages without needing to rebuild the entire site. Unlike server-side rendered pages, the page is not rebuilt for each user, so they load quickly, but unlike statically-generated pages they can be periodically updated with new content without a new deploy.
ISR on Netlify is implemented with On Demand Builders,
using the TTL feature. You can enable ISR for a page by returning a value for revalidate from the getStaticProps
function. This value is the number of seconds for which the content will be considered fresh. If a request arrives for a
page after the revalidate period has elapsed, the page will be regenerated. ISR uses a "stale while revalidate"
strategy, meaning that the visitor still receives the stale content, but it is regenerated in the background ready for
the next request. The generated page is persisted globally, so is available to all visitors wherever they are in the
world. It is also cached in the global Netlify CDN so responses are fast.
The minimum value for revalidate is 60 seconds, and any value less than that will be rounded-up to 60 seconds. After a
request is made for stale content, the page will be regenerated in the background and immediately persisted globally,
but it can take up to 60 seconds before the new content is then updated in all CDN nodes if they already had a cached
copy.
If the static regeneration relies on local files in your repository they need to be bundled with the handler functions.
This can be done by modifying your
file based configuration. An entry to the
included_files option needs to be added under the functions option. You should be careful to not include unnecessary
files, particularly large files such as images or videos, because there is a 50MB size limit for each handler function.
See Functions Configuration Docs for
more info. Update your netlify.toml file to include the following (assuming local content is located in the /content
directory):
[functions]
included_files = ["content/**"]If you only need the content for DSG pages, then you can target only that function like this:
[functions.__dsg]
included_files = ["content/**"]or, for SSR pages:
[functions.__ssr]
included_files = ["content/**"]If a new deploy is made, all persisted pages and CDN cached pages will be invalidated so that conflicts are avoided. If this did not happen, a stale HTML page might make a request for an asset that no longer exists in the new deploy. By invalidating all persisted pages, you can be confident that this will never happen and that deploys remain atomic.
On-Demand ISR (where a path is manually revalidated) is not currently supported on Netlify. Please let us know if this feature would be useful to you, and if so how you would plan to use it.
ISR is best for situations where there are regular updates to content throughout the day, particularly you don't have control over when it happens. It is less ideal in situations such as a CMS with incremental updates where you can have the CMS trigger a deploy when a page is added or edited. This offers the best performance and avoids unnecesary rebuilds.
For high-traffic pages you can use
static generation without
revalidate, which deploys static files directly to the CDN for maximum performance.
For less commonly-accessed content you can use return fallback: "blocking" from
getStaticPaths and defer
builds until the first request. This also uses On Demand Builders, but persists the built page until the next deploy.
This is great for long-tail content and archives that don't change often but are not accessed often enough to justify
statically-generating them at build time.