NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #3288 most downloaded on npm
Simplifies communications with Workbox packages running in the service worker
Last release 5 months ago
04 May 2026
Release timing varies
gaps range from 2 weeks to 13 months
Nearly every release is documented
notes for 37 of 38 stable releases
1 version withdrawn
withdrawn after publishing
8 years old
62 releases · first in 2019
…longer used by Workbox. Workbox v4 introduced a breaking change to the precache format, so developers upgrading from Workbox v3 or earlier might find…
The latest beta release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.
workbox-windowWorkbox constructor function signature has changed to accept an optional scriptVersion option. To support this new option (and other future options) the constructor now accepts a single object argument [#1861].// Old way
new Workbox(scriptURL, registerOptions);
// New way
new Workbox({
scriptUrl,
scriptVersion,
registerOptions,
});
The properties .active and .controlling have been added to the Workbox class. These are promises which will resolve as soon as Workbox has a reference to a service working in the corresponding state (active or controlling) with a matching scriptURL (and optionally scriptVersion, if used). These are similar to the navigator.serviceWorker.ready promise, but when using scriptVersion you can be sure they won't resolve until the correct version of the script is active/controlling [#1861].
Workbox event listeners are now always called with an Event-like object (i.e. they have a .type, .target properties), to more closely match how native event listeners work. In the future when all browsers support contructable EventTarget, these will be native Event objects [#1861].
// Old way
myWorkbox.addEventListener('activated', (sw) => {
// Do something with `sw`.
});
// New way
myWorkbox.addEventListener('activated', (event) => {
// The activated service worker is at `event.sw`.
// And the underlying event that triggered this is at `event.originalEvent`.
});
controlling event is now dispatched prior to the activated event, which correctly matches the ordering of when the controllerchange and statechange events fire in the service worker lifecycle. [#1861]workbox-routingworkbox.routing.Router#addCacheListener() method has updated the format off messages it can receive from the window to cache. Previously it would accept an array of URL strings, now it can also accept an array of URL strings or arrays in the form of [url, requestInit]. This is useful if you need to override the default request mode [#1851]boolean configuration option, cleanupOutdatedCaches, has been added to the GenerateSW mode of all of the build tools. It defaults to false. When set to true, a call to workbox.precaching.cleanupOutdatedCaches() will automatically be added to your generated service worker, which will in turn delete any out-of-date precaches no longer used by Workbox. Workbox v4 introduced a breaking change to the precache format, so developers upgrading from Workbox v3 or earlier might find this useful. [#1863]workbox-webpack-pluginswSrc being a file on file system, it can now be a webpack generated asset as well. This allows users to compile their service worker with webpack and then give it as a source to inject-manifest plugin. [#1763]workbox-coreOne column per quarter.
To avoid confusion, the workbox.strategies.strategyName() approach is deprecated, and will be removed in v5. We encourage all developers to move to th…
Workbox v4.0.0-beta.1 Release Notes
The latest beta release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.
workbox-windowpackageThe workbox-window, a library which can be used from the context of your web page (i.e. the window global scope). It provides helpers for registering and detecting updates to your service worker. Functionality will be added over time, and we're looking for early feedback. (#1827)
You can try out workbox-window in dev mode today by adding the following module script to your HTML templates. But be sure change the URL to workbox-window.prod.mjs before deploying your code to production!
<script type="module">
// Important: change the filename to workbox-window.prod.mjs before deploying.
import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/4.0.0-beta.1/workbox-window.dev.mjs'
new Workbox('/sw.js').register();
</script>
For additional usage instructions and API reference, see the design doc.
workbox-cli now supports a --watch parameter. When used, it will re-run the service worker build whenever any of the files in the precache manifest change. (#1776)
Support for including JavaScript functions when configuring runtimeCaching in the various build tools. (#1770 and #1778)
The workbox-webpack-plugin will append to, rather than overwrite, any existing self.__precacheManifest value, making it easier to combine a precache manifest with the manifest generated by the plugin. (#1775)
A new fetchDidSucceed({request, response}) lifecycle callback has been added, allowing developers to inspect and potentially modify a response that's been retrieved from the network, prior to it being passed back to the page. (#1772)
The default check for whether a response is cacheable now looks explicitly for a status code of 200, rather than checking for response.ok (which is true for any status code in the range 200-209). In practice, this means that partial responses with a status code of 206 won't be inadvertently cached by default. (#1805)
The default injectionPointRegexp option value has been updated to exclude a leading . character, making it friendlier to developers who are bundling their own service worker files. (#1834)
Several under-the-hood changes have been made to Workbox's internal build and bundling structure, which should not impact developers using the default, prepackaged libraries. (#1831)
workbox-precaching rewriteworkbox-precaching has undergone a major rewrite (#1820) to address the issues detailed in #1793. As a result, existing precached data used by Workbox prior to this beta release can't be reused, and upon registering a service worker that uses this new code, all precached data will be downloaded again.
Entries that are precached will now store any revision information provided in the precache manifest as a special URL query parameter, __WB_REVISION__, appended to the entry's real URL. In practice, that means that a precache entry with a URL of /index.html and revision of abcd1234 would be cached with a key of /index.html?__WB_REVISION__=abcd1234.
If you are using workbox-precaching via the precacheAndRoute() interface, as most developers are, the details of looking up the correct cache key will be handled for your automatically.
If you have a need to manually retrieve a precached entry directly using caches.match(), then you have two options:
Use the "real" URL, and pass in the ignoreSearch parameter to caches.match(). This does not give you any guarantees about which version of the cached resource you'll retrieve.
Pass the "real" URL to workbox.precaching.getCacheKeyForURL(), which will return the cache key corresponding to the version of the resource cached by the current service worker. You can then pass this cache key directly to caches.match(). This is the safest approach.
After upgrading to the latest Workbox v4.0.0-beta.1 release, any precached data stored by a previous version of Workbox will effectively be "abandoned". Workbox will not attempt to delete outdated precaches, as doing so involves some degree of guessing what the previous precache name was.
A new method, workbox.precaching.cleanupOutdatedCaches() can be manually called if you would like to opt-in to an attempt at cleaning up the correct cache.
Alternatively, if you know the name of your old precache, you can explicitly call caches.delete('old-precache-name') inside of an activate handler instead.
We are looking for feedback about how workbox.precaching.cleanupOutdatedCaches(), as a future release might default to enabling it instead of requiring developers to opt-in to using it.
A call to this method was generated by the build tools to turn off some warning messages that might otherwise be logged. This proved unnecessary, and for simplicity's sake, workbox.precaching.supressWarnings() has been removed from Workbox.
Workbox log levels have been removed since now all developer tools support filtering visible logs by level. As a result, workbox.core.setLogLevel(), workbox.core.logLevel, and workbox.core.LOG_LEVELS have all been removed.
Workbox previously allowed developers to use workbox-strategies in one of two ways: by calling a workbox.strategies.strategyName() factory method, or by explicitly constructing new workbox.strategies.StrategyName(). To avoid confusion, the workbox.strategies.strategyName() approach is deprecated, and will be removed in v5. We encourage all developers to move to the new workbox.strategies.StrategyName() syntax. (#1842)
Various public interfaces and options have been renamed to standardize on capitalization. Most noticeably, 'Url' is now 'URL', 'Sw' is now 'SW', and the various strategyName handler values in runtimeCaching are now StrategyName (e.g. 'cacheFirst' is now 'CacheFirst'). The previous capitalization will remain supported until Workbox v5, but using the old variation will lead to deprecation warnings. All developers are encouraged to update their configuration to match the new, consistent capitalization. (#1833 and #1841)
workbox.skipWaiting() has been renamed to workbox.core.skipWaiting(), and workbox.clientsClaim() has been renamed to workbox.core.clientsClaim(). If you are using the skipWaiting or clientsClaim build configuration options, the new method names will be used in your generated service worker automatically.
fetchOptions to customize the behavior of a network request (e.g., by adding in an extra header) will now work when the request has a mode of 'navigate'. (#1825)Special thanks to @tanhauhau for contributions that went into this release.
Your coding agent can read these notes before it upgrades. Set up the MCP server →