Add docs for route caching CDN providers#13937
Conversation
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| <p> | ||
|
|
||
| <Since pkg="@astrojs/cloudflare" v="13.6.0" /> |
There was a problem hiding this comment.
Need to double-check that these are the actual adapter versions when the release PR is ready!
ascorbic
added
the
merge-on-release
ArmandPhilippot
left a comment
ArmandPhilippot
left a comment
There was a problem hiding this comment.
Thank you! Overall, this LGTM. I left a few comments/suggestions, but nothing really blocking. They're mostly nitpicking either to improve the readability (shorter sentences) or because I wonder if we are documenting implementation details...
|
|
||
| The provider sets `Cloudflare-CDN-Cache-Control` and `Cache-Tag` headers, which are read by Cloudflare's built-in Worker cache. The adapter enables Worker caching automatically when a Cloudflare cache provider is configured. Both tag-based and path-based invalidation are supported. | ||
|
|
||
| If you enable the [`CF_VERSION_METADATA`](https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/) binding in your Worker config, responses are also tagged with the Worker version that produced them, so a deploy or rollback can purge only the entries written by a specific version. |
There was a problem hiding this comment.
nit: I think splitting the sentence in two could improve readability.
| If you enable the [`CF_VERSION_METADATA`](https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/) binding in your Worker config, responses are also tagged with the Worker version that produced them, so a deploy or rollback can purge only the entries written by a specific version. | |
| If you enable the [`CF_VERSION_METADATA`](https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/) binding in your Worker config, responses are also tagged with the Worker version that produced them. This means a deploy or rollback can purge only the entries written by a specific version. |
|
|
||
| The provider sets `Netlify-CDN-Cache-Control` and `Netlify-Cache-Tag` headers. Cached responses use Netlify's [durable cache](https://docs.netlify.com/platform/caching/#durable-directive) so they are shared across all edge nodes, reducing function invocations. | ||
|
|
||
| Both tag-based and path-based invalidation are supported, using `purgeCache()` from `@netlify/functions` under the hood. |
There was a problem hiding this comment.
Is purgeCache() an important information for the user?
Maybe the following is enough:
Both tag-based and path-based invalidation are supported.
Or, if this is important to say that we use Netlify-specific helpers but purgeCache() itself is not important, maybe this could be something like:
Tag-based invalidation and path-based invalidation are both supported and use built-in Netlify features.
I'm not familiar with Netlify, so I'm wondering if it's useful in the documentation or not (ie. an implementation detail vs. something helpful to users). That's mostly nitpicking, feel free to ignore if you think this should be in docs!
| }); | ||
| ``` | ||
|
|
||
| The provider sets `Vercel-CDN-Cache-Control` and `Vercel-Cache-Tag` headers on responses. Both tag-based and path-based invalidation are supported, using `invalidateByTag()` from `@vercel/functions` under the hood. Tag invalidation is a soft invalidation: cached responses are marked as stale and revalidated in the background using stale-while-revalidate. |
There was a problem hiding this comment.
Same question as for Netlify regarding invalidateByTag().
|
|
||
| 2. **The config helper** — A function exported for users to call in `astro.config.mjs`. It returns a [`CacheProviderConfig` object](#cacheproviderconfig) that tells Astro where to find the runtime module and what options to pass it. This is the same pattern used by `memoryCache()` from `astro/config`. | ||
|
|
||
| Astro exports shared helpers for CDN provider authors from `astro/cache/provider-utils`, including `buildCacheControlDirectives()` for generating cache-control header values, `pathTag()` for generating path-based invalidation tags, `setConditionalHeaders()` for `Last-Modified` and `ETag`, and `collectInvalidationTags()` for normalizing invalidation options. These are the same helpers used by the first-party Cloudflare, Netlify, and Vercel providers. |
There was a problem hiding this comment.
Since the code snippets below do not use these helpers, I feel that it breaks the flow a bit and it might be better to place them at the end of the section, just before "CacheProvider interface".
Or better yet, we could have an "Imports from astro/cache/provider-utils" section with a heading for each import and, in "Writing a custom cache provider", we could simply create a link to this new section.
|
|
||
| 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. | ||
|
|
||
| The incoming `request` is passed as a second argument so a provider can read the URL or request headers, for example to auto-tag responses with their pathname for path-based invalidation. |
There was a problem hiding this comment.
nit: I think splitting the sentence in two could improve readability.
| The incoming `request` is passed as a second argument so a provider can read the URL or request headers, for example to auto-tag responses with their pathname for path-based invalidation. | |
| The incoming `request` is passed as a second argument so a provider can read the URL or request headers. This can be useful to auto-tag responses with their pathname for path-based invalidation. |
2 participants
Description (required)
Adds docs for the three new experimental CDN cache providers. I've added the docs for all providers to the existing experiemntal flag page, rather than the adapter pages.
Related issues & labels (optional)
Code PR: withastro/astro#16335
For Astro version:
6.4. See astro PR withastro/astro#16335.