Route caching
Added in:
astro@7.0.0
Astro provides a platform-agnostic API for caching responses from on-demand rendered pages and endpoints. Cache directives set in your routes are translated into the appropriate headers or runtime behavior depending on your configured cache provider.
Route caching builds on standard HTTP caching semantics, including max-age and stale-while-revalidate, with support for tag-based and path-based invalidation, config-level route rules, and pluggable cache providers that adapters can set automatically.
Configure caching
Section titled “Configure caching”Route caching requires a cache provider to determine how caching is implemented at runtime. A built-in in-memory provider is available, and custom providers can be implemented for advanced use cases and specific runtimes.
To enable this feature, set a cache provider in your Astro config:
import { defineConfig, memoryCache } from 'astro/config';import node from '@astrojs/node';
export default defineConfig({ adapter: node({ mode: 'standalone' }), cache: { provider: memoryCache(), },});You can then use Astro.cache in your .astro pages (or context.cache for API routes and middleware) to control caching per request. Cache defaults for groups of routes can also be defined declaratively in your config using routeRules.
If you deploy to Netlify, Vercel, or Cloudflare, you can use their respective adapters’ experimental CDN cache provider instead of the in-memory provider.
Adapter cache providers
Section titled “Adapter cache providers”Astro’s first-party adapters for Netlify, Vercel, and Cloudflare each provide an experimental CDN cache provider that maps cache directives to the platform’s native cache headers and invalidation API. Rather than storing responses in memory, these push your caching directives to the host’s edge network, and cache hits are served straight from the CDN without invoking your server function.
During the experimental phase these providers need to be manually enabled, as shown below. In a future release, they will be enabled automatically by their adapters.
Each provider automatically tags cached responses with the request path, so cache.invalidate({ path }) works on platforms that only support tag-based purges.
Netlify
Section titled “Netlify”
Added in:
@astrojs/netlify@8.0.0
Import cacheNetlify() from @astrojs/netlify/cache and set it as your cache provider:
import { defineConfig } from 'astro/config';import netlify from '@astrojs/netlify';import { cacheNetlify } from '@astrojs/netlify/cache';
export default defineConfig({ adapter: netlify(), cache: { provider: cacheNetlify(), },});The provider sets Netlify-CDN-Cache-Control and Netlify-Cache-Tag headers. Cached responses use Netlify’s durable cache so they are shared across all edge nodes, reducing function invocations. Both tag-based and path-based invalidation are supported.
Vercel
Section titled “Vercel”
Added in:
@astrojs/vercel@11.0.0
New
Import cacheVercel() from @astrojs/vercel/cache and set it as your cache provider:
import { defineConfig } from 'astro/config';import vercel from '@astrojs/vercel';import { cacheVercel } from '@astrojs/vercel/cache';
export default defineConfig({ adapter: vercel(), cache: { provider: cacheVercel(), },});The provider sets Vercel-CDN-Cache-Control and Vercel-Cache-Tag headers. Both tag-based and path-based invalidation are supported. Tag invalidation is a soft invalidation: cached responses are marked as stale and revalidated in the background using stale-while-revalidate.
Cloudflare
Section titled “Cloudflare”
Added in:
@astrojs/cloudflare@14.0.0
Import cacheCloudflare() from @astrojs/cloudflare/cache and set it as your cache provider:
import { defineConfig } from 'astro/config';import cloudflare from '@astrojs/cloudflare';import { cacheCloudflare } from '@astrojs/cloudflare/cache';
export default defineConfig({ adapter: cloudflare(), cache: { provider: cacheCloudflare(), },});The provider sets Cloudflare-CDN-Cache-Control and Cache-Tag headers. Both tag-based and path-based invalidation are supported.
The adapter enables the Cloudflare Workers Cache with default settings when a Cloudflare cache provider is used. You can change the configuration if needed, for example if you want to preserve the cache when you deploy a new version of the site.
Interacting with the cache
Section titled “Interacting with the cache”The cache object provides methods for setting cache options, invalidating entries, and checking the current cache state. This object is available in your .astro pages as Astro.cache, and in API routes and middleware as context.cache.
Checking if caching is enabled
Section titled “Checking if caching is enabled”When caching is not configured, cache.set(), cache.tags, and cache.options log a warning, and cache.invalidate() throws an error. To avoid this, wrap your caching logic in a conditional check using cache.enabled. Its value is always false when no provider is configured or in development mode.
---if (Astro.cache.enabled) { const tags = await getProductTags(Astro.params.id); Astro.cache.set({ maxAge: 3600, tags });}---Setting cache options
Section titled “Setting cache options”Call cache.set() with an options object to enable caching for the current response.
The following example caches a page for 2 minutes, serves stale content for 1 minute while revalidating, and tags the response for targeted invalidation:
---export const prerender = false; // Not needed in 'server' mode
Astro.cache.set({ maxAge: 120, swr: 60, tags: ['home'],});---
<html><body>Cached page</body></html>