From 42627ea51ead3e7b18cbae239fcd767b8f1cfd07 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Tue, 14 Dec 2021 09:52:14 +0000 Subject: [PATCH 1/2] chore: document ISR --- docs/isr.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/isr.md diff --git a/docs/isr.md b/docs/isr.md new file mode 100644 index 0000000000..d6d50e8ef6 --- /dev/null +++ b/docs/isr.md @@ -0,0 +1,47 @@ +## Incremental Static Regeneration (ISR) + +[Incremental static regeneration](https://vercel.com/docs/concepts/next.js/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 Essential Next.js plugin, 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. + +### Using ISR on Netlify + +ISR on Netlify is implemented with [On Demand Builders](https://docs.netlify.com/configure-builds/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 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. + +### Alternatives to ISR + +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. + +### Static site generation + +For high-traffic pages you can use +[static generation](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) without +`revalidate`, which deploys static files directly to the CDN for maximum performance. + +### Distributed persistent rendering + +For less commonly-accessed content you can use return `fallback: "blocking"` from +[`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation) 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. From 61d3e40b2839c3a06d78dd9e93dcc09ebb22c5aa Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Tue, 14 Dec 2021 10:16:58 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Tiffany Le-Nguyen --- docs/isr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/isr.md b/docs/isr.md index d6d50e8ef6..0e6ca606cb 100644 --- a/docs/isr.md +++ b/docs/isr.md @@ -3,7 +3,7 @@ [Incremental static regeneration](https://vercel.com/docs/concepts/next.js/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 Essential Next.js plugin, 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 +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. ### Using ISR on Netlify