guide: ISR | Incremental Static Regeneration

src/content/docs/en/guides/incremental-static-regeneration.mdx

@@ -0,0 +1,273 @@
+---
+title: Incremental Static Regeneration
+---
+If your website fetches content from a CMS or a database that updates infrequently, you can use a technique called **Incremental Static Regeneration**, or ISR, to update your site without rebuilding the entire project. This is a great way to keep your site up-to-date while still enjoying the benefits of static hosting.
+
+:::note[SSG vs SSR vs ISR]
+ISR is often presented as an alternative to Static Site Generation (SSG) and Server Side Rendering (SSR), but it is more helpful to think of it as SSR with caching.
+:::
+
+:::note
+Incremental static regeneration is different from **incremental builds**, which speeds up full rebuilds by reusing work done by the previous builds.
+:::
+
+## Why ISR?
+- Your site has a lot of pages (more than one thousand). Build times can be shortened when using SSR or ISR.
+- Your content changes infrequently (less frequently than once in 5 minutes on average).
+- Your site gets a lot of visitors. It can be wasteful to render the same page for every visitor, and you can avoid it using ISR.
+- The CMS or database you are using is slow, or charges by request. With ISR, the requests to your backend will become much less frequent.
+
+## Why not ISR?
+- Your content is located inside your project (for example, as markdown files in `src/content`).
+- You don't want the hassle of running a server or using a serverless platform.
+- Your website offers logged-in experiences. If each user needs to be sent a slightly different HTML from others, caching the page may not be possible.
+- The structure of your site (layouts, and styling) changes frequently. Changes to the structure require a full rebuild.
+
+## Implementing ISR for Your Project
+
+ISR involves saving the response such that it can be reused for future requests. The exact implementation depends on where you are deploying.
+
+If you aren't using an adapter already, you are going to need to add one. See the [integrations guide](/en/guides/integrations-guide/) for specific instructions. In your config, make sure that the `output` is either `"server"` or `"hybrid"`. Note that when using "hybrid", the pages you want generated, cached, and invalidated will need to be opted-out of prerendering. Otherwise, they will only be rendered once during build. See the [server side rendering guide](/en/guides/server-side-rendering/#opting-out-of-pre-rendering-in-hybrid-mode) to see how.
+
+
+#### About Cache-Control Headers
+You will see `Cache-Control` headers being used for many of the platforms below. It is worth reviewing the basics of how they work.
+ - `Cache-Control: s-maxage=60` tells the caching server to cache the response for 60 seconds. You probably want to use this for most cases.
+ - `Cache-Control: max-age=60` tells both browsers and servers to cache the response for 60 seconds. You may use this when your content is unlikely to be edited. If a page with `max-age` updates after it has been visited by a user, their browser will show them the cached version until the age of the content is past `max-age`.
+ - `Cache-Control: private, max-age=60` tells the browser to cache the response for 60 seconds, but tells the servers to not cache it. This is useful when you want to provide quick navigation, and the content includes details specific to the visitor.
+
+#### About the Web Cache API
+Deno and Cloudflare implement the Web Cache API, a way to store and retrieve `Response` objects using javascript.
+To use this API, call the `open` method on the globally available `caches` object with a name of your choosing.
+```ts
+const cache = await caches.open("astro")
+```
+You just opened a [`Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache)! You can now call `await cache.put(request, response)` to save a response, and `await cache.match(request)` to retrieve it. See [web.dev's Cache API quick guide](https://web.dev/cache-api-quick-guide/) if you want to learn more.
+
+### Self-hosted Node.js
+ISR can be implemented in Node.js by writing a caching middleware. The following middleware caches every response in memory for 60 seconds:
+
+```ts title="src/middleware.ts"
+import { defineMiddleware } from "astro:middleware"
+
+const cache = new Map
+
+export const onRequest = defineMiddleware(async ({ request }, next) => {
+
+    let expiresIn = 60
+
+    const cached = cache.get(request.url)
+
+    if (cached) {
+        if (cached.expires > Date.now()) {
+            return cached.response.clone()
+        }
+        else {
+            cache.delete(request.url)
+        }
+    }
+
+    const response = await next()
+
+    cache.set(request.url, {
+        expires: Date.now() + expiresIn * 1000,
+        response: response.clone()
+    })
+
+    return response
+})
+```
+:::tip
+It is a good idea to skip caching when the response code is 500 (Internal Server Error).
+:::
+
+#### Advanced: Per-page revalidation time
+You may want some pages to be always rendered fresh, while others to be kept saved for hours. Astro makes this possible with middleware locals.
+
+You can create a function that changes the `expiresIn` variable, and add it to locals. Now each astro page can decide how long it should be cached for!
+```ts title="src/middleware.ts" ins={9}
+import { defineMiddleware } from "astro:middleware"
+
+const cache = new Map
+
+export const onRequest = defineMiddleware(async ({ request, locals }, next) => {
+
+    let expiresIn = 60
+
+    locals.revalidate = seconds => { expiresIn = seconds }
+
+    const cached = cache.get(request.url)
+
+    if (cached) {
+        if (cached.expires > Date.now()) {
+            return cached.response.clone()
+        }
+        else {
+            cache.delete(request.url)
+        }
+    }
+
+    const response = await next()
+
+    cache.set(request.url, {
+        expires: Date.now() + expiresIn * 1000,
+        response: response.clone()
+    })
+
+    return response
+})
+```
+```ts title="src/env.d.ts"
+/// <reference types="astro/client" />
+
+namespace App {
+    interface Locals {
+        revalidate(seconds: number): void
+    }
+}
+```
+```astro title="src/pages/index.astro"
+---
+Astro.locals.revalidate(3600)
+---
+<h1>This page will saved and reused for 1 hour before being generated again.</h1>
+```
+```ts title="src/pages/endpoint.ts"
+export async function GET({ locals }) {
+    locals.revalidate(0)
+    return new Response("This response will be generated every time this endpoint is called.")
+}
+```
+
+### Self-hosted Deno
+The middleware approach used for Node works on Deno as well. Deno also implements the Web Cache API which has the added bonus of persisting the cache across server restarts. It is important to note that `Cache-Control` headers are not automatically processed - you would have to manually delete responses when they have expired. The following middleware uses the Web Cache API to cache responses. A custom header (`X-Expires`) is used to keep track of staleness:
+
+```ts title="src/middleware.ts"
+import { defineMiddleware } from "astro:middleware"
+
+const cache = await caches.open('astro')
+
+export const onRequest = async ({ request }, next) => {
+    const cachedResponse = await cache.match(request)
+
+    if (cachedResponse) {
+        const expires = Number(cachedResponse.headers.get('X-Expires'))
+        if (expires > Date.now()) {
+            return cachedResponse
+        } else {
+            await cache.delete(request)
+        }
+    }
+
+    const response = await next()
+
+    response.headers.set('X-Expires', String(Date.now() + 60 * 1000))
+
+    await cache.put(request.url, response.clone())
+
+    return response
+}
+```
+
+### Deno Deploy
+Deno Deploy does not provide a way to persist data. However, you may be able to use a third-party caching database to manually cache responses. While this avoids calls to your CMS, you may still experience significant latencies due to the network round-trip time between the Deno Deploy instance and your database.
+
+### Vercel
+Vercel provides a built-in caching layer that automatically saves cacheable responses. Make sure your server-rendered page or endpoint sets a `Cache-Control` header.
+```astro title="src/pages/index.astro"
+---
+Astro.response.headers.set('Cache-Control', 's-maxage=60')
+---
+<h1>Vercel Edge CDN will save and reuse this page for about 60 seconds.</h1>
+```
+```ts title="src/pages/endpoint.ts"
+export async function GET({ request }) {
+    return new Response("Vercel Edge CDN will save and reuse this response for about 60 seconds.", {
+        headers: { "Cache-Control": "s-maxage=60" }
+    })
+}
+```
+Vercel only supports `s-maxage` and `stale-while-revalidate` in the Cache-Control header. See [Vercel documentation](https://vercel.com/docs/concepts/edge-network/caching) for current information.
+
+### Netlify
+Netlify supports caching via two methods: `Cache-Control` headers, which works with edge and serverless functions; and, On-demand Builders, a type of function dedicated for optimized caching.
+
+#### On-demand Builders
+On-demand Builders are serverless functions used to generate web content as needed that’s automatically cached on Netlify’s Edge CDN.
+To enable them, set the `builders` option to `true` in your config file.
+```ts title="astro.config.js" ins={6}
+import { defineConfig } from 'astro/config'
+import netlify from '@astrojs/netlify/functions'
+
+export default defineConfig({
+  output: 'server',
+  adapter: netlify({ builders: true })
+})
+```
+By default, pages for your site will be built when a user visits them for the first time and then cached at the edge for subsequent visits. To set a revalidation time, call the `runtime.setBuildersTtl(ttl)` local with the duration (in seconds). For example, to set a revalidation time of 60 seconds:
+```astro title="src/pages/index.astro"
+---
+Astro.locals.runtime.setBuildersTtl(60)
+---
+<h1>Netlify On-Demand Builders will save and reuse this page for about 60 seconds.</h1>
+```
+When you set a revalidation time, Netlify will rerender the page in the background at regular intervals so that visitors never have to wait for a page to be rendered.
+:::caution
+On-demand Builders ignore query params when checking for cached pages.
+
+For example, if `example.com/?x=y` is cached, it will be served for `example.com/?a=b` (different query params) and `example.com/` (no query params) as well.
+:::
+See [Netlify documentation](https://docs.netlify.com/configure-builds/on-demand-builders) to learn more about On-demand Builders.
+
+#### Edge and serverless functions
+Netlify supports caching via `Cache-Control` headers. Make sure your server-rendered page or endpoint sets a `Cache-Control` header.
+
+```astro title="src/pages/index.astro"
+---
+Astro.response.headers.set('Cache-Control', 's-maxage=60')
+---
+<h1>Netlify Edge CDN will save and reuse this page for about 60 seconds.</h1>
+```
+See [Netlify documentation](https://docs.netlify.com/edge-functions/optional-configuration/#supported-headers) to learn about the supported headers, and values.
+
+### Cloudflare Pages/Workers
+The example below shows how you would use a combination of middleware and `Cache-Control` headers. A check for existence of the default `Cache` is done to avoid running the middleware in the dev server, which does not have access to the Cache API.
+```ts title="src/middleware.ts"
+import { defineMiddleware } from "astro:middleware"
+
+const cachingMiddleware = defineMiddleware(async ({ request }, next) => {
+
+    const cache = caches.default
+
+    const cachedResponse = await cache.match(request)
+
+    if (cachedResponse) return cachedResponse
+
+    else {
+        const response = await next()
+
+        await cache.put(request, response.clone())
+
+        return response
+    }
+})
+
+export const onRequest =
+    globalThis.caches?.default
+        ? cachingMiddleware
+        : (_, next) => next()
+```
+```astro title="src/pages/index.astro"
+---
+Astro.response.headers.set('Cache-Control', 'max-age=3600')
+---
+<h1>Cloudflare Workers will save and reuse this response for upto 1 hour.</h1>
+```
+`caches.default` is a pre-opened `Caches` available only on Cloudflare's javascript runtime. It is worth noting that, unlike Deno and browsers, this runtime automatically deletes stale responses put inside a `Cache`. See [Cloudflare docs](https://developers.cloudflare.com/workers/runtime-apis/cache#headers) to learn more.
+:::caution
+Cloudflare may remove the cached response from their server before the duration you set has elapsed.
+
+This may happen if the page was not receving visitors, or if the server is approaching capacity.
+
+If it is important to you that your visitors don't wait for the page to render afresh, you may be able to take advantage of Cloudflare's Cache Reserve feature, which stores cache on their object storage offering, R2.
+:::