Support CacheStorage.match() options in SW Static Routing API cache source
@monica-ch is already working on this.
Since Dec 5, 2025.
- Dominant language
- Bikeshed
- Stars
- 3.6k
- Forks
- 324
- Avg merge
- 14d 22h
- Merged PRs (30d)
- 1
Description
Problem Description
The ServiceWorker Static Routing API provides a powerful cache source type for addRoutes(). Currently, this source allows developers to specify which cache storage to query in two ways:
- Matching against all cache storages (e.g.,
source: "cache"). - Matching against a specific cache storage (e.g.,
source: { cacheName: "my-specific-cache" }).
However, this only controls which cache is checked. The how it is checked is not configurable.
The underlying CacheStorage.match() API, which this feature is analogous to, supports a richer options object that allows for more granular control over the matching logic, including:
ignoreSearchignoreMethodignoreVary
We have received requests from developers who need this same level of control directly within their static routes. For example, a common use case is to serve a cached asset regardless of its URL query parameters (ignoreSearch: true).
Without this feature, developers are forced to fall back to a full fetch event listener in their ServiceWorker to implement this logic, which negates some of the performance benefits of the API.
Proposed Solution
I propose extending the CacheSource dictionary to include an optional options member. This member would be a dictionary that directly corresponds to the options parameter of CacheStorage.match().
The existing RouterSourceDict dictionary would be extended to support this:
// Current
dictionary RouterSourceDict {
DOMString cacheName;
};
// Proposed
dictionary RouterSourceDict {
DOMString cacheName;
// See https://w3c.github.io/ServiceWorker/#dictdef-cachequeryoptions for details
CacheQueryOptions cacheOptions;
};
This would allow developers to define routes with fine-grained cache matching logic.
Examples
Example 1: Match in a specific cache, ignoring URL search parameters
This rule would match a request for /articles/hello?utm_source=... against a cache entry for /articles/hello.
event.addRoutes([
{
condition: { urlPattern: "/articles/*" },
source: {
cacheName: "article-cache",
cacheOptions: {
ignoreSearch: true
}
}
}
]);
Example 2: Match in any cache, ignoring the VARY header
This rule would match against all cache storages, and if a matching response is found, it would be returned even if its VARY header doesn't match the request.
event.addRoutes([
{
condition: { urlPattern: "/images/*" },
source: {
// No cacheName: queries all caches
cacheOptions: {
ignoreVary: true
}
}
}
]);
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.