Skip to content

Workbox v5.0.0-alpha.2

Pre-release
Pre-release
Compare
Choose a tag to compare
@jeffposnick jeffposnick released this 01 Aug 21:18
v5.0.0-alpha.2
0cb0029

🎉 What's New?

additionalManifestEntries option in build tools

All of the build tools (generateSW and injectManifest modes in workbox-build, workbox-cli, and workbox-webpack-plugin) now support a new option: additionalManifestEntries. [#2124] It can be set to a list of additional precache manifest entries that go beyond what would normally be included as part of your build (such as CDN URLs), and is a shortcut to something that is otherwise possible via the manifestTransforms option.

Before using this feature, please keep in mind that workbox-precaching requires one of two things from each entry in order to keep precached content up to date:

  • The URL contains versioning information, and therefore the contents will never change. E.g. 'https://example.com/v1.0.0/index.js', or 'https://example.com/index.hashValue.js'

  • You include a revision field alongside an unversioned URL, providing versioning information that is updated each time new contents are deployed to that URL. E.g. {url: https://example.com/index.js, revision: hashOfIndexJsContents}

The precache manifest entries generated by Workbox's built tools can automatically add in revision fields for you, but when using additionalManifestEntries, it's up to you to ensure that you only add in versioned URLs, or that you include a revision field that will always change whenever the corresponding URL changes.

To ensure that developers are aware of this, passing in string values in the additionalManifestEntries will result in a non-fatal warning message, asking you tot confirm that your URLs are versioned. To avoid this message, pass in an object with a revision: null property instead of a string, like {url: http://example.com/v1.0.0/index.js, revision: null}.

importScriptsViaChunks in workbox-webpack-plugin's GenerateSW mode

A new option, importScriptsViaChunks, is supported in the GenerateSW mode of the webpack plugin. [#2131] Passing in one or more chunk names will cause the corresponding script files to be included in the generated service worker, via importScripts().

Because of the way script caching works with importScripts(), developers should ensure that their chunks' filenames include a hash, so that changes to a chunk's contents will result in new filename.

Support for subresource integrity metadata in precaching requests

Precache manifest entries can now include an optional property, integrity. If provided, that value will be treated as the integrity metadata for in the fetch() request used to populate the precache. [#2141]

There is currently no option in the Workbox build tools for generating this metadata; it's left as an exercise to developers to uses the manifestTransforms option to post-process the generated precache manifests and add in integrity properties, with appropriate values, to the entries that need that extra validation.

update(), to force a service worker update check

A new update() method has been added to workbox-window. When called, it will invoke the update() method on the underlying ServiceWorkerRegistration object. [#2136]

Calling this method is optional, as browsers will automatically check for service worker updates whenever there's a navigation request to a new page, along with a few other scenarios. However, as described in this guide, manually requesting a service worker update can be useful for loong-lived, single-page apps.

🚧 Breaking Changes

Removal of makeRequest() in favor of handle()

Calling makeRequest() is mostly equivalent to calling handle() on one of the workbox-strategy classes. The differences between the two methods were so slight that keeping both around did not make sense. Developers who called makeRequest() should be able to switch to using handle() without any further change. [#2123]

Removal of registerNavigationRoute() in favor of createHandlerForURL()

workbox-routing previously supported a method, registerNavigationRoute(), that, under the hood, did two things:

  1. Detecting whether or not a given fetch event had a mode of 'navigate'.
  2. If so, responding to that request using the contents of a previously cached, hardcoded URL, regardless of which URL being navigated to.

(This is a common pattern to use when implementing the App Shell architecture.)

The second step, generating a response by reading from the cache, falls outside of what we envision workbox-routing accomplishing. Instead, we see it as functionality that should be part of workbox-precaching, via a new method, createHandlerForURL(). This new method can work hand-in-hand with the existing NavigationRoute class in workbox-routing to accomplish the same logic. [#2143]

If you're using the navigateFallback option in one of the build tool's generateSW mode, then the switchover will happen automatically, without requiring any change on your part.

If you're using injectManifest mode and your source service worker calls registerNavigationRoute() directly, then you'll have to make a chance to your code to get the equivalent behavior.

Instead of:

import {getCacheKeyForURL} from 'workbox-precaching/getCacheKeyForURL.mjs'
import {registerNavigationRoute} from 'workbox-routing/registerNavigationRoute.mjs'

const appShellCacheKey = getCacheKeyForURL('/app-shell.html');
registerNavigationRoute(appShellCacheKey, {
  whitelist: [...],
  blacklist: [...],
});

You would need to change to:

import {createHandlerForURL} from 'workbox-precaching/createHandlerForURL.mjs'
import {NavigationRoute} from 'workbox-routing/NavigationRoute.mjs'
import {registerRoute} from 'workbox-routing/registerRoute.mjs'

const handler = createHandlerForURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  whitelist: [...],
  blacklist: [...],
});
registerRoute(navigationRoute);

(You no longer need to call getCacheKeyForURL(), as createHandlerForURL() will take care of that for you.)

In short, this change makes explicit the two steps that registerNavigationRoute() used to implicitly perform.

🐛 What's Fixed?

TypeScript

workbox-routing

  • Pass matchCallback string/number return values through to handlerCallback. [#2134]

workbox-webpack-plugin

  • In InjectManifest mode, using a .ts file as swSrc and omitting swDest will now lead to a compiled service worker that uses the .js extension. [#2117]

  • In GenerateSW mode, using a swDest value that included subdirectories will now work as expected. [#2140]

Thanks

Special thanks to @azizhk and @jaulz for their contributions that went into this release, as well as @derekdowling and @emillundstrm for their issue reports.

Assets 4
Loading