Overview of Workbox v4

We're happy to announce the first alpha release of Workbox's v4! This release brings a relatively small number of breaking changes, and we anticipate a straightforward migration for most developers. Here's what to watch out for:

🎉 What's New?

workbox-routing logic can now be used outside of a fetch event

Most of the time a workbox router instance is responding to a fetch event by matching that event's request against the list of registered routes. But there are some cases where you want to reuse your existing routing and caching strategy logic outside of receiving fetch events. The two most common use cases are:

• Caching URLs that were fetched prior to the service worker controlling the page.
• Pre-caching URLs that you think the user will likely need in the near future.

The Router class's handleRequest() method now takes an object in the form of {request, [event]} (where event is optional). When called, the router will then make and cache the request according to whatever caching strategies/plugins are used by the matching route.

Note: the use cases described above are different from pre-caching via workbox-precaching in that they're resources that can best be determined at runtime. workbox-precaching, on the other hand, should be used for caching resources that can best be determined at build time.

See #1682 for details.

workbox-broadcast-cache-update no longer requires the Broadcast Channel API and defers notifications on navigation requests

The workbox-broadcast-cache-update library would previously only work in browsers that supported the Broadcast Channel API. Nothing would happen when it was used in browsers that lacked support.

Starting in v4, the code will automatically fall back to iterating over all the open window clients and sending them an update message, one by one, using the postMessage() API.

In addition, when the workbox-broadcast-cache-update plugin would detect updates for navigation requests, most of the time the page the user is navigating to will not be ready to receive the update notification at the time when it's sent. To help deal with this issue, the plugin now defers notifications on navigation requests until a configurable timeout has passed, or until it receives a ready signal from the window.

See #1673 for details.

MIT Licensing

Workbox has moved from using the Apache 2 license to the MIT license. The motivation is similar to what led Angular to previously make the same switch.

⚠️ Breaking Changes

Modern transpilation targets

Workbox uses the (excellent) Babel project, along with @babel/preset-env, to transpile our source code to various runtime targets.

For Workbox libraries that run in a node environment (e.g. workbox-build, workbox-cli, and workbox-webpack-plugin), we've updated the transpilation target to node version 6. This means we've dropped compatibility with node version 4, which has reached its official end-of-life date. (#1654)

For Workbox libraries that run in the service worker environment (e.g. workbox-sw, and all the other runtime code), we've updated the transpilation target to Chrome 56. We chose this target because it matches the capabilities of Samsung Internet v6 and higher. This means we've dropped compatibility with any browser based on Chrome versions earlier than 56, like Samsung Internet v5. (#1655)

Our intention is to be fully compatible with all "evergreen" browsers, including Chrome, Firefox, Edge, or Safari.

Standard failure behavior for the various workbox-strategies

Previously, the various workbox-strategies would behave differently in failure scenarios. Some, like networkFirst, would resolve with an undefined value when there was a network failure and a cache miss. Other strategies would reject with a NetworkError under a similar failure.

Starting in v4, we've standardized how all of the workbox-strategies behave when they can't return a response due to some combination of network failure and/or cache miss: the promise than they return will consistently reject with a WorkboxError. This makes it much easier to think about handling failures with "fallback content," making patterns using custom handlers like the following work consistently, regardless of the strategy being used. (#1657)

workbox.routing.registerRoute(
  new RegExp('/some/path/prefix'),
  async ({event}) => {
    try {
      return await workbox.strategies.networkFirst().handle({event});
    } catch (error) {
      return caches.match(FALLBACK_URL);
    }
  }
);

workbox-webpack-plugin will now precache manifest.json by default

Previously, the default configuration would cause workbox-webpack-plugin to exclude files named manfiest.json from the list of files to precache. Because some browsers do in fact make use of the service worker cache when reading the web app manifest data, it makes more sense to default to including, rather than excluding, that file. (#1679)

🐛 What's Fixed?

Windows command line compatibility

As a byproduct of updating our projects various npm dependencies to the latest releases, we've fixed and issue that preventing the workbox-cli's wizard command from properly completing when run on a Windows command line environment. (#1658)

Precaching of HTTP 30x redirects

A bug in workbox-precaching previously could have caused URLs that lead to a HTTP 30x redirect to be cached incorrectly. This is now fixed. (#1678)

Failed service worker installations due to workbox-google-analytics

Certain content blocking browser extensions automatically cause calls like importScripts('/path/to/workbox-google-analyics.prod.js)to fail. That failure, in turn, will prevent a service worker from ever successfully installing. To prevent this trickle-down failure scenario, we've renamed the workbox-google-analytics.prod.js and workbox-google-analytics.dev.js to workbox-offline-ga.prod.js and workbox-offline-ga.dev.js.

This renaming does not impact whether or not client pages actually communicate with Google Analytics; it's done to make it more likely that the service worker's installation can complete. (#1688)