Overview of Workbox V3

Workbox v3 has been focused on reducing the size of the library, while lowering the friction for usage. This has been accomplished thanks to a significant refactoring of the existing codebase. We believe the migration process for most users should be minimal, taking a few hours.

Developers are encouraged to view our documentation, including a migration guide for moving from either Workbox v2 or from sw-precache/sw-toolbox to Workbox v3.

Many thanks to @beatrizdemiguelperez, @raejin, @goldhand for contributing code for the v3 release, and to all the members of the community who tested and gave feedback during our alpha and beta periods.

🥅 High-level Goals for v3

Minimize the size of Workbox

The size of the Workbox libraries has been reduced. Instead of opting everyone in to a monolithic bundle, only code for the features you use will be imported at runtime.

Workbox has official CDN support

We provide a Google Cloud Storage-based CDN of the Workbox runtime libraries, making it easier to get up and running with Workbox.

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.

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

🎉 New Functionality

workbox-build

• globFollow and globStrict added to workbox-build. This means symbolic links will be followed when searching for files and any errors discovered by glob will now throw. (#1104)

workbox-cli

• Support --injectManifest in the workbox-cli wizard. (#1171)

workbox-precaching

• workbox-precaching supports two new configuration options, cleanUrls and urlManipulation. By default cleanUrls is true and will append .html to a reqest when looking for a precache hit (i.e. /about will check for /about.html). urlManipulation can be a function enabling you to express a mapping between the server-side URL and the underlying local file. (#1154)

• If a precached request is not in the cache, we fallback to the network. (#1302)

• Precaching will store requests in a temporary cache on install and copy these requests to final cache during the activate step. (#1316)

• The precaching IndexedDB name is now derived from the cache name - allowing multiple precaches on a single origin. (#1346)

workbox-strategies

• Fallback to the network response whena network timeout is reached and there is no cache hitfor the network-first strategy. (#1301)
• Support for configuring fetch options in a strategy. (#1340)

workbox-webpack-plugin

• Adds support for webpack v4, while retaining support for webpack v3. (#1275)

• workbox-webpack-plugin now supports {test, include, exclude}-style filtering, providing an additional way of controlling which assets are included in the precache manifest. By default, assets matching /\.map$/ or /^manifest\.js(?:on)$/ are excluded. (#1149)

⚠️ 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)

• A new importWorkboxFrom option can be used to determine where the Workbox libraries are read from: the CDN, locally, or from a custom bundle (when using webpack).

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)

• The maxRetentionTime configuration option is now interpreted as a number of minutes, rather than milliseconds. (#1268)

• The tag name is now used when responding to a sync event. (#1280)

workbox-build

• The default destination of a service worker for the CLI has changed from 'build/' to the location of the globDirectory (i.e. the directory searched for files to precache). (#1105)

• The getFileManifestEntries() function has been renamed to getManifest(), and the promise returned now includes additional information about the URLs which are precached.

• The generateFileManifest() function has been removed. Developers are encouraged to call getManifest() instead, and use its response to write data to disk in the appropriate format.

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-cache-expiration now throws an error if you attempt to expire entries on the default runtime cache (i.e. the shared cache used by all strategies by default). (#1079)

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 the workbox namespace. (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)