NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #3349 most downloaded on npm
A service worker helper library to manage common request and caching patterns
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 26 of 26 stable releases
1 version withdrawn
withdrawn after publishing
6 years old
31 releases · first in 2020
One column per quarter.
migrate rollup v4 and plugins by @AJIb63PT in https://github.com/GoogleChrome/workbox/pull/3446
actions/cache to v5 by @swissspidy in https://github.com/GoogleChrome/workbox/pull/3491npm audit fix) by @swissspidy in https://github.com/GoogleChrome/workbox/pull/3510Full Changelog: https://github.com/GoogleChrome/workbox/compare/v7.4.0...v7.4.1
v7.4.0 - Critical dependency updates.
v7.4.0
v7.3.0 - Critical dependency updates.
v7.3.0
Updating dependencies with critical vulnerabilities, plus some other dependencies maintenance
Full Changelog: https://github.com/GoogleChrome/workbox/compare/v7.0.0...v7.1.0
Minimum required version Node 16
⚠️ Breaking changes
Nothing published for this version
updating typescript version and types by @tropicadri in https://github.com/GoogleChrome/workbox/pull/3181
Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.5.4...v6.6.0
Webpack plugin can be extended and subclasses can access the config property [#3056]
config property [#3056]workbox-precaching during a fall back to the network, if the request's mode is no-cors, integrity will not be used and the cache entry will not be repaired. [#3099]idb and selenium-assitant versionsFull Changelog: https://github.com/GoogleChrome/workbox/compare/v6.5.3...v6.5.4
Update minimist to a non-vulnerable version. by @lgarron in https://github.com/GoogleChrome/workbox/pull/3053
minimist to a non-vulnerable version. by @lgarron in https://github.com/GoogleChrome/workbox/pull/3053Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.5.2...v6.5.3
Workbox v6.5.2 includes a number of improvements to the TypeScript documentation and exported types, which should in turn improve the generated docume
Workbox v6.5.2 includes a number of improvements to the TypeScript documentation and exported types, which should in turn improve the generated documentation.
A full changelog is available at https://github.com/GoogleChrome/workbox/compare/v6.5.1...v6.5.2
The Workbox v6.5.1 release includes a few changes related to our TypeScript interfaces and documentation.
The Workbox v6.5.1 release includes a few changes related to our TypeScript interfaces and documentation.
A full changelog is available at https://github.com/GoogleChrome/workbox/compare/v6.5.0...v6.5.1
@examples of using our build tools have been added to the TSDocs for workbox-build and workbox-webpack-plugin. [#3038]generateSW(), injectManifest(), and getManifest() methods in workbox-build has been updated from unknown to an appropriate actual type specific to each method. This should lead to better TSDoc generation and type inferences for developers. As this takes what was previously only a runtime check and moves it to a compile-time check, we believe that it should be functionally equivalent to prior releases, but if you run into problems, please let us know by opening an issue. [#3037]default export to workbox-webpack-plugin. [#3036]Removed the dependency on the deprecated source-map-url package. [#3031]
The Workbox v6.5.0 release includes a number of smaller fixes, as well as a major rewrite of the workbox-webpack-plugin to TypeScript.
A full changelog is available at https://github.com/GoogleChrome/workbox/compare/v6.4.2...v6.5.0
workbox-webpack-plugin has been rewritten in TypeScript, and has public TypeScript definitions for its interfaces published as part of this release. We do not anticipate any changes in the underlying functionality as part of this rewrite. [#2882]forceSyncFallback parameter has been added to workbox-background-sync, without changing the default behavior. When forceSyncFallback is explicitly set to true, workbox-background-sync will always attempt to replay queued requests when the service worker starts up and never rely on the sync event listener. Most developers will not need this behavior, but it can be useful when targeting environments that have a non-functional Background Sync implementation, like some Electron runtimes. [#3020]workbox-streams. [#3001]workbox-background-sync which could lead to errors when run through with certain aggressive minifiers. [#3012]waitUntil() was added to the StaleWhileRevalidate strategy, ensuring that it works properly with navigation preload responses. [#3015]source-map-url package. [#3031]Thank you to @roikoren755 for their contributions to the workbox-webpack-plugin TypeScript migration!
The Workbox v6.4.2 release fixes a few issues:
The Workbox v6.4.2 release fixes a few issues:
@apideck/better-ajv-errors to ^0.3.1 by @wopian in https://github.com/GoogleChrome/workbox/pull/2988ExpirationPlugin docs by @mungojam in https://github.com/GoogleChrome/workbox/pull/2987workbox wizard --injectManifest by @jeffposnick in https://github.com/GoogleChrome/workbox/pull/2992Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.4.1...v6.4.2
The Workbox v6.4.1 release fixes a few issues:
The Workbox v6.4.1 release fixes a few issues:
@apideck/better-ajv-errors has been updated, which in turn addresses a security issue in one of its dependencies. [#2977]preloadResponse was incorrect, and has been fixed to reflect the previous definition that used to be provided by the TypeScript standard library. [#2975]request.url into account in StrategyHandler.getCacheKey(). This ensures if a custom strategy overrides the Strategy._handle() method and performs multiple cache operations on different URLs, the cache key is properly calculated for each distinct URL. [#2973]We upgraded @surma/rollup-plugin-off-main to patch a vulnerability from the dependency. [#2962]
Workbox v6.4.0 includes:
size(). [#2941]injectManifest. It returns now returns a warning and continues with execution. [#2959]To our new contributors in this version: @StephanBijzitter and @fuzail-ahmed!
Workbox v6.3.0 includes a couple of bug fixes and several new features.
Workbox v6.3.0 includes a couple of bug fixes and several new features.
Although unexpected, there are edge cases where the precache might not be in an inconsistent state, most likely due to a developer manually deleting something in DevTools.
When this happens, workbox-precaching defaults to falling-back to using a network response (assuming the device is online) when there's a precaching miss. Up until now, workbox-precaching hasn't attempting to use this network response to repopulate the precache, because there are no guarantees that the network response corresponds to the version of the asset specified in the precache manifest.
However, if the precache entry includes an integrity property, then subresource integrity guarantees that the response does correspond to the same version of the asset in the manifest. So it should be safe to "repair" the cache with that response. [#2921]
This small change to the way Workbox writes to IndexedDB should lead to slightly better performance, without any appreciable downsides. [#2934]
BroadcastCacheUpdate uses postMessage() to notify all open tabs controlled by the current service worker about a cache update. This default behavior is not changing.
Setting notifyAllClients: false when configuring BroadcastCacheUpdate and the associated plugin will result in postMessage() only communicating the update to the specific window client that triggered the fetch request which resulted in the cache update. [#2920]
This enhancement makes it easier to use TypeScript to write workbox-window event handlers. [#2919]
The presence of Vary: headers on a cached Response can make it difficult to properly match and delete cache entries. To make it clearer to developers when this is happening, the development builds of Workbox will now log a message to the console when a Response that's being cached includes a Vary: header. [#2916]
chokidar dependency, for better node compatibility and to eliminate security warnings. [#2913]PrecacheCacheKeyPlugin. [#2914]Passing in functions for onSync and handler in generateSW's runtimeCaching should not fail validation. [#2911]
onSync and handler in generateSW's runtimeCaching should not fail validation. [#2911]Move @types/trusted-types to dependencies of workbox-window [#2909]
@types/trusted-types to dependencies of workbox-window [#2909]Workbox v6.2.2 fixes a few bugs introduced in the v6.2.0 release.
Workbox v6.2.2 fixes a few bugs introduced in the v6.2.0 release.
Validation fix for plugin functions passed to runtimeCaching in the build tools. [#2901]
Ensure that our tsc configuration transpiles newer language features down to the ES2017 target level. [#2902]
Update to our lerna configuration to use the --exact tag when publishing to npm, to ensure that all the mutual dependencies in the monorepo use exact version matches, and not ^ versions. [#2904]
Fix WorkboxPlugins schema validation by @jeffposnick in https://github.com/GoogleChrome/workbox/pull/2903
Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.2.0...v6.2.1
Our intention is not to include any breaking changes in v6.2.0, and we've made an effort to maintain the same public interfaces and general behaviors…
Workbox v6.2.0 includes a number of bug fixes and internal refactoring described below.
Our intention is not to include any breaking changes in v6.2.0, and we've made an effort to maintain the same public interfaces and general behaviors while rewriting some of Workbox's internals.
The workbox-build module has been rewritten in TypeScript, following the earlier migration of the workbox-cli module. (workbox-webpack-plugin has not yet been migrated.) Developers who use workbox-build from their own TypeScript code should benefit from the official, accurate type definitions that are now published alongside workbox-build. [#2867]
As part of this change, workbox-build now uses the TypeScript definitions as the source of truth when validating the configuration options developers provide. Previously, joi was used for validation with its own set of schema, and this would sometimes lead to mismatches between what the validation logic thought was okay and what the code actually expected. Developers who inspect the validation errors returned by workbox-build will likely see different error strings in v6.2.0. We expect that moving forward, using TypeScript as the source of truth will lead to fewer of those mismatches.This change applies to both workbox-cli and workbox-webpack-plugin, as well, which rely on workbox-build under the hood.
Another refactoring is the replacement of our previous custom IndexedDB logic with the idb library. No developer-visible changes are expected due to this migration. [#2838]
Following this change, worbox-window's controlling event is fired each time the underlying oncontrollerchange event happens. Multiple controlling events can occur on a long-lived page in which multiple service worker updates take place. isExternal: true will be set when the service worker that takes control is "external," which will always be the case for multiple updates.
Previously, controlling would only be fired once per lifetime of the page, which does not match the documented behavior. This change is considered a bug fix to match the expected behavior, and developers are encouraged to test their logic to ensure that they were not relying on the previous, buggy behavior. [#2817]
Developers who have opted-in to the CSP policy "require-trusted-types-for 'script'" and who are using TypeScript would have previously had trouble using TrustedScriptURLs in workbox-window. This release improves that support. [#2872]
Setting rangeRequests: true inside of a runtimeCaching configuration entry will add the RangeRequestsPlugin to the service worker generated by Workbox's build tools. [#2871]
HandlerDidErrorCallbackParam type definition is now exported alongside the other relevant TypeScript types. [#2886]webpack's eval-cheap-source-map is used along with the InjectManifest plugin. [#2847]ports was missing on the WorkboxMessageEvent. It's been added, mirroring the value of the underlying MessageEvent, when used in an onmessage handler. [#2874]
The WorkboxEventMap type definition is now exported alongside the other relevant TypeScript types. [#2870]
Thank you @rockwalrus for contributing a PR [#2857] that went into this release!
fixing binding issues with idb upgrade callback by @tropicadri in https://github.com/GoogleChrome/workbox/pull/2896
Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.2.0-alpha.0...v6.2.0-alpha.2
fixing binding issues with idb upgrade callback by @tropicadri in https://github.com/GoogleChrome/workbox/pull/2896
Full Changelog: https://github.com/GoogleChrome/workbox/compare/v6.2.0-alpha.0...v6.2.0-alpha.1
Our intention is not to include any breaking changes in v6.2.0, and we've made an effort to maintain the same public interfaces and general behaviors…
Workbox v6.2.0-alpha.0 is the first pre-release version of Workbox v6.2.0. It includes a number of bug fixes and internal refactorings described below.
Our intention is not to include any breaking changes in v6.2.0, and we've made an effort to maintain the same public interfaces and general behaviors while rewriting some of Workbox's internals. However, since a significant amount of refactoring did take place, we wanted to make it available as a pre-release initially, and give developers a chance to test it before we tag it as the latest release in npm.
The workbox-build module has been rewritten in TypeScript, following the earlier migration of the workbox-cli module. (workbox-webpack-plugin has not yet been migrated.) Developers who use workbox-build from their own TypeScript code should benefit from the official, accurate type definitions that are now published alongside workbox-build. [#2867]
As part of this change, workbox-build now uses the TypeScript definitions as the source of truth when validating the configuration options developers provide. Previously, joi was used for validation with its own set of schema, and this would sometimes lead to mismatches between what the validation logic thought was okay and what the code actually expected. Developers who inspect the validation errors returned by workbox-build will likely see different error strings in v6.2.0. We expect that moving forward, using TypeScript as the source of truth will lead to fewer of those mismatches.This change applies to both workbox-cli and workbox-webpack-plugin, as well, which rely on workbox-build under the hood.
Another refactoring is the replacement of our previous custom IndexedDB logic with the idb library. No developer-visible changes are expected due to this migration. [#2838]
Following this change, worbox-window's controlling event is fired each time the underlying oncontrollerchange event happens. Multiple controlling events can occur on a long-lived page in which multiple service worker updates take place. isExternal: true will be set when the service worker that takes control is "external," which will always be the case for multiple updates.
Previously, controlling would only be fired once per lifetime of the page, which does not match the documented behavior. This change is considered a bug fix to match the expected behavior, and developers are encouraged to test their logic to ensure that they were not relying on the previous, buggy behavior. [#2817]
Developers who have opted-in to the CSP policy "require-trusted-types-for 'script'" and who are using TypeScript would have previously had trouble using TrustedScriptURLs in workbox-window. This release improves that support. [#2872]
Setting rangeRequests: true inside of a runtimeCaching configuration entry will add the RangeRequestsPlugin to the service worker generated by Workbox's build tools. [#2871]
HandlerDidErrorCallbackParam type definition is now exported alongside the other relevant TypeScript types. [#2886]webpack's eval-cheap-source-map is used along with the InjectManifest plugin. [#2847]ports was missing on the WorkboxMessageEvent. It's been added, mirroring the value of the underlying MessageEvent, when used in an onmessage handler. [#2874]
The WorkboxEventMap type definition is now exported alongside the other relevant TypeScript types. [#2870]
Thank you @rockwalrus for contributing a PR [#2857] that went into this release!
We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.
Workbox v6.1.5 includes fixes in workbox-cli, workbox-window and workbox-webpack-plugin. Also, the rollup and @rollup/plugin-node-resolve dependencies
Workbox v6.1.5 includes fixes in workbox-cli, workbox-window and workbox-webpack-plugin. Also, the rollup and @rollup/plugin-node-resolve dependencies were updated.
(There was no v6.1.3 or v6.1.4 release.)
In the configuration file generated by workbox wizard the regex for ignoreURLParametersMatching are now serialized correctly, as before they were being serialized as strings and that was causing errors. [#2796]
Added support for external controlling events. The controlling event is now dispatched whether it originated in the current or external service worker. Developers can check the isExternal flag to distinguish between the two. [#2786]
Fix to push an Error object to compilation.warnings instead of strings, since pushing strings causes the warnings to not be bubbled up correctly. See [#2790]
Thank you @jcabak for contributing documentation updates [#2808]!
Workbox v6.1.2 includes several fixes to the workbox-cli's wizard mode, and removes some potentially confusing logging.
Workbox v6.1.2 includes several fixes to the workbox-cli's wizard mode, and removes some potentially confusing logging.
workbox-build was used, due to an update to the @rollup/plugin-replace plugin that it uses. The underlying issue raised in the warning message has been addressed. [#2772]Previously, the wizard question flow would not give developers the opportunity to specify a value to override the default ignoreURLParametersMatching setting. The wizard now provides some context and explicitly asks about overriding this value. [#2763]
There were two issues fixed in the wizard related to entering the globDirectory value: the separator characters, --------, were inadvertently selectable, and additionally, the logic was buggy when a manual directory name was entered. Both of these issues are fixed. [#2766]
Special thanks to @ognjenjevremovic for contributing the two workbox-cli PRs that went into this release!
Workbox v6.1.1 includes a bug fix for the NetworkFirst strategy, as well as some documentation and TypeScript fixes.
Workbox v6.1.1 includes a bug fix for the NetworkFirst strategy, as well as some documentation and TypeScript fixes.
The NetworkFirst strategy uses two promises: one for the network request, and one is the optional networkTimeoutSeconds option is set. If the network request succeeds, then the timeout promise's timer is canceled. However, the strategy previously attempted to wait until both promises resolve before the handler resolves. This meant that, if the network request succeeds before the timeout, the strategy's over handler promise would not properly resolve.
See #2744
Special thanks to @joshkel for both bringing that NetworkFirst issue to our attention, as well as contributing the code for the fix!
Workbox v6.1.0 includes a number of new features, as well as an important fix for a bug that could have affected workbox-precaching behavior in earlie
Workbox v6.1.0 includes a number of new features, as well as an important fix for a bug that could have affected workbox-precaching behavior in earlier v6 releases.
The setCatchHandler() method on a Router allows you to configure "fallback" logic if any handler invoked by that Router returns an error. It can be awkward to use, however, if you have many different Routes registered for the same Router, and you would prefer that the fallback logic only be invoked when one or two particular Route handlers fail.
Starting in this release, each individual Route object has a setCatchHandler() method, allowing you to add fallback logic just to that Route, without affecting any other Routes. To use this method, make sure you explicitly construct a Route first, and then pass that Route to the (overloaded) registerRoute() method:
import {Route, registerRoute} from 'workbox-routing';
import {NetworkOnly, StaleWhileRevalidate} from 'workbox-strategies';
const navigationRoute = new Route(
({event, request, url}) => request.mode === 'navigate',
new NetworkOnly()
);
navigationRoute.setCatchHandler(
({event, request, url}) => {
// Do something to generate a fallback response,
// e.g. read a HTML document from the cache.
}
);
registerRoute(navigationRoute);
// This route, created implicitly via an overloaded registerRoute()
// method, won't have the catch handler applied.
registerRoute(
({event, request, url}) => request.destination === 'image',
new StaleWhileRevalidate()
);
See #2699
The workbox-recipes module has been extended with a few new features:
warmStrategyCache, which takes an array of paths and a Workbox strategy and warms that strategy's cache with those paths at service worker install time.warmCache option to page, image, and static resource recipes to allow users to warm those caches.plugins option to page, image, and static resource recipes to allow users to pass additional plugins to those recipes, allowing a user, for instance, to add a URL normalization plugin to the page recipe.The workbox-recipes documentation has more information and examples.
See #2718
The expected behavior for workbox-precaching is that all URLs listed in the precache manifest need to be considered "cacheable" in order for service worker installation to succeed. By default, workbox-precaching considers any response with a status code less than 400 as being cacheable (including opaque responses, which have a status code of 0). Developers who need to customize this behavior can pass a cacheWillUpdate plugin to workbox-precaching, and use that logic to determine whether or not a response should be precached during installation.
Two bugs were introduced in the Workbox v6.0.0 release:
The default criteria, in which any response with a status of 400 or higher should be considered uncacheable, would lead to the invalid response being inadvertently written to the cache prior to failing the service worker installation. The next time installation was attempted, this previously cached error response wouldn't be retried, so after enough retries, the service worker would eventually finish installation, even though some responses that should have been considered invalid were precached.
If a developer uses a cacheWillUpdate plugin while precaching, returning null from the plugin properly excluded that response from being precached, but it would not cause the overall service worker installation to fail.
Both of these bugs are fixed in the v6.1.0 release. During service worker installation, if any response that is uncacheable (either via the default or custom cacheWillUpdate criteria) is encountered, installation will consistently fail and the invalid response won't be added to the cache.
See #2738
chunks or excludeChunks options could lead to a warning message under some circumstances, due to workbox-webpack-plugin assuming they always corresponded to chunk group names. The code will now check to see if the name matches a chunk itself, not just a group. See #2735source-map dependency has been updated to resolve an issue that could occur when run in a Node environment that had a polyfilled fetch(). See #2716Special thanks to @Spiderpig86 for contributing a PR that was part of this release.
Workbox v6.0.2 resolves an issue that could prevent workbox-precaching from working as expected when loaded via workbox-sw.
Workbox v6.0.2 resolves an issue that could prevent workbox-precaching from working as expected when loaded via workbox-sw.
(There was no v6.0.1 release.)
_handle. [#2687]Special thanks to @pidtuner for raising the issue that was resolved in this release.
This should not result in any breaking changes, and should lead to better long-term consistency in how the two modules access the network and cache.
We're happy to announce the release of Workbox v6!
This release includes additional bug fixes for better compatibility with webpack. As of this release, workbox-webpack-plugin requires webpack v4.40.0 or later (for those still on the v4.x branch) or webpack v.5.9.0 or later (for those who have updated to webpack v5.x).
workbox-webpack-plugin will also now take advantage of the immutable metadata that webpack automatically adds to hashed assets. In most cases, this means that explicitly using dontCacheBustURLMatching in your workbox-webpack-plugin configuration is no longer necessary.
See #2651, #2673, and #2675.
The best way to ensure third-party developers have the power to extend Workbox in ways that fully meet their needs is to base our own strategies on top of the extensibility mechanisms we expose to third-party developers.
Specifically, v6 introduces a new way for third-party developers to define their own Workbox strategies, and all of our built-in strategies have been rewritten on top of this mechanism.
This change also allowed us to rewrite the workbox-precaching codebase to use workbox-strategies as a base. This should not result in any breaking changes, and should lead to better long-term consistency in how the two modules access the network and cache.
See #2446, #2459 and #2569 for more details.
In v6, all Workbox strategy classes (both built-in strategies as well as custom, third-party strategies) must extend the new Strategy base class.
The Strategy base class is responsible for two primary things:
We previously had internal modules call fetchWrapper and cacheWrapper, which (as their name implies) wrap the various fetch and cache APIs with hooks into their lifecycle. This is the mechanism that currently allows plugins to work, but it's not exposed to developers.
The new "handler" class (which this proposal calls StrategyHandler) will expose these methods so custom strategies can call fetch() or cacheMatch() and have any plugins that were added to the strategy instance automatically invoked.
This class would also make it possible for developers to add their own custom, lifecycle callbacks that might be specific to their strategies, and they would "just work" with the existing plugin interface.
In Workbox v5, plugins are stateless. That means if a request for /index.html triggers both the requestWillFetch and cachedResponseWillBeUsed callbacks, those two callbacks have no way of communicating with each other or even knowing that they were triggered by the same request.
In this proposal, all plugin callbacks will also be passed a new state object. This state object will be unique to this particular plugin object and this particular strategy invocation (i.e. the call to handle()).
This allows developers to write plugins where one callback can conditionally do something based on what another callback in the same plugin did (e.g. compute the time delta between running requestWillFetch and fetchDidSucceed or fetchDidFail).
In order to fully leverage the plugin lifecycle state (mentioned above), you need to know when the lifecycle of a given strategy invocation starts and finishes.
To address this need (and others), the following new plugin lifecycle callbacks will be added:
handle() method returns a response. This callback can be used to modify that response before returning it to a route handler or other custom logic.handle() method returns a response. This callback can be used to record any final response details, e.g. after changes made by other plugins.Developers implementing their own custom strategies do not have to worry about invoking these callbacks themselves; that's all handled by a new Strategy base class.
TypeScript definitions for various callback methods have been normalized. This should lead to a better experience for developers who use TypeScript and write their own code to implement or call handlers.
See #2548.
This release includes a new module, workbox-recipes, that combines common routing and caching strategy configurations into ready-to-use code that can be dropped in to your service worker.
You can read more about what's included in the first batch of recipes, as well as how to use them, in #2664.
A new method, messageSkipWaiting(), has been added to the workbox-window module to simplify the process of telling the "waiting" service worker to activate.
This offers some improvements over alternatives:
It calls postMessage() with the de facto standard message body, {type: 'SKIP_WAITING'}, that a service worker generated by Workbox checks for to trigger skipWaiting().
It chooses the correct "waiting" service worker to post this message to, even if it's not the same service worker that workbox-window was registered with.
See #2394.
Many developers were confused by the concept of "external" events in workbox-window, and in practice, they did not end up being a net-positive.
All "external" events are now represented as "normal" events with an isExternal property set to true. This allows developers who care about the distinction to still detect it, and developers who don't need to know can ignore the property.
See #2031.
Taken together, these two changes make the "Offer a page reload for users" recipe cleaner:
<script type="module">
import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0/workbox-window.prod.mjs';
if ('serviceWorker' in navigator) {
const wb = new Workbox('/sw.js');
const showSkipWaitingPrompt = () => {
// This assumes a hypothetical createUIPrompt() method with
// onAccept and onReject callbacks:
const prompt = createUIPrompt({
onAccept: () => {
wb.addEventListener('controlling', () => {
window.location.reload();
});
// This will postMessage() to the waiting service worker.
wb.messageSkipWaiting();
},
onReject: () => {
prompt.dismiss();
}
});
};
// Listening for externalwaiting is no longer needed.
wb.addEventListener('waiting', showSkipWaitingPrompt);
wb.register();
}
</script>
A new boolean parameter, sameOrigin, is passed to the matchCallback function used in workbox-routing. It's set to true if the request is for a same-origin URL, and false otherwise.
This simplifies some common boilerplate:
// In v5:
registerRoute(
({url}) => url.origin === self.location.origin &&
url.pathname.endsWith('.png'),
new StaleWhileRevalidate({cacheName: 'local-png'}),
);
// In v6:
registerRoute(
({sameOrigin, url}) => sameOrigin &&
url.pathname.endsWith('.png'),
new StaleWhileRevalidate({cacheName: 'local-png'}),
);
See #2487.
You can now set matchOptions in workbox-expiration, which will then be passed through as the CacheQueryOptions to the underlying cache.delete() call. (Most developers won't need to do this.)
See #2206.
workbox-precaching has been updated so that only one entry in the precache manifest is requested and cached at a time, instead of attempting to request and cache all of them at once (leaving it to the browser to figure out how to throttle).
This should reduce the likelihood of net::ERR_INSUFFICIENT_RESOURCES errors while precaching, and also should reduce the bandwidth contention between precaching and simultaneous requests made by the web app.
See #2528.
workbox-precaching now includes a PrecacheFallbackPlugin, which implements the new handlerDidError lifecycle method added in v6.
This makes it easy to specify a precached URL as a "fallback" for a given strategy when a response otherwise wouldn't be available. The plugin will take care of properly constructing the correct cache key for the precached URL, including any revision parameter that's needed.
Here's a sample of using it to respond with a precached /offline.html when the NetworkOnly strategy can't generate a response for a navigation request—in other words, displaying a custom offline HTML page:
import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';
// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);
registerRoute(
({request}) => request.mode === 'navigate',
new NetworkOnly({
plugins: [
new PrecacheFallbackPlugin({
fallbackURL: '/offline.html',
}),
],
}),
);
If you're using generateSW to create a service worker for you instead of writing your service worker by hand, you can use the new precacheFallback configuration option in runtimeCaching to accomplish the same thing:
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
This release includes a substantial rewrite to the implementation of workbox-precaching, to build on top of other standard Workbox idioms (like Routes, Strategy subclasses, and custom plugins) as much as possible. There are a few breaking changes, described in the follow section, but they are mostly limited to uncommon use cases, when PrecacheController is instantiated directly. For the most part, these changes are meant to be invisible to developers, but should lead to be better consistency in how routing and request handling works across all of Workbox.
You can read more about what's change in #2638
Only GET requests can be used as cache keys, but there are scenarios in which you might want to use a combination of plugins to transform a POST or PUT request into a cacheable GET request.
You can now use the cacheKeyWillBeUsed lifecycle callback in a plugin to return a GET request with whatever URL you'd like to use as a cache key, and that can then allow the response associated with a POST or PUT to be cached.
See #2615 for more details. Thanks to @markbrocato for their contribution.
The minimum required version of node has been increased to v10.0.0. This applies to workbox-build, workbox-cli, and workbox-webpack-plugin. [#2462]
mode was not intended to be a supported parameter for the injectManifest and getManifest modes of workbox-build and workbox-cli. It's been removed from the documentation and attempting to use it outside of generateSW will now trigger a build error. This does not apply to workbox-webpack-plugin, which does support mode in its InjectManifest plugin. [#2464]
skipWaiting() method in workbox-core wrapped the underlying call to self.skipWaiting() in an install handler. In practice, this caused undue confusion and offered little value, as it's valid to call self.skipWaiting() outside of an install event. As of v6, Workbox's skipWaiting() will no longer add in an install handler, and is equivalent to just calling self.skipWaiting(). Because of this, developers should migrate to calling self.skipWaiting() directly, and Workbox's skipWaiting() will likely be removed in v7. [#2547]While this scenario is uncommon, if you precache a URL that corresponds to an HTTP redirect to an HTML document on a different origin, that cross-origin HTML document can no longer be used to satisfy a navigation request. [#2484]
By default, the fbclid URL query parameter is now ignored when looking up a precached response for a given request. [#2532]
Note: The following changes primarily apply to direct usage of the PrecacheController class. Most developers don't use PrecacheController directly, and instead use static helper methods like precacheAndRoute() exported by workbox-precaching. [#2639]
The PrecacheController constructor now takes in an object with specific properties as its parameter, instead of a string. This object supports the following properties: cacheName (serving the same purpose as the string that was passed in to the constructor in v5), plugins (replacing the addPlugins() method from v5), and fallbackToNetwork (replacing the similar option that was passed to createHandler() and `createHandlerBoundToURL() in v5).
The install() and activate() methods of PrecacheController now take exactly one parameter, which should be set to a corresponding InstallEvent or ActivateEvent, respectively.
The addRoute() method has been removed from PrecacheController. In its place, the new PrecacheRoute class can be used to create a route that you can then register.
The precacheAndRoute() method has been removed from PrecacheController. (It still exists as a static helper method exported by the workbox-precaching module.) It was removed because PrecacheRoute can be used instead.
The createMatchCalback() method has been removed from PrecacheController. The new PrecacheRoute can be used instead.
The createHandler() method has been removed from PrecacheController. The strategy property of the PrecacheController object can be used to handle requests instead.
The createHandler() static export has already been removed from the workbox-precaching module. In its place, developers should construct a PrecacheController instance and use its strategy property.
The route registered with precacheAndRoute() is now a "real" route that uses workbox-routing's Router class under the hood. This may lead to a different evaluation order of your routes if you interleave calls to registerRoute() and precacheAndRoute(). See #1857 and #2402 for more details.
setDefaultHandler() method now takes an optional second parameter corresponding to the HTTP method that it applies to, defaulting to 'GET'. It no longer applies to requests with any HTTP method. If you were using setDefaultHandler() and all of your web app's requests are 'GET', then no changes need to be made. [#2463]v4.40.0 (for users remaining on the webpack v4.x major release) or v5.9.0 (for users who have updated to the webpack v5.x major release). [#2641]We're happy to announce the first release candidate of Workbox v6! We do not anticipate any more breaking changes in between now and the official v6 r…
We're happy to announce the first release candidate of Workbox v6! We do not anticipate any more breaking changes in between now and the official v6 release.
In addition to the changes outlined in the previous release notes, the following has changed since Workbox v5.
This release includes a new module, workbox-recipes, that combines common routing and caching strategy configurations into ready-to-use code that can be dropped in to your service worker.
You can read more about what's included in the first batch of recipes, as well as how to use them, in #2664.
This release includes additional bug fixes for better compatibility with webpack. As of this release, workbox-webpack-plugin requires webpack v4.40.0 or later (for those still on the v4.x branch) or webpack v.5.4.0 or later (for those who have updated to webpack v5.x).
workbox-webpack-plugin will also now take advantage of the immutable metadata that webpack automatically adds to hashed assets. In most cases, this means that explicitly using dontCacheBustURLMatching in your workbox-webpack-plugin configuration is no longer necessary.
See #2651, #2673, and #2675.
Thank you to @dermoumi for their contributions to this release.
We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.
Your coding agent can read these notes before it upgrades. Set up the MCP server →