📦 Workbox: JavaScript libraries for Progressive Web Apps
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]
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!
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 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-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.
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 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.
(There was no v6.0.1 release.)
_handle. [#2687]Special thanks to @pidtuner for raising the issue that was resolved in this release.