The Guide for On-Demand ISR

Incremental Static Regeneration (ISR) is not just caching, but the ability to cache and revalidate the cache on the CDN once it expires. The on-demand part could be a game-changer.

Incremental Static Regeneration (ISR) is an incredible tool for caching your data on a CDN. The technology was released in 2020 by Vercel and built specifically for Next.js. However, since then it has begun adapting for different frameworks on different hosting environments. It is quite useful and could save you thousands in hosting and database costs.

Server Cache Headers

Caching has existed for a long time on server environments. With Cache-Control headers, you have the ability to save your state for a selected amount of time. All you do is return the proper header in your designated language (PHP, Node.js, etc.).

Cache-Control: max-age=<seconds>

or if you’re using a proxy:

Cache-Control: s-maxage=<seconds>

The data is fetched once, then saved to the server cache. When the cache expires, it will fetch again. You can also display the last cache and fetch in the background when the cache expires. This prevents the first user after the cache expires from having to wait for the content to regenerate. You can specify the time to allow the old cache to display.

Cache-Control: stale-while-revalidate=<seconds>

There are many other cache-control headers available.

Problems

Caching is extremely useful, but ultimately it’s are not as robust as CDN caching. The caches are not shared across regions, and you can only revalidate the cache when it expires. There are other differences from ISR to note as well. That being said, if you don’t care about revalidation, cache-control is a great tool.

Purging

Before the term “on-demand revalidation” was coined, CDNs revalidated a cache by purging it. Usually you had to do this through the CDN dashboard, but you could also use headers.

• Cloudflare
• Fastly

Not all CDNs can be purged by a header request, but this definitely paved the way for what Vercel is doing.

Vercel ISR

Vercel, which uses Cloudflare under the hood, decided to create its own caching technique called Incremental Static Regeneration. Basically, it caches for a certain amount of seconds, and then it revalidates in the background incrementally using a stale while revalidate technique.

You can do this without a framework with the Build Output API. The docs are not clear on using it without a framework, but you can see the example repo. ISR functions on both serverless functions and Edge Functions on the Edge Network.

On-Demand ISR

What really makes ISR incredible is the ability to revalidate the cache on-demand. This means you could update the database, then revalidate your cache programmatically without having to manually touch a dashboard or redeploy your project. The technology has been built into the frameworks to make it easy for developers.

Next.js

For Next.js:

revalidatePath('/');

All paths are cached by default until you revalidate them. You cannot, however, revalidate a path you are currently on. This means you need to revalidate from a different URL.

Server Actions, for example, are created on the current URL, so you you would need to write your code accordingly. This now works with the app directory as well. You could and probably should also write your code to validate a key or token before the function gets called for security.

SvelteKit

SvelteKit uses a token by default. To create the cache, put this at the top of the server file you want to cache:

export const config = {
    isr: {
        expiration: false,
        bypassToken: BYPASS_TOKEN
    }
};

And in a different file, you can revalidate it by calling the same file with this header:

await fetch('/', {
    headers: {
        'x-prerender-revalidate': BYPASS_TOKEN
    }
});

Again, you need to revalidate from a different URL. You could also check the fetch results to make sure it completed successfully.

Other Frameworks

While other frameworks support ISR, I could not find an example of other frameworks supporting on-demand ISR. Again this should be possible on Vercel to manually create this using the Build Output API, but it may not be easy to implement. It would probably need to be added to the Vercel adapter for each framework. This would make it very easy for us developers. We may see this over time.

Other Hosting Providers

Since Next.js, a Vercel creation, supports ISR as a framework, other hosting providers have slowly released their take on ISR. React and Next.js are extremely popular outside of Vercel. Nevertheless, none of them support on-demand ISR.

Netlify

Netlify supports ISR, but doesn’t seem to care to support on-demand revalidation; they would be the provider that we would think would support it. Remember that ISR is not just caching, but the ability to cache and revalidate the cache on the CDN once it expires.

Someone from Netlify wrote a whole article explaining why on-demand revalidation is not great. Isn’t that up to the developer to decide? The whole argument stems on the problems showing an older version of a page. Ultimately this could be fixed given the right conditions.

I think the article was probably written when Netlify decided they didn’t want to give any more resources to create support for it. Either way, the on-demand builders are a vital part of Netlify, which didn’t exist before that time period.

Firebase Hosting

Firebase supports ISR as well, using Firebase Cloud Functions and Fastly CDN under the hood. However, it does not support on-demand revalidation and seems to only work for Next.js, not SvelteKit.

Cloudflare/Any Environment

While Cloudflare is no different and has no framework support for ISR, someone created an article about using Incremental Static Regeneration on Cloudflare Workers. Cloudflare Workers are just edge functions that don’t need to cold start like other types of serverless environments.

Cloudflare has a KV Store, which is globally available like a Redis cache would be. Basically you could use some sort of KV Store or Redis to cache your data and revalidate the cache on-demand.

This could be comparably fast to ISR depending on your region, server and database used. Upstash wrote an article comparing Redis and Cloudflare Workers KV.

If you don’t want to be vendor locked-in, this is your best bet. They are all eventually consistent just like ISR on Vercel.

Final Thoughts

Incremental Static Regeneration is an incredible technology, but it is the on-demand part that really shines. Unfortunately this is only available on Vercel, and only works out of the box with Next.js and SvelteKit.

However, using an edge database could be just as useful. If I’m using a database like Firebase, where I get charged per read, this could save me thousands while being much faster. If I am using a database that doesn’t scale well, this could keep my server in check. If I want to save money on function iterations, using Vercel caching techniques could save me there as well. All in all, it saves you money and makes your site faster.

You should be using it.