Next.js ISR on Netlify

Incremental static regeneration (ISR) is the architecture behind Next.js that allows pages to be updated after a site has been built and deployed.

Compared to server-side rendered (SSR) pages and statically-generated pages, ISR pages have distinct advantages. They are not rebuilt for each user, so they load quickly. And they can be periodically updated with new content without a new deploy.

# Using ISR on Netlify

ISR on Netlify is implemented with On Demand Builders, using the Time To Live (TTL) feature. You can enable ISR for a page by returning a value for revalidate from the getStaticProps function.

The value set for revalidate is the number of seconds that the page’s content is considered fresh. If a request arrives for a page after the revalidate period has elapsed, the page is regenerated.

ISR uses a “stale while revalidate” strategy, meaning that the visitor still receives the stale content, but it is regenerated in the background and becomes ready for the next request. The generated page is persisted globally, so it’s available to all visitors wherever they are in the world. It is also cached in the global Netlify CDN for fast responses.

The minimum value for revalidate is 60 seconds. Any value less than that will default to 60 seconds.

After a request is made for stale content, the page will be regenerated in the background. After it has been regenerated, it will be persisted globally. This can take a little time before the new content is updated across all CDN nodes.

If the static regeneration relies on local files in your repository, the files need to be bundled with the handler functions. This can be done by modifying your file based configuration.

Add an entry to the included_files option under the functions option. You should be careful to not include unnecessary files. Particularly large files like images or videos can make your handler function sizes grow quickly. AWS has a 50 MB size limit for each handler function.

See the Functions Configuration Docs for more information.

Update your netlify.toml file to include the following (assuming local content is located in the /content directory):

  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

On-demand ISR (where a path is manually revalidated) is not currently supported on Netlify.

# Alternatives to ISR

ISR is best for situations where there are regular updates to content throughout the day, particularly when you don’t have control over when the updates happen. It is less ideal for certain use cases, such as when a CMS is called for. A CMS is ideal for incremental updates since you can trigger a deploy when a page is added or edited.

# Static site generation

For high-traffic pages, you can use static generation without revalidate. This deploys static files directly to the CDN for maximum performance.

# Distributed persistent rendering

For less commonly-accessed content, you can return fallback: "blocking" from getStaticPaths and defer builds until the first request.

This approach 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 and are not accessed often enough to justify statically-generating them at build time.