Skip to content

Add docs for experimental route caching#13305

Merged
sarah11918 merged 10 commits intov6from
v6-route-caching
Mar 4, 2026
Merged

Add docs for experimental route caching#13305
sarah11918 merged 10 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 6a56c8c
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/69a84de5efd9840008833bbe
😎 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
Merged
@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>
@ascorbic @yanthomasdev
Update src/content/docs/en/reference/experimental-flags/route-caching…
60cde86 
….mdx

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
sarah11918
sarah11918 approved these changes Feb 27, 2026
View reviewed changes
Copy link
Member

@sarah11918 sarah11918 left a comment •
edited
Loading

Choose a reason for hiding this comment

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

I think we've decided this one is ready for whenever the feature is released! 🥳

(Assuming no user-facing usage details change in the implementation PR. So, only updates there would require revisiting here!)

@ascorbic
Copy link
Contributor Author

ascorbic commented Mar 2, 2026

@sarah11918 I've added some extra docs, because the memory cache provider now allows some options.

@ascorbic ascorbic requested a review from sarah11918 March 2, 2026 11:49
sarah11918
sarah11918 approved these changes Mar 2, 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.

New docs LGTM!

yanthomasdev
yanthomasdev approved these changes Mar 2, 2026
View reviewed changes
Copy link
Member

@yanthomasdev yanthomasdev left a comment

Choose a reason for hiding this comment

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

LGTM!

@sarah11918 sarah11918 added the Merge Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)! label Mar 2, 2026
@ascorbic
Copy link
Contributor Author

ascorbic commented Mar 4, 2026

The code PR has now been merged

@sarah11918
Copy link
Member

sarah11918 commented Mar 4, 2026

This can merge when the feature is released in withastro/astro#15687 !

@sarah11918 sarah11918 merged commit ffed2ce into v6 Mar 4, 2026
10 checks passed
@sarah11918 sarah11918 deleted the v6-route-caching branch March 4, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ArmandPhilippot ArmandPhilippot ArmandPhilippot left review comments

@sarah11918 sarah11918 sarah11918 approved these changes

@yanthomasdev yanthomasdev yanthomasdev approved these changes

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 Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)! 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