Workbox v4.0.0-beta.1

Workbox v4.0.0-beta.1 Release Notes

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?

The workbox-windowpackage

The workbox-window, a library which can be used from the context of your web page (i.e. the window global scope). It provides helpers for registering and detecting updates to your service worker. Functionality will be added over time, and we're looking for early feedback. (#1827)

You can try out workbox-window in dev mode today by adding the following module script to your HTML templates. But be sure change the URL to workbox-window.prod.mjs before deploying your code to production!

<script type="module">
// Important: change the filename to workbox-window.prod.mjs before deploying.
import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/4.0.0-beta.1/workbox-window.dev.mjs'

new Workbox('/sw.js').register();
</script>

For additional usage instructions and API reference, see the design doc.

Other new features:

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

• Support for including JavaScript functions when configuring runtimeCaching in the various build tools. (#1770 and #1778)

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

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

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

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

• Several under-the-hood changes have been made to Workbox's internal build and bundling structure, which should not impact developers using the default, prepackaged libraries. (#1831)

⚠️ Breaking Changes

workbox-precaching rewrite

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.

Changes to cache keys

Entries that are precached will now store any revision information provided in the precache manifest as a special URL query parameter, __WB_REVISION__, appended to the entry's real URL. In practice, that means that a precache entry with a URL of /index.html and revision of abcd1234 would be cached with a key of /index.html?__WB_REVISION__=abcd1234.

If you are using workbox-precaching via the precacheAndRoute() interface, as most developers are, the details of looking up the correct cache key will be handled for your automatically.

If you have a need to manually retrieve a precached entry directly using caches.match(), then you have two options:

• Use the "real" URL, and pass in the ignoreSearch parameter to caches.match(). This does not give you any guarantees about which version of the cached resource you'll retrieve.

• Pass the "real" URL to workbox.precaching.getCacheKeyForURL(), which will return the cache key corresponding to the version of the resource cached by the current service worker. You can then pass this cache key directly to caches.match(). This is the safest approach.

Cleaning up old precached data

After upgrading to the latest Workbox v4.0.0-beta.1 release, any precached data stored by a previous version of Workbox will effectively be "abandoned". Workbox will not attempt to delete outdated precaches, as doing so involves some degree of guessing what the previous precache name was.

A new method, workbox.precaching.cleanupOutdatedCaches() can be manually called if you would like to opt-in to an attempt at cleaning up the correct cache.

Alternatively, if you know the name of your old precache, you can explicitly call caches.delete('old-precache-name') inside of an activate handler instead.

We are looking for feedback about how workbox.precaching.cleanupOutdatedCaches(), as a future release might default to enabling it instead of requiring developers to opt-in to using it.

Removal of workbox.precaching.supressWarnings()

A call to this method was generated by the build tools to turn off some warning messages that might otherwise be logged. This proved unnecessary, and for simplicity's sake, workbox.precaching.supressWarnings() has been removed from Workbox.

Other breaking changes:

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

• 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. (#1842)

• 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 and #1841)

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

🐛 What's Fixed?

• Using fetchOptions to customize the behavior of a network request (e.g., by adding in an extra header) will now work when the request has a mode of 'navigate'. (#1825)

Thanks!

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