Skip to content

Comments

Add docs for experimental route caching#13305

Open
ascorbic wants to merge 7 commits intov6from
v6-route-caching
Open

Add docs for experimental route caching#13305
ascorbic wants to merge 7 commits intov6from
v6-route-caching

Conversation

@ascorbic
Copy link
Contributor

@ascorbic ascorbic commented Feb 23, 2026

Description (required)

Adds docs for the experimental route caching flag. See the code PR: withastro/astro#15579 and the RFC: withastro/roadmap#1245 for more details

Also updates the live collections docs to refer to route caching in the sections about cache hints.

Related issues & labels (optional)

  • Closes #
  • Suggested label:

@netlify
Copy link

netlify bot commented Feb 23, 2026 •
edited
Loading

✅ Deploy Preview for astro-docs-2 ready!

Name Link
🔨 Latest commit 6ab3ba7
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/699dc47c4466590007343f7b
😎 Deploy Preview https://deploy-preview-13305--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@ascorbic ascorbic mentioned this pull request Feb 23, 2026
Open
@astrobot-houston
Copy link
Contributor

astrobot-houston commented Feb 23, 2026 •
edited
Loading

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File Note
en/reference/content-loader-reference.mdx Source changed, localizations will be marked as outdated.
en/reference/experimental-flags/route-caching.mdx Localization added, will be marked as complete.
en/reference/modules/astro-content.mdx Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

@sarah11918 sarah11918 added add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. 6.0 merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!) labels Feb 23, 2026
@sarah11918 sarah11918 added this to the v6.0.0 docs milestone Feb 23, 2026
sarah11918
sarah11918 reviewed Feb 23, 2026
View reviewed changes
Copy link
Member

@sarah11918 sarah11918 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow, @ascorbic ! Only a very few small comments from me (most of them just adding specific link anchors that were probably too annoying for you to hunt down in the moment).

I think this one just needs to go straight to @yanthomasdev , for whom I've left all the commas! 🎉

src/content/docs/en/reference/experimental-flags/route-caching.mdx Outdated

Enables a platform-agnostic API for caching responses from [on-demand rendered](/en/guides/on-demand-rendering/) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) including `max-age` and [`stale-while-revalidate`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#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.
Copy link
Member

@sarah11918 sarah11918 Feb 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering whether somewhere around here in the intro, it's worth comparing this feature to ISR? (Astro's solution to X, sometimes known as ISR; Astro's answer to what's normally solved with ISR; While other frameworks attempt to do X with ISR, Astro's route caching accomplishes X+...)

Totally not necessary of course, just thinking how we could have an SEO hit for Astro + ISR and also be able to point people somewhere when they say "what about ISR?"

yanthomasdev
yanthomasdev reviewed Feb 23, 2026
View reviewed changes
ArmandPhilippot
ArmandPhilippot reviewed Feb 23, 2026
View reviewed changes
Copy link
Member

@ArmandPhilippot ArmandPhilippot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The feature looks great! I left a few suggestions, some are nitpickings and others are for consistency with the rest of the docs (e.g. use of tables which don't look very good on small devices).

@ascorbic @yanthomasdev
@ArmandPhilippot @sarah11918
Apply suggestions from code review
eadf6d6 
Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: Armand Philippot <git@armand.philippot.eu>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
yanthomasdev
yanthomasdev reviewed Feb 24, 2026
View reviewed changes
src/content/docs/en/reference/experimental-flags/route-caching.mdx
Comment on lines +2 to +4
title: Experimental Route Caching
sidebar:
label: Route Caching
Copy link
Member

@yanthomasdev yanthomasdev Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: Experimental Route Caching
sidebar:
label: Route Caching
title: Experimental route caching
sidebar:
label: Route caching

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sarah11918 sarah11918 sarah11918 left review comments

@ArmandPhilippot ArmandPhilippot ArmandPhilippot left review comments

@yanthomasdev yanthomasdev yanthomasdev left review comments

Assignees

No one assigned

Labels

6.0 add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!)

Projects

None yet

Milestone

v6.0.0 docs

Development

Successfully merging this pull request may close these issues.

5 participants

@ascorbic @astrobot-houston @sarah11918 @ArmandPhilippot @yanthomasdev