Workbox v6.3.0

Workbox v6.3.0 includes a couple of bug fixes and several new features.

🎉 What's New?

Allow precaching "repair" when using subresource integrity

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]

IDB writes use relaxed durability

This small change to the way Workbox writes to IndexedDB should lead to slightly better performance, without any appreciable downsides. [#2934]

notifyAllClients option in BroadcastCacheUpdate

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]

All WorkboxEvents TypeScript types are now exported

This enhancement makes it easier to use TypeScript to write workbox-window event handlers. [#2919]

Debug logging when caching responses with Vary: headers

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]

🐛 What's Fixed?

workbox-cli

• Update to chokidar dependency, for better node compatibility and to eliminate security warnings. [#2913]

workbox-precaching

• Preserve all request headers in PrecacheCacheKeyPlugin. [#2914]

Workbox v6.2.4

🐛 What's Fixed?

• Passing in functions for onSync and handler in generateSW's runtimeCaching should not fail validation. [#2911]

Workbox v6.2.3

🐛 What's Fixed?

• Move @types/trusted-types to dependencies of workbox-window [#2909]

Workbox v6.2.2

Workbox v6.2.2 fixes a few bugs introduced in the v6.2.0 release.

🐛 What's Fixed?

• 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

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.

🎉 What's New?

workbox-build TypeScript rewrite

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]

Build tool option validation

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.

IndexedDB code migration

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]

Multiple controlling events during a page's lifetime

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]

TrustedScriptURL support in workbox-window

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]

rangeRequests option in runtimeCaching

Setting rangeRequests: true inside of a runtimeCaching configuration entry will add the RangeRequestsPlugin to the service worker generated by Workbox's build tools. [#2871]

🐛 What's Fixed?

workbox-core

• The HandlerDidErrorCallbackParam type definition is now exported alongside the other relevant TypeScript types. [#2886]

workbox-webpack-plugin

• A bug was fixed that could lead to invalid generated code when quotation chars when webpack's eval-cheap-source-map is used along with the InjectManifest plugin. [#2847]

workbox-window

• 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]

Thanks!

Thank you @rockwalrus for contributing a PR [#2857] that went into this release!

Workbox v6.2.0-alpha.0

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.

🎉 What's New?

workbox-build TypeScript rewrite

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]

Build tool option validation

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.

IndexedDB code migration

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]

Multiple controlling events during a page's lifetime

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]

TrustedScriptURL support in workbox-window

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]

rangeRequests option in runtimeCaching

Setting rangeRequests: true inside of a runtimeCaching configuration entry will add the RangeRequestsPlugin to the service worker generated by Workbox's build tools. [#2871]

🐛 What's Fixed?

workbox-core

• The HandlerDidErrorCallbackParam type definition is now exported alongside the other relevant TypeScript types. [#2886]

workbox-webpack-plugin

• A bug was fixed that could lead to invalid generated code when quotation chars when webpack's eval-cheap-source-map is used along with the InjectManifest plugin. [#2847]

workbox-window

• 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]

Thanks!

Thank you @rockwalrus for contributing a PR [#2857] that went into this release!

Installation of the latest pre-release version

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

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.)

🐛 What's Fixed?

workbox-cli

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]

workbox-window

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]

workbox-webpack-plugin

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]

Thanks!

Thank you @jcabak for contributing documentation updates [#2808]!

Workbox v6.1.2

Workbox v6.1.2 includes several fixes to the workbox-cli's wizard mode, and removes some potentially confusing logging.

🐛 What's Fixed?

workbox-build

• A warning message was logged when 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]

workbox-cli

• 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]

workbox-strategies

• There was previously unnecessary logging of an uncaught error when a network request failed while offline, even if the response was eventually provided via the cache. This amounted to extra noise in the JS console, and could be particularly confusing if it was triggered during Chrome's new automatic offline check. This uncaught error should no longer show up in the logs. [#2777]

Thanks!

Special thanks to @ognjenjevremovic for contributing the two workbox-cli PRs that went into this release!

Workbox v6.1.1

Workbox v6.1.1 includes a bug fix for the NetworkFirst strategy, as well as some documentation and TypeScript fixes.

🐛 What's Fixed?

workbox-strategies

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

Thanks!

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

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.

🎉 What's New?

setCatchHandler for individual Routes

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

New "recipes"

The workbox-recipes module has been extended with a few new features:

• A new recipe, 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.
• Adds a warmCache option to page, image, and static resource recipes to allow users to warm those caches.
• Adds a 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

🐛 What's Fixed?

workbox-precaching

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

workbox-webpack-plugin

• Using the 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 #2735

All build tools

• The source-map dependency has been updated to resolve an issue that could occur when run in a Node environment that had a polyfilled fetch(). See #2716

Thanks!

Special thanks to @Spiderpig86 for contributing a PR that was part of this release.