Overview of Workbox V3

Workbox's v3 release represents a significant refactoring of the existing codebase.

🎉 Whats New

Minimize the size of Workbox

The amount of service worker runtime code that's downloaded and executed has been reduced. Instead of opting everyone in to a monolithic bundle, only code for the specific features that you're using will be imported at runtime.

Workbox has a CDN

We provide a fully supported, Google Cloud Storage-based CDN hosting as the canonical option for accessing the Workbox runtime libraries, making it easier to get up and running with Workbox.

Better Debugging and Logs

The debugging and logging experience has been vastly improved. Debug logs are enabled by default whenever Workbox is used from a localhost origin and all logging and assertions are stripped from the production builds

Improved webpack Plugin

workbox-webpack-plugin integrates more closely with the webpack build process, allowing for a zero-config use case when you want to precache all the assets in the build pipeline.

Achieving these goals, and cleaning up some aspects of the previous interface that felt awkward or led to antipatterns, required introducing a number of breaking changes in the v3 release.

⚠️ Breaking Changes

Build Configuration

The following changes affect the behavior of all of our build tools (workbox-build, workbox-cli, workbox-webpack-plugin), which share a common set of configuration options.

• The 'fastest' handler name was previously valid, and treated as an alias for 'staleWhileRevalidate', when configuring runtimeCaching. It's no longer valid, and developers should switch to using 'staleWhileRevalidate' directly. (https://github.com/GoogleChrome/workbox/issues/915)

• Several runtimeCaching.options property names have been updated, and additional parameter validation is in place that will cause a build to fail if an invalid configuration is used. See the documentation for runtimeCaching for a list of currently supported options. (https://github.com/GoogleChrome/workbox/issues/1096).

workbox-background-sync

• There are significant changes to the API surface in v3. Developers should consult the documentation for current guidance. (https://github.com/GoogleChrome/workbox/issues/868)

workbox-cache-expiration

• The plugin API has stayed the same, however there are significant API changes impacting developers who use it as a standalone class. Consult the documentation for the updated API surface. (https://github.com/GoogleChrome/workbox/issues/920)

workbox-cli

• The set of command line options, and the way of reading in stored configuration, have all changed. Developers should consult the documentation or run the CLI with the --help flag for guidance. (https://github.com/GoogleChrome/workbox/issues/865)

• Support for the workbox-cli alias for the binary script has been removed. The binary can now only be accessed as workbox. (https://github.com/GoogleChrome/workbox/issues/730)

workbox-google-analytics

• While the API surface has not changed, the underlying implementation was updated to use the workbox-background-sync library, and therefore rely on the Background Sync API. (https://github.com/GoogleChrome/workbox/issues/244)

workbox-precaching

• The precache() method previously performed both the cache modifications and set up routing to serve cached entries. Now, precache() only modifies cache entries, and a new method, addRoute(), has been exposed to register a route to serve those cached responses. Developers who want the previous, two-in-one functionality can switch to calling precacheAndRoute(). This enables more developer flexibility. (https://github.com/GoogleChrome/workbox/issues/886).

• workbox-broadcast-update will no longer be automatically configured to announce cache updates for precached assets. To get this behavior, you can add the plugin manually. (https://github.com/GoogleChrome/workbox/issues/1073)

workbox-routing

• The Router will now evaluate Routes in a first-registered-wins order. This is the opposite order of Route evaluation that was used in v2, where the last-registered Route would be given precedence. (https://github.com/GoogleChrome/workbox/issues/845)

• The ExpressRoute class, and support for "Express-style" wildcards have been removed. This reduces the size of workbox-routing considerably. Strings used as the first parameter to workbox.routing.registerRoute() will now be treated as exact matches. Wildcard or partial matches should be handled by RegExps—using any RegExp that matches against part or all of the request URL can trigger a route. (https://github.com/GoogleChrome/workbox/issues/1012)

• The addFetchListener() helper method of the Router class has been removed. Developers can either add their own fetch handler explicitly, or use the interface provided by workbox.routing, which will implicitly create a fetch handler for them. (https://github.com/GoogleChrome/workbox/issues/914)

• The registerRoutes() and unregisterRoutes() methods were removed. The versions of those methods that operate on a single Route were not changed, and developers who need to register or unregister multiple routes at once should make a series of calls to registerRoute() or unregisterRoute() instead. (https://github.com/GoogleChrome/workbox/issues/856)

workbox-strategies (formerly know as workbox-runtime-caching)

• The workbox-runtime-caching module is now officially known as workbox-strategies, and has been published on npm under its new name. (https://github.com/GoogleChrome/workbox/issues/1045)

• The syntax for specifying plugins when configuring a strategy has changed. Each plugin needs to be explicitly listed in the plugins property of the strategy's configuration. (https://github.com/GoogleChrome/workbox/issues/1071)

• Defining a strategy that applies to the default cache name and which uses cache expiration is no longer supported. When configuring cache expiration, you must also configure a specific cache name. (https://github.com/GoogleChrome/workbox/issues/1014)

• The cacheWillMatch lifecycle method has been renamed to cachedResponseWillBeUsed. This should not be a visible change for developers unless they wrote their own plugins that reacted tocacheWillMatch. (https://github.com/GoogleChrome/workbox/issues/713)

workbox-sw

• The handleFetch option has been removed. (https://github.com/GoogleChrome/workbox/issues/1002)

• skipWaiting and clientsClaim are no longer options passed to the WorkboxSW constructor. Instead, they have been changed to methods of the same name that could be called on a WorkboxSW instance. (https://github.com/GoogleChrome/workbox/issues/853)

workbox-webpack-plugin

• The plugin has been substantially rewritten, and in many cases, can be used in a "zero-configuration" mode. Consult the documentation for the updated API surface. (https://github.com/GoogleChrome/workbox/issues/696)