Workbox v4.2.0

🎉 What's New?

Build Tools

• Adds a new navigationPreload config property (defaulting to false) to workbox-build's generateSW and generateSWString modes, which would also expose it to the wrappers like workbox-cli and workbox-webpack-plugin. [#1981]

workbox-core

• Adds workbox.core.cacheNames.prefix and workbox.core.cacheNames.suffix for accessing the current prefix and suffix used in generating cache names. [#2001]

• Adds a new cacheKeyWillBeUsed lifecycle callback. This allows developers to override the default cache key for reads or writes (or both). [#1990]

The interface for the callback looks like:

async function cacheKeyWillBeUsed({request, mode}) {
  // request is the default Request object that would otherwise be used as the cache key.
  // mode is either 'read' or 'write', depending on whether it's a read or a write.
  // Return either a string, or a Request whose url property will be used as the cache key.
  // Returning the original request will make this a no-op.
}

🐛 What's Fixed?

workbox-webpack-plugin

• Convert source to Buffer when getting asset's hash, improving compatibility with some webpack loaders [#1966].
• Added sorting before generating a hash in the precache manifest. [#1973]

Thanks!

Special thanks to @merrywhether, @3846masa and @el for contributions that went into this release.

Workbox v4.1.1

🐛 What's Fixed?

workbox-window

• The removeEventListener() method of the Workbox class would throw due to an implementation error, this has been fixed. [#1963]

• If, at registration time, there was already both an active and waiting service worker with the same script URL as the one being registered, calling getSW() or messageSW() after registration would target the active service worker rather than the waiting service worker. The intended behavior is that the target service worker associated with a Workbox instance is always the most recently registered service worker with a matching script URL. These methods now target the waiting service worker [#1961]

Thanks!

Special thanks to @donavon for contributions that went into this release.

Workbox v4.1.0

🎉 What's New?

workbox-build

• When using the generateSW option to build your service worker, a message listener is now added to the service worker output, which allows you to invoke skipWaiting() from the window via postMessage() [#1929].

🐛 What's Fixed?

workbox-window

• When calling messageSW() after an updated service worker is found, it would send the message to the service worker currently controlling the page. This has been fixed [#1941].

workbox-precaching

• Plugins implementing the cacheDidUpdate method were not properly bound, and would fail in some cases. This has been fixed [#1678].

workbox-background-sync

• If requests were added to a backgroundSync.Queue queue due to server error rather than network error, those requests would be retried immediately, which could lead to an infinite loop. This has been fixed [#1943]

• The backgroundSync.Queue class used to store Request bodies as Blob objects in IndexedDB, but this does not work in Safari. All request bodies are now stored as ArrayBuffer objects [#1932].

workbox-broadcast-update

• If the the BroadcastCacheUpdate instance is passed an install event (which happens when using it as a precache plugin) rather than a fetch event, it would error. This has been fixed [#1938].

Workbox v4.0.0

Overview of Workbox v4

We're happy to announce the release of Workbox version 4! This release introduces a lot of great new features, as well as some breaking changes.

You can read the full list of changes here; we've also published a guide on migrating from v3 to v4.

🎉 What's New?

workbox-window

The workbox-window package is a set of modules that are intended to run in the window context, which is to say, inside of your web pages. They're a complement to the other workbox packages that run in the service worker.

The key features/goals of workbox-window are:

• To simplify the process of service worker registration and updates by helping developers identify the most critical moments in the service worker lifecycle, and making it easier to respond to those moments.
• To help prevent developers from making the most common mistakes.
• To enable easier communication between code running in the service worker and code running in the window.

You can use workbox-window by importing it into your code from our CDN as show in the following example:

<script type="module">
import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/4.0.0/workbox-window.prod.mjs';

if ('serviceWorker' in navigator) {
  const wb = new Workbox('/sw.js');

  wb.register();
}
</script>

To learn more, see the workbox-window usage guide or the Workbox class reference documentation.

workbox-routing

• Logging has improved for workbox.routing.NavigationRoute when a URL matches the blacklist. Now a message with higher priority is logged when using the development builds. [#1741]

• workbox.routing.Router now includes a routes getter method, giving developers access to the underlying Map of routes that have been registered for a given router. [#1714]

• The Router#handleRequest() method no longer requires an event be passed, which allows routing logic to be used programmatically, outside of the context of a fetch event. This can be useful as a way to cache URLs using the same strategies and plugins that you've already defined in your routing logic. [#1682]

workbox-google-analytics

• If you use Google Tag Manager (GTM) to load Google Analytics on your site, Workbox will now cache the gtm.js library so it will work offline as well [#1869].

workbox-broadcast-update

• The workbox-broadcast-update plugin now works in browsers that don't support the BroadcastChannel API by iterating over all the open window clients and sending them the update message via postMessage() API. In addition, the channel parameter is no longer required. If no channel is given the default channel name workbox is used (no channle is used for browsers that don't support the BroadcastChannel API). [#1673]

Build tools

• Support for a new boolean configuration option, cleanupOutdatedCaches, has been added to the GenerateSW mode of all of the build tools. It defaults to false. When set to true, a call to workbox.precaching.cleanupOutdatedCaches() will automatically be added to your generated service worker, which will in turn delete any out-of-date precaches no longer used by Workbox. Workbox v4 introduced a breaking change to the precache format, so developers upgrading from Workbox v3 or earlier might find this useful. [#1863]

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.

🐛 What's Fixed?

workbox-precaching

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

workbox-expiration

• The workbox-expiration documentation states that the maxAgeSeconds option will expire entires based on the time they were last accessed. But due to a bug in the logic, it would actually expire entries based on the time they were originally cached. This has been fixed, and the behavior now matches the documentation [#1883].

workbox-strategies

• The default check for whether a response is cacheable now looks explicitly for a status code of 200, rather than checking for response.ok (which is true for any status code in the range 200-209). In practice, this means that partial responses with a status code of 206 won't be inadvertently cached by default. [#1805]

workbox-webpack-plugin

• In addition to swSrc being a file on the file system, it can now be a webpack generated asset as well. This allows users to compile their service worker with webpack and then give it as a source to inject-manifest plugin. [#1763]

workbox-core

• To work around an issue that could lead to failed navigations, fetchOptions are no longer set when request.mode is 'navigate'. [#1862]

• A new fetchDidSucceed({request, response}) lifecycle callback has been added, allowing developers to inspect and potentially modify a response that's been retrieved from the network, prior to it being passed back to the page. [#1772]

Build tools

• The default injectionPointRegexp option value has been updated to exclude a leading . character, making it friendlier to developers who are bundling their own service worker files. [#1834]

• Support has been added for including JavaScript functions when configuring runtimeCaching in the various build tools. [#1770, #1778]

• workbox-cli now supports a --watch parameter. When used, it will re-run the service worker build whenever any of the files in the precache manifest change. [#1776]

• The workbox-webpack-plugin will append to, rather than overwrite, any existing self.__precacheManifest value, making it easier to combine a precache manifest with the manifest generated by the plugin. [#1775]

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

workbox-google-analytics

• Some content blocking browser extensions would block requests for script files containing the substring analytics. When these requests are blocked, and error is thrown which causes the service worker installation to fail. To prevent this failure from affecting all service worker functionality, 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. [#1688]

  Note: This change is not an attempt to get around content blockers preventing Google Analytics tracking, as requests to all Google Analytics endponts will still be blocked. This change is just to prevent the entire service worker from breaking.

⚠️ Breaking Changes

Global changes

• Various public interfaces and options have been renamed to standardize on capitalization. Most noticeably, 'Url' is now 'URL', 'Sw' is now 'SW', and the various strategyName handler values in runtimeCaching are now StrategyName (e.g. 'cacheFirst' is now 'CacheFirst'). The previous capitalization will remain supported until Workbox v5, but using the old variation will lead to deprecation warnings. All developers are encouraged to update their configuration to match the new, consistent capitalization. [#1833, #1841]

• The npm names of the following two packages has change to reflect their browser namespace:

  • workbox-cache-expiration ➡️ workbox-expiration
  • workbox-broadcast-cache-update ➡️ workbox-broadcast-update

  This change only affects developers who bundle their service worker from npm dependencies. Developers who load Workbox using workbox-sw should not have to change their code. [#1879]

• Our @babel/preset-env transpilation targets have been updated to >= node 6 for node libraries and >= Chrome 56 for service worker libraries. Note: we chose Chrome 56 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]

workbox-core

• Workbox log levels have been removed since now all developer tools support filtering visible logs by level. As a result, workbox.core.setLogLevel(), workbox.core.logLevel, and workbox.core.LOG_LEVELS have all been removed. [#1831]

`workbox...

Workbox v4.0.0-rc.4

The latest RC release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🐛 What's Fixed?

workbox-precaching

• Fixed a bug where precached assets would not trigger the cacheDidUpdate callback because the now contain a __WB_REVISION__ URL parameter. [#1914]

workbox-routing

• Fixed a bug where the message listener add via addCacheListener would throw an error if a message event was received where the event.data property was not an object. [#1913]

Workbox v4.0.0-rc.3

The latest RC release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🎉 What's New?

workbox-window

• Lifecycle events dispatched by the Workbox class now include an isUpdate property. This property can be used to distinguish lifecycle events in the follow scenarios: 1) the very first service worker installation (isUpdate === undefined), 2) an update from a previous service worker version (isUpdate === true).

• The waiting event dispatched by the Workbox class will now include a wasWaitingBeforeRegistration flag in the event that there was already a service worker waiting when the current service worker was registered. When this is true, it typically means there are other open tabs preventing the service worker from activating (or the user is reloading the current tab). See The Service Worker Lifecycle: skip the waiting phase for more details on why this can happen. [#1905]

🐛 What's Fixed?

workbox-routing

• The message event listener added via addCacheListener() now no longer requires event.data.metadata to equal workbox-window. This allows developers not using workbox-window to still be able to send cache messages to their service worker. [#1906]

Workbox v4.0.0-rc.2

The latest RC release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🐛 What's Fixed?

workbox-build

• In the previous release candidate we introduced a bug that broke the copyLibraries functionality of workbox-build. This has been fixed [#1903].

Workbox v4.0.0-rc.1

The latest RC release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🎉 What's New?

workbox-window

• The workbox-window package now ships with a few different build options, to help make it as easy as possible for people to include it in to their existing tool chain [#1895, #1899]. Here's what's currently supported:

1. Requiring workbox-window in node (or any or environment that doesn't support native modules):

// Imports a UMD version with ES5 syntax
const {Workbox} = require('workbox-window');

2. Importing workbox-window via webpack or Rollup in a context where your build does not automatically transpile anything in node_modules:

// Imports the module version with ES5 syntax
import {Workbox} from 'workbox-window';

3. Importing workbox-window via webpack or Rollup in a context where you can handle transpiling yourself (or you don't need to transpile to ES5):

// Imports the module version with ES2015+ syntax
import {Workbox} from 'workbox-window/Workbox.mjs';

Note: option 3 above will usually result in the smallest file size, so it's recommend to do that if your build supports it.

🐛 What's Fixed?

workbox-routing

• The setCatchHandler() and setDefaultHandler() methods were not properly migrated as part of the bundling changes in #1831. This has been fixed, and these method now work as they did before [#1898].

Workbox v4.0.0-rc.0

The latest RC release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🎉 What's New?

workbox-window

• The addition of a scriptVersion option to the Workbox constructor in beta.2. has been reverted, as well as the change to the function signature. The Workbox function signature is now the same as it was in beta.1 [#1876]:

new Workbox(scriptURL, registerOptions);

workbox-google-analytics

• If you use Google Tag Manager (GTM) to load Google Analytics on your site, Workbox will now cache the gtm.js library so it will work offline as well [#1869].

workbox-expiration and workbox-broadcast-update

The npm names of these two packages has change to reflect their browser namespace.

• workbox-cache-expiration ➡️ workbox-expiration
• workbox-broadcast-cache-update ➡️ workbox-broadcast-update

This change only affects developers who bundle their service worker from npm dependencies. Developers who load Workbox using workbox-sw should not have to change their code. [#1879]

⚠️ Breaking Changes

workbox-expiration

• The underlying IndexedDB data model for cached entry metadata has changed from using IndexedDB database names that match the cache name (one database per cache name) to a single database named workbox-expiration. If you had code that was manually inspected this metadata, you'll need to update it to check the new database [#1883].

🐛 What's Fixed?

workbox-window

• workbox-window scripts were not being copied when using the copyLibraries in workbox-build and workbox-cli. This has been fixed [#1871].

workbox-expiration

• The workbox-expiration documentation states that the maxAgeSeconds option will expire entires based on the time they were last accessed. But due to a bug in the logic, it would actually expire entries based on the time they were originally cached. This has been fixed, and the behavior now matches the documentation [#1883].

workbox-build

• After changes to workbox-precaching in beta.1, using the navigationFallback option in workbox-build wouldn't work if your fallback URL had precach metadata added to it. This has been fixed in workbox-build, but anyone using workbox.routing.registerNavigationRoute() and passing it a precached URL will likely need to update their code to use workbox.precaching.getCacheKeyForURL() as well:

// This won't work anymore.
workbox.routing.registerNavigationRoute(myPrecachedURL);

// Instead, do this:
workbox.routing.registerNavigationRoute(
  workbox.precaching.getCacheKeyForURL(myPrecachedURL)
);

Workbox v4.0.0-beta.2

The latest beta release of Workbox v4 includes the following developer-visible changes, in addition to all the changes from the previous pre-releases.

🎉 What's New?

workbox-window

• The Workbox constructor function signature has changed to accept an optional scriptVersion option. To support this new option (and other future options) the constructor now accepts a single object argument [#1861].

// Old way
new Workbox(scriptURL, registerOptions);

// New way 
new Workbox({
  scriptUrl,
  scriptVersion,
  registerOptions,
});

• The properties .active and .controlling have been added to the Workbox class. These are promises which will resolve as soon as Workbox has a reference to a service working in the corresponding state (active or controlling) with a matching scriptURL (and optionally scriptVersion, if used). These are similar to the navigator.serviceWorker.ready promise, but when using scriptVersion you can be sure they won't resolve until the correct version of the script is active/controlling [#1861].

• Workbox event listeners are now always called with an Event-like object (i.e. they have a .type, .target properties), to more closely match how native event listeners work. In the future when all browsers support contructable EventTarget, these will be native Event objects [#1861].

// Old way
myWorkbox.addEventListener('activated', (sw) => {
  // Do something with `sw`.
});

// New way 
myWorkbox.addEventListener('activated', (event) => {
  // The activated service worker is at `event.sw`.
  // And the underlying event that triggered this is at `event.originalEvent`.
});

• The controlling event is now dispatched prior to the activated event, which correctly matches the ordering of when the controllerchange and statechange events fire in the service worker lifecycle. [#1861]

workbox-routing

• The workbox.routing.Router#addCacheListener() method has updated the format off messages it can receive from the window to cache. Previously it would accept an array of URL strings, now it can also accept an array of URL strings or arrays in the form of [url, requestInit]. This is useful if you need to override the default request mode [#1851]

Build tools

• Support for a new boolean configuration option, cleanupOutdatedCaches, has been added to the GenerateSW mode of all of the build tools. It defaults to false. When set to true, a call to workbox.precaching.cleanupOutdatedCaches() will automatically be added to your generated service worker, which will in turn delete any out-of-date precaches no longer used by Workbox. Workbox v4 introduced a breaking change to the precache format, so developers upgrading from Workbox v3 or earlier might find this useful. [#1863]

🐛 What's Fixed?

workbox-webpack-plugin

• In addition to swSrc being a file on file system, it can now be a webpack generated asset as well. This allows users to compile their service worker with webpack and then give it as a source to inject-manifest plugin. [#1763]

workbox-core

• Don't set fetchOptions when request.mode is 'navigate', to work around an issue that could lead to failed navigations. [#1862]