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.

• 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.

• 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.

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 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 to see how.

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.

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.

const cache = await caches.open("astro")

You just opened a 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 if you want to learn more.

ISR can be implemented in Node.js by writing a caching middleware. The following middleware caches every response in memory for 60 seconds:

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
})

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!

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
})

/// <reference types="astro/client" />

namespace App {
    interface Locals {
        revalidate(seconds: number): void
    }
}

---
Astro.locals.revalidate(3600)
---
<h1>This page will saved and reused for 1 hour before being generated again.</h1>

export async function GET({ locals }) {
    locals.revalidate(0)
    return new Response("This response will be generated every time this endpoint is called.")
}

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:

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 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 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.response.headers.set('Cache-Control', 's-maxage=60')
---
<h1>Vercel Edge CDN will save and reuse this page for about 60 seconds.</h1>

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 for current information.

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 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.

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.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.

See Netlify documentation to learn more about On-demand Builders.

Netlify supports caching via Cache-Control headers. Make sure your server-rendered page or endpoint sets a Cache-Control header.

---
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 to learn about the supported headers, and values.

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.

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.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 to learn more.