Next.js ISR on Netlify
Legacy Next.js Runtime
The information on this page applies to Next.js version 10-13.4 and Netlify Next.js Runtime v4, which is currently in maintenance support.
Visit our Next.js adapter docs for info on newer versions of Next.js.
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.
# Use 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. This can take a little time before the new content is updated across all CDN nodes if they already had a cached copy. 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.
# Configure builds to use ISR
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.
Under the functions option, add an entry to the included_files option. Be careful to not include unnecessary files. Particularly large files like images or videos can make your handler function sizes grow quickly. There is a 250 MB size limit for each handler’s unzipped function bundle.
Review 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):
[functions]
included_files = ["content/**"]
If a new deploy is made, all persisted pages and CDN cached pages will be invalidated by default 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 only supported for Next.js 13.5 and later and Next.js Runtime v5.
# 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 aren’t accessed often enough to justify statically-generating them at build time.
Did you find this doc useful?
Your feedback helps us improve our docs.