🐛 What's Fixed?

workbox-broadcast-update

• Fixed a bug where some private symbols were not being properly exported from workbox-core, which prevented workbox-broadcast-update from notifying on navigation requests. [#2050]

🎉 What's New?

workbox-background-sync

• Adds a new getAll() method to the Queue class. This can be used to get a list of all unexpired entries in a given queue without removing them. This is useful in situations where replaying the queue is not possible (the user is offline), but you want to show information about the queue to the user. [#2018]

🐛 What's Fixed?

Build Tools

• Fixes a bug where the workbox namespace was used before it was defined, when navigationPreload: true. [#2007]
• Properly passes in a custom channel name when using the broadcastUpdate option in runtimeCaching. [#2017]

workbox-background-sync

• Fixes a bug in which a Request wasn't being clone()ed before re-adding it to the queue. [#2014]
• Ensures that when a navigation request is stored in the queue, it's serialized with a mode of same-origin. [#2015]

Thanks!

Special thanks to @merrywhether and @tarjei for contributions that went into this release.

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

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

🎉 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].

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-strategies

• Workbox previously allowed developers to use workbox-strategies in one of two ways: by calling a workbox.strategies.strategyName() factory method, or by explicitly constructing new workbox.strategies.StrategyName(). To avoid confusion, the workbox.strategies.strategyName() approach is deprecated, and will be removed in v5. We encourage all developers to move to the new workbox.strategies.StrategyName() syntax. [#1831, #1842]

• 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 that 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-precaching

• workbox-precaching will default to confirming that all Responses cached during installation have a non-error (less than 400) HTTP status code. If any Responses have an error code, the install phase will now fail. (The next time the service worker starts up, installation will be re-attempted.) Developers who need to precache Responses that have a 4xx or 5xx status code (e.g., precaching a /not-found.html URL that is served with a status code of 404) can opt-in to allowing that by passing in a custom cacheWillUpdate plugin to the workbox.precaching.PrecacheController's install method.

• workbox-precaching has undergone a major rewrite [#1820] to address the issues detailed in #1793. As a result, existing precached data used by Workbox prior to this beta release can't be reused, and upon registering a service worker that uses this new code, all precached data will be downloaded again. There is more information in our migration guide detailing specific changes you might need to make to account for the new precaching behavior.

workbox-sw

• workbox.skipWaiting() has been renamed to workbox.core.skipWaiting(), and workbox.clientsClaim() has been renamed to workbox.core.clientsClaim(). If you are using the skipWaiting or clientsClaim build configuration options, the new method names will be used in your generated service worker automatically.

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

workbox-background-sync

• The workbox.backgroundSync.Queue class has been updated to give developers more control over how failed requests are replayed when a sync event occurs. Previously, developers could only add requests to the queue (there was no option to remove them). Now they have low-level methods to push, pop, shift, and unshift requests. For the full list of changes and use cases, see #1710.

workbox-range-requests

• workbox-range-requests will now check to see if the Response object it's processing already has an HTTP status code of 206 (indicating that it contains partial content). If so, it will just pass it through unmodified. [#1721]

workbox-webpack-plugin

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

Thanks!

Special thanks to @tanhauhau, @xMokAx, and @tomayac for contributions that went into this release, and to @webmaxru and @jadjoubran for help testing all the pre-releases!

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]

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]

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

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:

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