feat: route caching by ascorbic · Pull Request #15579 · withastro/astro

ascorbic · 2026-02-19T14:34:32Z

Changes

Adds a new experimental Route Caching API and Route Rules for controlling SSR response caching. See the RFC for full details.

Route caching gives you a platform-agnostic way to cache server-rendered responses, based on web standard cache headers. You set caching directives in your routes using Astro.cache (in .astro pages) or context.cache (in API routes and middleware), and Astro translates them into the appropriate headers or runtime behavior depending on your adapter. You can also define cache rules for routes declaratively in your config using experimental.routeRules, without modifying route code.

Getting started

Enable the feature by configuring experimental.cache with a cache provider in your Astro config:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import { memoryCache } from 'astro/config';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  experimental: {
    cache: {
      provider: memoryCache(),
    },
  },
});

Using `Astro.cache` and `context.cache`

In .astro pages, use Astro.cache.set() to control caching:

---
// src/pages/index.astro
Astro.cache.set({
  maxAge: 120,       // Cache for 2 minutes
  swr: 60,           // Serve stale for 1 minute while revalidating
  tags: ['home'],    // Tag for targeted invalidation
});
---
<html><body>Cached page</body></html>

In API routes and middleware, use context.cache:

// src/pages/api/data.ts
export function GET(context) {
  context.cache.set({
    maxAge: 300,
    tags: ['api', 'data'],
  });
  return Response.json({ ok: true });
}

Cache options

cache.set() accepts the following options:

maxAge (number): Time in seconds the response is considered fresh.
swr (number): Stale-while-revalidate window in seconds. During this window, stale content is served while a fresh response is generated in the background.
tags (string[]): Cache tags for targeted invalidation. Tags accumulate across multiple set() calls within a request.
lastModified (Date): When multiple set() calls provide lastModified, the most recent date wins.
etag (string): Entity tag for conditional requests.

Call cache.set(false) to explicitly opt out of caching for a request.

Multiple calls to cache.set() within a single request are merged: scalar values use last-write-wins, lastModified uses most-recent-wins, and tags accumulate.

Invalidation

Purge cached entries by tag or path using cache.invalidate():

// Invalidate all entries tagged 'data'
await context.cache.invalidate({ tags: ['data'] });

// Invalidate a specific path
await context.cache.invalidate({ path: '/api/data' });

Config-level route rules

Use experimental.routeRules to set default cache options for routes without modifying route code. Supports Nitro-style shortcuts for ergonomic configuration:

import { memoryCache } from 'astro/config';

export default defineConfig({
  experimental: {
    cache: {
      provider: memoryCache(),
    },
    routeRules: {
      // Shortcut form (Nitro-style)
      '/api/*': { swr: 600 },

      // Full form with nested cache
      '/products/*': { cache: { maxAge: 3600, tags: ['products'] } },
    },
  },
});

Route patterns support static paths, dynamic parameters ([slug]), and rest parameters ([...path]). Per-route cache.set() calls merge with (and can override) the config-level defaults.

You can also read the current cache state via cache.options:

const { maxAge, swr, tags } = context.cache.options;

Cache providers

Cache behavior is determined by the configured cache provider. There are two types:

CDN providers set response headers (e.g. CDN-Cache-Control, Cache-Tag) and let the CDN handle caching. Astro strips these headers before sending the response to the client.
Runtime providers implement onRequest() to intercept and cache responses in-process, adding an X-Astro-Cache header (HIT/MISS/STALE) for observability.

Built-in memory cache provider

Astro includes a built-in in-memory LRU cache provider. Import memoryCache from astro/config to configure it.

Features:

In-memory LRU cache with configurable max entries (default: 1000)
Stale-while-revalidate support
Tag-based and path-based invalidation
X-Astro-Cache response header: HIT, MISS, or STALE

Writing a custom cache provider

A cache provider is a module that exports a factory function as its default export:

import type { CacheProviderFactory } from 'astro';

const factory: CacheProviderFactory = (config) => {
  return {
    name: 'my-cache-provider',
    // For CDN-style: set response headers
    setHeaders(options) {
      const headers = new Headers();
      if (options.maxAge !== undefined) {
        headers.set('CDN-Cache-Control', `max-age=${options.maxAge}`);
      }
      return headers;
    },
    // For runtime-style: intercept requests (optional)
    async onRequest(context, next) {
      // ... check cache, call next(), store response
    },
    // Handle invalidation
    async invalidate(options) {
      // ... purge by tags or path
    },
  };
};

export default factory;

Error handling

If you use Astro.cache or context.cache without enabling the feature, Astro throws an AstroError with the name CacheNotEnabled and a message explaining how to configure it. If the configured provider cannot be resolved, Astro throws CacheProviderNotFound at build time.

Testing

Adds comprehensive test suite

Docs

withastro/docs#13305

changeset-bot · 2026-02-19T14:34:38Z

🦋 Changeset detected

Latest commit: 2a10742

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…time Adds the foundational building blocks for the route caching feature (RFC #1245): - CacheOptions, CacheProvider, CacheProviderFactory, InvalidateOptions types - Zod config schema (CacheSchema) registered under experimental.cache - AstroCache class with set() merge semantics, tags accumulation, invalidate(), _applyHeaders() - NoopAstroCache for dev mode - Utility functions: normalizeCacheDriverConfig, cacheConfigToManifest, defaultSetHeaders - Public type exports from astro package

Integrates the cache system into the full request lifecycle: - Virtual module vite-plugin for cache driver resolution (resolves from project root) - SSRManifest: cacheDriver and cacheConfig fields - BasePipeline: getCacheProvider() with lazy resolution - RenderContext: creates AstroCache/NoopAstroCache per request, exposes on Astro.cache and context.cache (API routes, actions, middleware) - App base: wraps onRequest for runtime providers, strips CDN headers after; applies _applyHeaders for CDN-based providers - Serialized manifest: cache driver import + config serialization - Throwing getter on Astro global for prerendered routes

Compiles cache.routes patterns using Astro's existing route parsing infrastructure (getParts, getPattern, routeComparator). Patterns use the same [param]/[...rest] syntax as file-based routing. Most specific route wins, computed once at startup via compileCacheRoutes().

72 unit tests covering: - AstroCache runtime: set() merge semantics, tags, invalidate, _applyHeaders, _isActive - Utils: defaultSetHeaders, normalizeCacheDriverConfig, cacheConfigToManifest, isCacheHint, isLiveDataEntry - NoopAstroCache: all methods callable and no-op - Route matching: exact paths, dynamic params, rest params, priority ordering 6 integration tests with mock CDN provider: - CDN-Cache-Control and Cache-Tag from context.cache.set() - cache.set(false) opt-out, tags-only, config-level routes - .astro page and API route support

Runtime cache provider for @astrojs/node with: - In-memory LRU cache (custom Map-based, no external deps) - SWR support via stale-while-revalidate with background revalidation - Tag-based and path-based invalidation - X-Astro-Cache response header (HIT/MISS/STALE) for observability - Auto-set as default when experimental.cache is enabled without a driver - Exported as @astrojs/node/cache subpath

8 tests covering the full runtime caching lifecycle: - Default driver auto-configuration - Cache hit/miss behavior with body verification - CDN header stripping for runtime providers - Tag-based and path-based invalidation - cache.set(false) opt-out - Uncached route passthrough

Full phased implementation plan for RFC #1245 covering: - Phases 1-3: Core types, pipeline wiring, route matching (complete) - Phase 4: Node adapter with in-memory LRU (complete) - Phase 5: Cloudflare adapter with CacheW - Phase 6: Vercel & Netlify adapters - Phase 7: Documentation

Replace _applyHeaders() and _isActive underscore convention with symbol-keyed methods behind applyCacheHeaders() and isCacheActive() helper functions. The symbols are not exported from the astro package, so users can't access them. Framework call sites import the helpers from the module directly. NoopAstroCache no longer needs the internal methods — the helpers handle the no-op case via 'in' checks.

Breaking: cache.routes moved to experimental.routeRules This commit addresses RFC #1245 feedback: 1. Terminology: Rename 'driver' to 'provider' throughout the cache API. Providers have a richer interface (headers, middleware, invalidation) than the simpler driver pattern used by sessions/unstorage. 2. Configuration: Move cache route config from cache.routes to experimental.routeRules with Nitro-style shortcuts: - Flat cache options: { maxAge: 600, swr: 60 } - Nested form: { cache: { maxAge: 600 } } - Prerender control: { prerender: true } 3. API: Add cache.options getter for full cache state access, complementing the existing cache.tags getter. Files renamed: - cache-driver.ts → cache-provider.ts (both astro + node adapter) - mock-cache-driver.mjs → mock-cache-provider.mjs (test fixture) All 109 tests pass (95 unit + 7 core + 7 node adapter).

routeRules is focused on cache configuration only. Prerender control will be handled separately if/when it's added to the feature.

codspeed-hq · 2026-02-19T14:52:04Z

Merging this PR will not alter performance

✅ 18 untouched benchmarks

_{Comparing feat/route-caching (2a10742) with main (844bdd4)¹}

No successful run was found on main (f9c67c0) during the generation of this report, so 844bdd4 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

…tructor, fix test import)

…om SSR bundle - Move runtime cache code (AstroCache, noop, route-matching, utils) into cache/runtime/ directory following Astro conventions - Remove node:url and node:path imports that leaked into SSR bundle, breaking Cloudflare/edge deployments and verify-no-node-stuff test plugin - Guard getCacheProvider() call in hot path to skip async overhead when no cache provider is configured (addresses CodSpeed benchmark regression)

- Move in-memory LRU cache provider from @astrojs/node to astro core (it's runtime-agnostic, not Node-specific) - Export memoryCache() from astro/config (follows sharpImageService pattern) - Runtime entrypoint at astro/cache/memory (separate from config context) - Remove bare string form for cache provider config (object-only) - Export CacheProviderConfig from public types

The memory cache provider is now in core, so its tests belong here too. Uses testAdapter() + app.render() instead of a live Node server.

# Conflicts: # packages/astro/src/core/app/base.ts

sarah11918

I'll let @yanthomasdev tackle the commas, but just some thoughts from me re: error docs and changeset!

I'll note the changeset is... huge! I do not object, nor do I object to offloading some of that heavy lifting to the docs themselves, if you decide you want to just give more superficial overviews of the various parts of the feature.

.changeset/warm-comics-pump.md

sarah11918 · 2026-02-23T20:35:10Z

packages/astro/src/core/errors/errors-data.ts


+/**
+ * @docs
+ * @kind heading


Just noting that this leaves one errant SVG error at the end, also within this heading.

(Would argue it's that one that's in the wrong place, but if we don't fix it as out of scope in this PR, would be nice to get that error moved somewhere more sensible!

I moved the SVG one up with the image errors

packages/astro/src/core/errors/errors-data.ts

.changeset/warm-comics-pump.md

packages/astro/src/core/cache/config.ts

packages/astro/src/core/cache/memory-provider.ts

packages/astro/src/core/create-vite.ts

florian-lefebvre · 2026-02-24T09:34:23Z

packages/astro/src/core/render-context.ts

 		public partial: undefined | boolean = undefined,
 		public shouldInjectCspMetaTags = pipeline.manifest.shouldInjectCspMetaTags,
 		public session: AstroSession | undefined = undefined,
+		public cache: AstroCache | NoopAstroCache | DisabledAstroCache = disabledAstroCache,


Is there a good reasons to have different types VS just AstroCache?

I've moved it to use an interface

packages/astro/src/types/public/config.ts

github-actions bot added pkg: integration Related to any renderer integration (scope) pkg: astro Related to the core `astro` package (scope) docs pr labels Feb 19, 2026

ascorbic added 12 commits February 19, 2026 14:36

Correctly disable when not configured

08111cb

fix: remove prerender from routeRules (out of scope)

8304765

routeRules is focused on cache configuration only. Prerender control will be handled separately if/when it's added to the feature.

chore: add exact-match comment on path invalidation

27d1cc0

ascorbic force-pushed the feat/route-caching branch from 1d9acb9 to 4c23661 Compare February 19, 2026 14:38

chore: move implementation plan to memory repo

35aaf46

ascorbic force-pushed the feat/route-caching branch from 4c23661 to 35aaf46 Compare February 19, 2026 14:44

ascorbic and others added 10 commits February 19, 2026 16:19

Add slow page

dd0f40d

Merge branch 'main' into feat/route-caching

115d1ae

fix: resolve lint errors (unexport internal schemas, fix generic cons…

cd5ebdb

…tructor, fix test import)

refactor: move memory cache tests from node adapter to astro core

01ee6d1

The memory cache provider is now in core, so its tests belong here too. Uses testAdapter() + app.render() instead of a live Node server.

docs: mention routeRules in changeset intro

819b9e8

Merge branch 'main' into feat/route-caching

90e0378

perf: skip all cache code in render hot path when no provider configured

66bc24e

Merge remote-tracking branch 'origin/main' into feat/route-caching

403e274

# Conflicts: # packages/astro/src/core/app/base.ts

Merge branch 'main' into feat/route-caching

d9b6b83

ascorbic marked this pull request as ready for review February 23, 2026 16:01

ascorbic mentioned this pull request Feb 23, 2026

Add docs for experimental route caching withastro/docs#13305

Open

sarah11918 reviewed Feb 23, 2026

View reviewed changes

yanthomasdev reviewed Feb 23, 2026

View reviewed changes

.changeset/warm-comics-pump.md Outdated Show resolved Hide resolved

florian-lefebvre reviewed Feb 24, 2026

View reviewed changes

ascorbic and others added 4 commits February 24, 2026 14:57

Merge branch 'main' into feat/route-caching

17e1b18

Changes from review

fb751f6

Tighten up memory cache

d00ffd3

Merge branch 'main' into feat/route-caching

c9dd908

ascorbic requested review from florian-lefebvre and sarah11918 February 26, 2026 17:46

ascorbic and others added 2 commits February 26, 2026 17:47

Merge branch 'main' into feat/route-caching

3005a2a

Fix import

2a10742

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: route caching#15579

feat: route caching#15579
ascorbic wants to merge 30 commits intomainfrom
feat/route-caching

ascorbic commented Feb 19, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

codspeed-hq bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

sarah11918 left a comment

Uh oh!

Uh oh!

sarah11918 Feb 23, 2026

Uh oh!

ascorbic Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

florian-lefebvre Feb 24, 2026

Uh oh!

ascorbic Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

ascorbic commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Getting started

Using Astro.cache and context.cache

Cache options

Invalidation

Config-level route rules

Cache providers

Built-in memory cache provider

Writing a custom cache provider

Error handling

Testing

Docs

Uh oh!

changeset-bot bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

codspeed-hq bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

florian-lefebvre Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ascorbic commented Feb 19, 2026 •

edited

Loading

Using `Astro.cache` and `context.cache`

changeset-bot bot commented Feb 19, 2026 •

edited

Loading

codspeed-hq bot commented Feb 19, 2026 •

edited

Loading

ascorbic Feb 26, 2026 •

edited

Loading