Skip to content

Comments

Add docs for experimental route caching#13305

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

Add docs for experimental route caching#13305
ascorbic wants to merge 4 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 processing.

Name Link
🔨 Latest commit 62dd137
🔍 Latest deploy log https://app.netlify.com/projects/astro-docs-2/deploys/699db077c6ea0d0008d9e19c

@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).

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

</p>

Optional. Translates cache options into response headers. Called after the response is rendered but before it is sent to the client. These headers are stripped from the final response.
Copy link
Member

@ArmandPhilippot ArmandPhilippot Feb 23, 2026

Choose a reason for hiding this comment

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

I'll note we usually don't start the description with "Optional"/"Required"... but maybe this is something to consider for the API block (alongside "Type", "Default"...).

src/content/docs/en/reference/experimental-flags/route-caching.mdx
Comment on lines +530 to +533
| Property | Type | Description |
| -------- | -------------------- | --------------------------------------------------------------------- |
| `path` | `string` | Exact path to invalidate. No glob or wildcard support. |
| `tags` | `string \| string[]` | Tag or tags to invalidate. All entries with matching tags are purged. |
Copy link
Member

@ArmandPhilippot ArmandPhilippot Feb 23, 2026

Choose a reason for hiding this comment

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

Same as above, we usually don't use tables and this is not the most usable on small devices.

ArmandPhilippot
ArmandPhilippot reviewed Feb 23, 2026
View reviewed changes
src/content/docs/en/reference/experimental-flags/route-caching.mdx
| `swr` | `number` | Stale-while-revalidate window in seconds. 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. |
| `lastModified` | `Date` | When multiple `set()` calls provide `lastModified`, the most recent date wins. |
| `etag` | `string` | Entity tag for conditional requests. |
Copy link
Member

@ArmandPhilippot ArmandPhilippot Feb 23, 2026

Choose a reason for hiding this comment

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

Oh, it seems I forgot to add this comment... 🤦🏽 (with the screenshot my comment about tables/small devices will make more sense I guess)

I'm a bit confused by this. We usually don't use tables in docs because they look a bit awful on small devices. We usually use headings for each. This how it looks using Firefox iPhone 11 preview:

screenshot of the table rendered in Firefox iPhone 11 preview

@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 @ArmandPhilippot
Update src/content/docs/en/reference/experimental-flags/route-caching…
62dd137 
….mdx

Co-authored-by: Armand Philippot <git@armand.philippot.eu>
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