Route caching #1131

ascorbic · 2025-02-28T13:38:57Z

ascorbic
Feb 28, 2025
Maintainer

Astro route caching

Summary

Introduce a platform-agnostic route caching API for Astro SSR pages. This feature enables developers to declaratively define caching rules per route and dynamically override them in middleware or API handlers. It provides a consistent API across Node.js, Vercel, Netlify, Cloudflare, and other deployment targets, ensuring efficient caching while allowing cache invalidation by path or tag when supported. Where possible it will be implemented using CDN caches, but with fallback implemntations where this isn't supported.

Background & Motivation

Currently, caching in Astro SSR requires manually setting Cache-Control or CDN-Cache-Control headers, which vary per platform and is not ergonomic. Many modern frameworks offer built-in support for SSR caching strategies, allowing pages to be served efficiently while reducing function invocations and improving performance.

Astro's current lack of a unified caching API means that users must implement custom caching solutions per deployment target, leading to unnecessary complexity. This proposal introduces a framework-level abstraction for caching that integrates seamlessly with Astro’s adapter system, providing an intuitive DX while using platform-specific caching mechanisms where available.

Goals

Provide a platform-agnostic caching API for Astro SSR routes and server islands.
Support TTL, stale-while-revalidate (SWR), and ETag-based caching.
Cache in the CDN where possible, using HTTP cache or CacheStorage.
Allow declarative caching definitions in config, with overrides in Astro pages and server islands.
Enable imperative cache invalidation via by path and tag for fine-grained control.
Use platform-specific caching mechanisms (CDN, edge cache, etc.) via Astro adapters where available.
Maintain a consistent API and DX across deployment targets.

Non-goals

Persistent cache storage in core. This is delegated to the CDN.
fetch cache. This is for responses only.
Page fragment cache, except for server islands. This is designed for caching complete responses.
Browser cache handling, except for setting etag and respecting conditional requests.
Cache rules for prerendered pages.

Example

Declarative API

Cache rules can be declared via route patterns in config:

// astro.config.mjs
export default {
  cache: {
    routes: {
      '/': { maxAge: 0, swr: 60 },
      '/blog/**': { maxAge: 300 },
      '/api/**': { maxAge: 600 },
    }
  }
};

They can be overridden in an Astro page or island's frontmatter:

---
Astro.cache({
  maxAge: 300,  // Cache for 5 minutes
  swr: 3600,    // Allow stale content for 1 hour while revalidating. In seconds or boolean. Default `true`, meaning 1 hour.
  tags: ['blog', 'blog:1'],   // Optional cache tags for invalidation
});
---

<html>…</html>

Invalidation

Helper functions allow cache invalidation where the adapter supports it:

// In an API handler or webhook:

import { invalidate } from "astro:cache"

invalidate({
    path: '/blog/my-article', // Invalidate a single page
    tag: ['blog', 'home'] // Invalidate all pages tagged as "blog" or "home"
});

This uses adapter hooks under the hood, which call the platform-specific APIs. By providing a unified API, Astro ensures that caching is easy to configure while remaining adaptable to different hosting environments.

Adapter support

Each platform has slightly different levels of support, so would need to declare this via features. Where possible this would be implemented with CDN-Cache-Control headers. The cache config could allow users to specify the header names, for example.

We would implement an optional lightweight cache for the Node adapter using in-memory LRU, but would recommend using an external proxy or CDN cache.

florian-lefebvre · 2025-03-12T17:04:48Z

florian-lefebvre
Mar 12, 2025
Maintainer

I'm in favor of promoting this to Stage 2

0 replies

matthewp · 2025-03-12T17:52:36Z

matthewp
Mar 12, 2025
Maintainer

I agree with the Goals here! I think it's ready for stage 2.

0 replies

natemoo-re · 2025-03-12T21:26:17Z

natemoo-re
Mar 12, 2025

Exciting to see! I'm in favor of promoting to Stage 2.

0 replies

lucacasonato · 2025-03-16T21:15:59Z

lucacasonato
Mar 16, 2025

This seems like a great direction! I think it is helpful for Astro to minimally abstract over underlying hosting primitives like this to enable users to more easily move between hosting providers.

0 replies

jazsouf · 2025-03-17T07:27:52Z

jazsouf
Mar 17, 2025

The fact that you can do this in top routes, but also in server island would be a killer feature for CMS driven websites!

But, would the caching work if there is a session check or AB test inside a route?

1 reply

ascorbic Mar 17, 2025
Maintainer Author

It would work via cache headers, so if you're doing sessions or A/B testing you'd need to handle that yourself. You could do it with a Vary header and cookie for A/B tests, but it would be a public cache so not suitable for anything that needs a session.

FredKSchott · 2025-03-18T18:00:22Z

FredKSchott
Mar 18, 2025
Maintainer

Sounds great! Would love to see this explored more. +1 to move to Stage 2.

The idea of putting this responsibility fully in the developers hands (aka managing Cache-Control and CDN-Cache-Control) always sounds nice from a first principles standpoint of doing less / getting out of the way, but we've seen this play out a few times against the Astro user. For example, before adapters were able to set caching rules for bundled + fingerprinted assets, many Astro sites performed slower than they needed to out of the box because the devs weren't familiar with these headers, or didn't realize that they had to manage them themselves.

So for me, a big reason to take this this responsibility on as a framework is to be able to set good defaults.

0 replies

ascorbic · 2025-03-19T15:16:35Z

ascorbic
Mar 19, 2025
Maintainer Author

This has been moved to stage 2! Continue discussion here

0 replies

Uh oh!

Route caching #1131

Uh oh!

Uh oh!

ascorbic Feb 28, 2025 Maintainer

Astro route caching

Summary

Background & Motivation

Goals

Non-goals

Example

Declarative API

Invalidation

Adapter support

Replies: 7 comments · 1 reply

Uh oh!

florian-lefebvre Mar 12, 2025 Maintainer

Uh oh!

matthewp Mar 12, 2025 Maintainer

Uh oh!

natemoo-re Mar 12, 2025

Uh oh!

lucacasonato Mar 16, 2025

Uh oh!

jazsouf Mar 17, 2025

Uh oh!

ascorbic Mar 17, 2025 Maintainer Author

Uh oh!

FredKSchott Mar 18, 2025 Maintainer

Uh oh!

Uh oh!

ascorbic Mar 19, 2025 Maintainer Author

ascorbic
Feb 28, 2025
Maintainer

Replies: 7 comments 1 reply

florian-lefebvre
Mar 12, 2025
Maintainer

matthewp
Mar 12, 2025
Maintainer

natemoo-re
Mar 12, 2025

lucacasonato
Mar 16, 2025

jazsouf
Mar 17, 2025

ascorbic Mar 17, 2025
Maintainer Author

FredKSchott
Mar 18, 2025
Maintainer

ascorbic
Mar 19, 2025
Maintainer Author