w3c / w3c/ServiceWorker

Support CacheStorage.match() options in SW Static Routing API cache source

Open
#1,797 5 comments 0 reactions 1 assignee View on GitHub

@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:

  • ignoreSearch
  • ignoreMethod
  • ignoreVary

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.