chore: document ISR (#986)

* chore: document ISR

* Apply suggestions from code review

Co-authored-by: Tiffany Le-Nguyen <[email protected]>

Co-authored-by: Tiffany Le-Nguyen <[email protected]>

Author: ascorbic

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.