Update dependency workbox-webpack-plugin to v6 #75

dev-mend-for-jackfan.us.kg · 2025-01-14T09:21:32Z

This PR contains the following updates:

Package	Type	Update	Change
workbox-webpack-plugin (source)	dependencies	major	`^3.4.1` -> `^6.0.0`

By merging this PR, the issue #16 will be automatically resolved and closed:

Severity	CVSS Score	CVE	Reachability
Critical	9.1	CVE-2019-10744

Release Notes

googlechrome/workbox (workbox-webpack-plugin)

`v6.0.0`: Workbox v6.0.0

Compare Source

Overview of Workbox v6

We're happy to announce the release of Workbox v6!

🎉 What's New?

webpack improvements

This release includes additional bug fixes for better compatibility with webpack. As of this release, workbox-webpack-plugin requires webpack v4.40.0 or later (for those still on the v4.x branch) or webpack v.5.9.0 or later (for those who have updated to webpack v5.x).

workbox-webpack-plugin will also now take advantage of the immutable metadata that webpack automatically adds to hashed assets. In most cases, this means that explicitly using dontCacheBustURLMatching in your workbox-webpack-plugin configuration is no longer necessary.

See #2651, #2673, and #2675.

workbox-strategies improvements

The best way to ensure third-party developers have the power to extend Workbox in ways that fully meet their needs is to base our own strategies on top of the extensibility mechanisms we expose to third-party developers.

Specifically, v6 introduces a new way for third-party developers to define their own Workbox strategies, and all of our built-in strategies have been rewritten on top of this mechanism.

This change also allowed us to rewrite the workbox-precaching codebase to use workbox-strategies as a base. This should not result in any breaking changes, and should lead to better long-term consistency in how the two modules access the network and cache.

See #2446, #2459 and #2569 for more details.

New strategy base class

In v6, all Workbox strategy classes (both built-in strategies as well as custom, third-party strategies) must extend the new Strategy base class.

The Strategy base class is responsible for two primary things:

Invoking plugin lifecycle callbacks common to all strategy handlers (e.g. when they start, respond, and end).
Creating a "handler" instance, that can manage state for each individual request a strategy is handling.

A new "handler" class

We previously had internal modules call fetchWrapper and cacheWrapper, which (as their name implies) wrap the various fetch and cache APIs with hooks into their lifecycle. This is the mechanism that currently allows plugins to work, but it's not exposed to developers.

The new "handler" class (which this proposal calls StrategyHandler) will expose these methods so custom strategies can call fetch() or cacheMatch() and have any plugins that were added to the strategy instance automatically invoked.

This class would also make it possible for developers to add their own custom, lifecycle callbacks that might be specific to their strategies, and they would "just work" with the existing plugin interface.

New plugin lifecycle state

In Workbox v5, plugins are stateless. That means if a request for /index.html triggers both the requestWillFetch and cachedResponseWillBeUsed callbacks, those two callbacks have no way of communicating with each other or even knowing that they were triggered by the same request.

In this proposal, all plugin callbacks will also be passed a new state object. This state object will be unique to this particular plugin object and this particular strategy invocation (i.e. the call to handle()).

This allows developers to write plugins where one callback can conditionally do something based on what another callback in the same plugin did (e.g. compute the time delta between running requestWillFetch and fetchDidSucceed or fetchDidFail).

New plugin lifecycle callbacks

In order to fully leverage the plugin lifecycle state (mentioned above), you need to know when the lifecycle of a given strategy invocation starts and finishes.

To address this need (and others), the following new plugin lifecycle callbacks will be added:

handlerWillStart: called before any handler logic starts running. This callback can be used to set the initial handler state (e.g. record the start time).
handlerWillRespond: called before the strategies handle() method returns a response. This callback can be used to modify that response before returning it to a route handler or other custom logic.
handlerDidRespond: called after the strategy's handle() method returns a response. This callback can be used to record any final response details, e.g. after changes made by other plugins.
handlerDidComplete: called after all extend lifetime promises added to the event from the invocation of this strategy have settled. This callback can be used to report on any data that needs to wait until the handler is done in order to calculate (e.g. cache hit status, cache latency, network latency).
handlerDidError: called if the handler was unable to provide a valid response from any source. This callback can be used to provide "fallback" content as an alternative to a network error.

Developers implementing their own custom strategies do not have to worry about invoking these callbacks themselves; that's all handled by a new Strategy base class.

More accurate TypeScript types for handlers

TypeScript definitions for various callback methods have been normalized. This should lead to a better experience for developers who use TypeScript and write their own code to implement or call handlers.

See #2548.

workbox-recipes

This release includes a new module, workbox-recipes, that combines common routing and caching strategy configurations into ready-to-use code that can be dropped in to your service worker.

You can read more about what's included in the first batch of recipes, as well as how to use them, in #2664.

workbox-window improvements

New messageSkipWaiting() method

A new method, messageSkipWaiting(), has been added to the workbox-window module to simplify the process of telling the "waiting" service worker to activate.

This offers some improvements over alternatives:

It calls postMessage() with the de facto standard message body, {type: 'SKIP_WAITING'}, that a service worker generated by Workbox checks for to trigger skipWaiting().
It chooses the correct "waiting" service worker to post this message to, even if it's not the same service worker that workbox-window was registered with.

See #2394.

Removal of "external" events in favor of an isExternal property

Many developers were confused by the concept of "external" events in workbox-window, and in practice, they did not end up being a net-positive.

All "external" events are now represented as "normal" events with an isExternal property set to true. This allows developers who care about the distinction to still detect it, and developers who don't need to know can ignore the property.

See #2031.

Cleaner "Offer a page reload for users" recipe

Taken together, these two changes make the "Offer a page reload for users" recipe cleaner:

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

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

  const showSkipWaitingPrompt = () => {
    // This assumes a hypothetical createUIPrompt() method with
    // onAccept and onReject callbacks:
    const prompt = createUIPrompt({
      onAccept: () => {
        wb.addEventListener('controlling', () => {
          window.location.reload();
        });

        // This will postMessage() to the waiting service worker.
        wb.messageSkipWaiting();
      },

      onReject: () => {
        prompt.dismiss();
      }
    });
  };

  // Listening for externalwaiting is no longer needed.
  wb.addEventListener('waiting', showSkipWaitingPrompt);
  wb.register();
}
</script>

sameOrigin parameter in matchCallback functions

A new boolean parameter, sameOrigin, is passed to the matchCallback function used in workbox-routing. It's set to true if the request is for a same-origin URL, and false otherwise.

This simplifies some common boilerplate:

// In v5:
registerRoute(
  ({url}) => url.origin === self.location.origin &&
             url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'}),
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin &&
                         url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'}),
);

See #2487.

matchOptions are supported in workbox-expiration

You can now set matchOptions in workbox-expiration, which will then be passed through as the CacheQueryOptions to the underlying cache.delete() call. (Most developers won't need to do this.)

See #2206.

Precaching now processes entries one by one, not in bulk

workbox-precaching has been updated so that only one entry in the precache manifest is requested and cached at a time, instead of attempting to request and cache all of them at once (leaving it to the browser to figure out how to throttle).

This should reduce the likelihood of net::ERR_INSUFFICIENT_RESOURCES errors while precaching, and also should reduce the bandwidth contention between precaching and simultaneous requests made by the web app.

See #2528.

PrecacheFallbackPlugin allows for easier offline fallback

workbox-precaching now includes a PrecacheFallbackPlugin, which implements the new handlerDidError lifecycle method added in v6.

This makes it easy to specify a precached URL as a "fallback" for a given strategy when a response otherwise wouldn't be available. The plugin will take care of properly constructing the correct cache key for the precached URL, including any revision parameter that's needed.

Here's a sample of using it to respond with a precached /offline.html when the NetworkOnly strategy can't generate a response for a navigation request—in other words, displaying a custom offline HTML page:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  }),
);

precacheFallback in runtime caching

If you're using generateSW to create a service worker for you instead of writing your service worker by hand, you can use the new precacheFallback configuration option in runtimeCaching to accomplish the same thing:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

Under-the-hood workbox-precaching improvements

This release includes a substantial rewrite to the implementation of workbox-precaching, to build on top of other standard Workbox idioms (like Routes, Strategy subclasses, and custom plugins) as much as possible. There are a few breaking changes, described in the follow section, but they are mostly limited to uncommon use cases, when PrecacheController is instantiated directly. For the most part, these changes are meant to be invisible to developers, but should lead to be better consistency in how routing and request handling works across all of Workbox.

You can read more about what's change in #2638

cacheKeyWillBeUsed can be used to cache non-GET requests

Only GET requests can be used as cache keys, but there are scenarios in which you might want to use a combination of plugins to transform a POST or PUT request into a cacheable GET request.

You can now use the cacheKeyWillBeUsed lifecycle callback in a plugin to return a GET request with whatever URL you'd like to use as a cache key, and that can then allow the response associated with a POST or PUT to be cached.

See #2615 for more details. Thanks to @markbrocato for their contribution.

⚠️ Breaking Changes

Build Tools

The minimum required version of node has been increased to v10.0.0. This applies to workbox-build, workbox-cli, and workbox-webpack-plugin. [#2462]
mode was not intended to be a supported parameter for the injectManifest and getManifest modes of workbox-build and workbox-cli. It's been removed from the documentation and attempting to use it outside of generateSW will now trigger a build error. This does not apply to workbox-webpack-plugin, which does support mode in its InjectManifest plugin. [#2464]

workbox-core

The skipWaiting() method in workbox-core wrapped the underlying call to self.skipWaiting() in an install handler. In practice, this caused undue confusion and offered little value, as it's valid to call self.skipWaiting() outside of an install event. As of v6, Workbox's skipWaiting() will no longer add in an install handler, and is equivalent to just calling self.skipWaiting(). Because of this, developers should migrate to calling self.skipWaiting() directly, and Workbox's skipWaiting() will likely be removed in v7. [#2547]

workbox-precaching

While this scenario is uncommon, if you precache a URL that corresponds to an HTTP redirect to an HTML document on a different origin, that cross-origin HTML document can no longer be used to satisfy a navigation request. [#2484]
By default, the fbclid URL query parameter is now ignored when looking up a precached response for a given request. [#2532]

Note: The following changes primarily apply to direct usage of the PrecacheController class. Most developers don't use PrecacheController directly, and instead use static helper methods like precacheAndRoute() exported by workbox-precaching. [#2639]

The PrecacheController constructor now takes in an object with specific properties as its parameter, instead of a string. This object supports the following properties: cacheName (serving the same purpose as the string that was passed in to the constructor in v5), plugins (replacing the addPlugins() method from v5), and fallbackToNetwork (replacing the similar option that was passed to createHandler() and `createHandlerBoundToURL() in v5).
The install() and activate() methods of PrecacheController now take exactly one parameter, which should be set to a corresponding InstallEvent or ActivateEvent, respectively.
The addRoute() method has been removed from PrecacheController. In its place, the new PrecacheRoute class can be used to create a route that you can then register.
The precacheAndRoute() method has been removed from PrecacheController. (It still exists as a static helper method exported by the workbox-precaching module.) It was removed because PrecacheRoute can be used instead.
The createMatchCalback() method has been removed from PrecacheController. The new PrecacheRoute can be used instead.
The createHandler() method has been removed from PrecacheController. The strategy property of the PrecacheController object can be used to handle requests instead.
The createHandler() static export has already been removed from the workbox-precaching module. In its place, developers should construct a PrecacheController instance and use its strategy property.
The route registered with precacheAndRoute() is now a "real" route that uses workbox-routing's Router class under the hood. This may lead to a different evaluation order of your routes if you interleave calls to registerRoute() and precacheAndRoute(). See #1857 and #2402 for more details.

workbox-routing

The setDefaultHandler() method now takes an optional second parameter corresponding to the HTTP method that it applies to, defaulting to 'GET'. It no longer applies to requests with any HTTP method. If you were using setDefaultHandler() and all of your web app's requests are 'GET', then no changes need to be made. [#2463]

workbox-webpack-plugin

The minimum required version of webpack has been increased to v4.40.0 (for users remaining on the webpack v4.x major release) or v5.9.0 (for users who have updated to the webpack v5.x major release). [#2641]

`v5.1.4`: Workbox v5.1.4

Compare Source

The v5.1.4 release contains a dependency update for rollup-plugin-terser, resolving a security error with one of its dependencies.

See https://github.com/GoogleChrome/workbox/issues/2601

`v5.1.3`: Workbox v5.1.3

Compare Source

🐛 What's Fixed?

`workbox-build`

Correct workbox-build's getManifest() JSDoc [#2429]

`workbox-cli`

Don't check swSrc for hardcoded injection point in wizard flow [#2451]

`workbox-core`

handlerCallback JSDocs update [#2440]

`workbox-precaching`

Remove the isSWEnv assertion [#2453]
Update message to remove duplicate is [#2466]

Thanks!

Special thanks to @akonchady for contributing a PR that went in to this release.

`v5.1.2`: Workbox v5.1.2

Compare Source

🐛 What's Fixed?

`workbox-build`

Reverted the strip-comments dependency to an earlier revision, to provide continued compatibility with the v8.x.y releases of node. [#2416]

Thanks!

Special thanks to @Mister-Hope for raising issues that were resolved in this release.

`v5.1.1`: Workbox v5.1.1

Compare Source

(We ran into some issues with the v5.1.0 release process, so v5.1.1 is a republish of the same code.)

🎉 What's New?

`workbox-routing`

Adjusted the debug logging code so that a URL's hash portion is displayed. [#2371]

`workbox-webpack-plugin`

A new compileSrc option (defaulting to true) has been added. If set to false, then webpack will not run the swSrc file through a compilation. This can be useful if you want your swDest output to be, e.g., a JSON file which contains your precache manifest. [#2412]

🐛 What's Fixed?

`workbox-webpack-plugin`

Switch to official package exports when using internal webpack modules. [#2397]
webpackCompilationPlugins that customize the swSrc compilation should now be properly applied. [#2400]

Thanks!

Special thanks to @aritsune, @bailnl, @novaknole and @pizzafox for raising issues that were resolved in this release.

`v5.1.0`

Compare Source

`v5.0.0`: Workbox v5.0.0

Compare Source

Overview of Workbox v5

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

If you're already using Workbox, the best place to get up to speed is the guide to migrating from v4 to v5.

One example migration, with commentary, can be found in this GitHub commit.

🎉 What's New?

A shift towards local Workbox bundles & away from the CDN

While our immediate plan is to continue publishing copies of the Workbox runtime code to our CDN, in v5, the generateSW mode of our build tools will create a local bundle of exactly the Workbox runtime methods you end up using in your service worker. Depending on the value of inlineWorkboxRuntime, this bundle will either be imported from a separate file, or inlined directly in your top-level service worker.

Under the hood, we use Rollup to create this optimized bundle, optionally minifying it and generating sourcemaps, depending on the configuration.

See #2064 for more details.

If you're using the workbox-webpack-plugin's InjectManifest mode, the service worker file you specify via swSrc will end up being run through a webpack compilation process, optionally applying any compilation plugins configured via the webpackPlugins parameter. This should simplify the development flow described in the Using Bundlers (webpack/Rollup) with Workbox guide.

See #1513 for more details.

You can continue using importScripts('http://storage.googleapis.com/workbox-cdn/releases/5.0.0/workbox-sw.js') and relying on workbox-sw to dynamically pull in the Workbox runtime code that you need in v5, but we expect that using a custom bundle will lead to smaller runtime payloads (as well as work around issues with asynchronous imports), and we encourage developers to consider switching off of the CDN.

Changes to the webpack precache manifest

Before v5, workbox-webpack-plugin would generate a list of entries to precache based on two distinct sources: the set of assets in a webpack compilation, along with an optional additional set of files matched via glob patterns. Most webpack developers did not use the glob-related options (since the webpack compilation would normally include all the assets that they cared about), but at the same time, some helpful configuration options for manipulating or post-processing the precache manifest only applied to entries created via those glob patterns.

In v5, the glob-related configuration options are no longer supported. The webpack asset pipeline is the source of all the automatically created manifest entries. (Developers who have files that exist outside of the webpack asset pipeline are encouraged to use, e.g., copy-webpack-plugin to get those files into the webpack compilation.)

Beyond that, options for post-processing the precache manifest can now be used to manipulate entries that originate from the webpack asset pipeline. manifestTransforms, in particular, can be used to make arbitrary changes to any aspect of the precache manifest, including adding entries, deleting them, and changing their revision or url fields as needed. The current webpack compilation will be passed in to the callback function in case you need information from there to determine how to manipulate entries.

Here's an example of using manifestTransforms to perform extensive post-processing of a precache manifest:

const manifestTransform = (originalManifest, compilation) => {
  // If anything needs to be propagated to webpack's list
  // of compilaiton warnings, add the message here:
  const warnings = [];

  const manifest = originalManifest.map((entry) => {
    // entry has size, revision, and url fields.

    // Add a CDN prefix to certain URLs.
    // (alternatively, use modifyURLPrefix)
    if (entry.url.endsWith('.jpg')) {
      entry.url = `https://examplecdn.com/${entry.url}`;
    }

    // Remove revision when there's a match for your hashed URL pattern.
    // (alternatively, just set dontCacheBustURLsMatching)
    if (entry.url.match(/\.[0-9a-f]{6}\./)) {
      delete entry.revision;
    }

    // Exclude assets greater than 1MB, unless they're JPEGs.
    // (alternatively, use maximumFileSizeToCacheInBytes)
    if ((entry.size > 1024 * 1024) && !entry.url.endsWith('.jpg')) {
      warnings.push(`${entry.url} will not be precached because it is too big.`);
      return null;
    }

    return entry;
  }).filter(Boolean); // Exclude any null entries.

  // When manually adding in additional entries, make sure you use a URL
  // that already includes versioning info, like the v1.0.0 below:
  manifest.push({
    url: 'https://examplecdn.com/third-party-code/v1.0.0/index.js',
  });

  return {manifest, warnings};
};

Helpers that implement common manifest transformations, like maximumFileSizeToCacheInBytes, dontCacheBustURLsMatching and modifyURLPrefix, are also supported for webpack assets.

See #1591 and #1854.

Additionally, in v5, the precache manifest is inlined into the top-level service worker file, and not stored in a separate, external JavaScript file.

Simplified injectManifest placeholder replacement

Prior to v5, manifest injection worked by using a regular expression to find the correct location in the source service worker file to replace with the array of manifest entries. This could be brittle, and it was hard to customize, since the replacement step assumed you were using a RegExp that had capture groups.

This is simplified in v5, and using the injectManifest mode just checks for a placeholder variable and performs the equivalent of string replacement to inject the full manifest in its place. This variable is self.__WB_MANIFEST by default.

Your swSrc file in v4 might have looked like precacheAndRoute([]);

In v5, you should change this to precacheAndRoute(self.__WB_MANIFEST);

self.__WB_MANIFEST was chosen as the default replacement because self should always be defined in the service worker global scope, and it is unlikely to conflict with any user-created variables. If you need a different replacement, it can be configured via the injectionPoint option.

See #2059 for more details.

TypeScript support

All browser-based Workbox packages are now written in TypeScript and type definitions have been published to npm. TypeScript users (as well as users with TypeScript-aware code editors) can now get type checking for all browser-exposed Workbox APIs. (There are no TypeScript definitions for the various Workbox build tools at this time.)

To get type definitions for any Workbox APIs, you can import the package as described in our guide on Using Bundlers (webpack/Rollup) with Workbox. For example:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {Plugin as ExpirationPlugin} from 'workbox-expiration';

registerRoute(
  /\.(?:png|gif|jpg|jpeg|svg)$/,
  new CacheFirst({
    cacheName: 'images',
    plugins: [
      new ExpirationPlugin({
        maxEntries: 60,
        maxAgeSeconds: 30 * 24 * 60 * 60, // 30 Days
      }),
    ],
  }),
);

Note, we've historically published our Workbox source modules with the .mjs extension as a way to disambiguate them from classic scripts and the examples in our documentation that reference file paths always use .mjs.

However, since TypeScript does not currently support importing .mjs files we publish both .js and .mjs files to npm. TypeScript users wanting to import an individual module should be able to reference it by omitting the extension (which will then default to the .js file).

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {Plugin as ExpirationPlugin} from 'workbox-expiration';

If you encounter any problems with the type definitions or importing the source files via TypeScript, please let us know by opening an issue on GitHub.

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 to 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 use 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 long-lived, single-page apps.

Navigation route changes

Two options that were previously supported for navigation routes, blacklist and whitelist have been renamed denylist and allowlist.

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

Detected whether or not a given fetch event had a mode of 'navigate'.
If so, responded to that request using the contents of a previously cached, hardcoded URL, regardless of the 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 see as the responsibilities of workbox-routing. Instead, we see it as functionality that should be part of workbox-precaching, via a new method, createHandlerBoundToURL(). This new method can work hand-in-hand with the existing NavigationRoute class in workbox-routing to accomplish the same logic.

If you're using the navigateFallback option in one of the build tool's "generate SW" mode, then the switchover will happen automatically. If you previously configured either the navigateFallbackBlacklist or navigateFallbackWhitelist options, please change those to navigateFallbackDenylist or navigateFallbackAllowlist, respectively.

If you're using "inject manifest" mode or just writing the service worker yourself, and your Workbox v4 service worker calls registerNavigationRoute() directly, then you'll have to make a change to your code to get the equivalent behavior.

// v4:
import {getCacheKeyForURL} from 'workbox-precaching';
import {registerNavigationRoute} from 'workbox-routing';

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

// v5:
import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [...],
  denylist: [...],
});
registerRoute(navigationRoute);

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

workbox-broadcast-update

A generatePayload() configuration option has been added to the BroadcastCacheUpdate and BroadcastUpdatePlugin classes that allows developers to customize the message that gets sent to the window when a cached response has been updated.

The generatePayload() function is called with the same arguments as the cacheDidUpdate() plugin callback, and its return value will be used as the message payload. Here's an example that adds the Last-Modified header value of the updated response to the payload:

new BroadcastUpdatePlugin({
  generatePayload({request, newResponse}) {
    return {
      url: request.url,
      lastModified: newResponse.headers.get('Last-Modified'),
    };
  },
});

New copyResponse method

A copyResponse() method has been added that can be used to clone a response and modify its headers, status, or statusText. [#2193]

Here's an example that adds a custom header to indicate that a response came from the cache (and not the network):

const newResponse = copyResponse(oldResponse, (responseInit) => {
  responseInit.headers.set('X-Cache', 'hit');
  return responseInit;
});

Changes to the precaching network requests

If workbox-precaching needs to bypass the HTTP cache when requesting a URL, it will now set cache: 'reload' on the outgoing Request, which in turns sets the appropriate Cache-Control headers. [#2176]

Previously, bypassing the HTTP cache was done by adding in a __WB_REVISION=... URL query parameter to the outgoing network request, meaning that backend web servers would see requests for URLs containing those query parameters. With this change in place, requests for URLs with __WB_REVISION=... should no longer be seen in HTTP server logs.

Please note that this change only applies to outgoing HTTP requests used to populate the precache, and does not apply to cache keys. The keys for some entries created by workbox-precaching still include the __WB_REVISION=... parameter, and it's still a best practice to call getCacheKeyForURL() to determine the actual cache key, including the __WB_REVISION parameter, if you need to access precached entries using the Cache Storage API directly.

Control over development logging

A new __WB_DISABLE_DEV_LOGS global has been added. Set it to false to disable all logging in development mode. [#2284]

New helper methods to read precached responses

Two new methods (matchPrecache() and createHandler()) have been added to make it easier to manually access precached assets. [#2254]

All build tools

Any manifestTransform callbacks are now treated as being async, and each callback will be await-ed by the build tools. If you supply multiple transforms, they will still be run sequentially, in the same order. [#2195]

This should not be a breaking change, as you can continue providing non-async callback functions, and they will still work as before.

workbox-build and workbox-cli

As part of a general refactoring of how the options passed to all of our build tools are parsed [#2191], using precaching in the generateSW mode of workbox-build and workbox-cli is no longer mandatory. You can now use the runtimeCaching options without configuring the glob-related options, and your generated service worker will just contain the corresponding runtime caching routes.

If you don't configure the glob-related options and you don't use runtimeCaching, that will lead to a build error.

⚠️ Breaking Changes

All Build Tools

A number of workbox-build, workbox-cli, and workbox-webpack-plugin configuration parameters are no longer supported, following the general outlines of the changes described above. For instance, generateSW will always create a local Workbox runtime bundle for you, so the importWorkboxFrom option no longer makes sense. Please consult the relevant tool's documentation for the list of supported options.
navigationRouteWhitelist has been renamed navigationRouteAllowlist, and navigationRouteBlacklist has been renamed navigationRouteDenylist. The functionality is otherwise identical.

All Plugin classes

All Plugin classes have been renamed to be package-specific, e.g. ExpirationPlugin, CacheableResponsePlugin, etc. If you're using one of the Workbox build tools in generateSW mode to create your service worker, this change will be handled for you automatically. If you use one of the plugins in a manually created service worker, you'll need to explicitly change instances of Plugin to the correct revised class name. [#2187]

workbox-broadcast-update

The workbox-broadcast-update package no longer uses BroadcastChannel, even in cases when the browser supports it. Instead it uses postMessage() to message window clients. [#2184]

This change was made because postMessage() messages are automatically buffered by the window to handle cases where the service worker sends a message before the code running on the window is ready to receive it. BroadcastChannel has no such buffering, and thus you're more likely to miss message when using it.

If you're currently listening for BroadcastChannel messages in your code running on the window, you'll now need to listen for message events on the ServiceWorkerContainer:

navigator.serviceWorker.addEventListener('message', (event) => {
  console.log(event.data);
})

Note: workbox-window users should not need to make any changes, as its internal logic has been updated to listen for postMessage() calls.

workbox-build

The generateSWString mode has been removed. We expect the impact of this to be minimal, as it was primarily used internally by workbox-webpack-plugin.
The minimum required version of node has been increased to v8.0.0. This also applies to build tools that use workbox-build, like workbox-cli and workbox-webpack-plugin.

workbox-routing

See the earlier "Navigation route changes" section.

workbox-strategies

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]

workbox-webpack-plugin

This plugin requires now requires webpack v4 or higher.

🐛 What's Fixed?

All build tools

If the swSrc file has an associated sourcemap, we now update that to account for the injected manifest. [#2239]

workbox-broadcast-update

Added a check to wait for the resulting client to load on navigation requests before broadcasting any update messages. [#2210]

workbox-precaching

Fixed a bug where the result of the cacheWillUpdate() plugin callback was not being await-ed. [#2287]

workbox-routing

Pass matchCallback string/number return values through to handlerCallback. [#2134]
Fixed a ReadableStream bug in development mode in Safari. [#2268]

workbox-webpack-plugin

When using multiple instances of workbox-webpack-plugin in the same compilation, assets created by those other instances will now be excluded from each others' precache manifest. [#2182]

workbox-window

Added the isUpdate property to the controlling event, which was documented but not actually implemented. [#2114]
The message event listener is now added earlier, inside of the constructor rather than the register() method. [#2211]

🙏 Thanks!

A sincere thank you to everyone who tested Workbox v5, and in particular to the following folks who filed bugs and made contributions to the code. (Apologies if we've missed anyone—it's been a long process!)

Code Contributions

Bug Reports

`v4.3.1`: Workbox v4.3.1

Compare Source

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

`v4.3.0`: Workbox v4.3.0

Compare Source

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

`v4.2.0`: Workbox v4.2.0

Compare Source

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

`v4.1.1`: Workbox v4.1.1

Compare Source

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

`v4.1.0`: Workbox v4.1.0

Compare Source

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

`v4.0.0`: Workbox v4.0.0

Compare Source

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

Update dependency workbox-webpack-plugin to v6

c36f1db

dev-mend-for-jackfan.us.kg bot added the security fix Security fix generated by Mend label Jan 14, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update dependency workbox-webpack-plugin to v6 #75

Update dependency workbox-webpack-plugin to v6 #75

dev-mend-for-jackfan.us.kg bot commented Jan 14, 2025

Update dependency workbox-webpack-plugin to v6 #75

Are you sure you want to change the base?

Update dependency workbox-webpack-plugin to v6 #75

Conversation

dev-mend-for-jackfan.us.kg bot commented Jan 14, 2025

Release Notes

v6.0.0: Workbox v6.0.0

Overview of Workbox v6

🎉 What's New?

webpack improvements

workbox-strategies improvements

New strategy base class

A new "handler" class

New plugin lifecycle state

New plugin lifecycle callbacks

More accurate TypeScript types for handlers

workbox-recipes

workbox-window improvements

New messageSkipWaiting() method

Removal of "external" events in favor of an isExternal property

Cleaner "Offer a page reload for users" recipe

sameOrigin parameter in matchCallback functions

matchOptions are supported in workbox-expiration

Precaching now processes entries one by one, not in bulk

PrecacheFallbackPlugin allows for easier offline fallback

precacheFallback in runtime caching

Under-the-hood workbox-precaching improvements

cacheKeyWillBeUsed can be used to cache non-GET requests

⚠️ Breaking Changes

Build Tools

workbox-core

workbox-precaching

workbox-routing

workbox-webpack-plugin

v5.1.4: Workbox v5.1.4

v5.1.3: Workbox v5.1.3

🐛 What's Fixed?

workbox-build

workbox-cli

workbox-core

workbox-precaching

Thanks!

v5.1.2: Workbox v5.1.2

🐛 What's Fixed?

workbox-build

Thanks!

v5.1.1: Workbox v5.1.1

🎉 What's New?

workbox-routing

workbox-webpack-plugin

🐛 What's Fixed?

workbox-webpack-plugin

Thanks!

v5.1.0

v5.0.0: Workbox v5.0.0

Overview of Workbox v5

🎉 What's New?

A shift towards local Workbox bundles & away from the CDN

Changes to the webpack precache manifest

Simplified injectManifest placeholder replacement

TypeScript support

additionalManifestEntries option in build tools

importScriptsViaChunks in workbox-webpack-plugin's GenerateSW mode

Support for subresource integrity metadata in precaching requests

update(), to force a service worker update check

Navigation route changes

workbox-broadcast-update

New copyResponse method

Changes to the precaching network requests

Control over development logging

New helper methods to read precached responses

All build tools

workbox-build and workbox-cli

⚠️ Breaking Changes

All Build Tools

All Plugin classes

workbox-broadcast-update

workbox-build

workbox-routing

workbox-strategies

`v6.0.0`: Workbox v6.0.0

`v5.1.4`: Workbox v5.1.4

`v5.1.3`: Workbox v5.1.3

`workbox-build`

`workbox-cli`

`workbox-core`

`workbox-precaching`

`v5.1.2`: Workbox v5.1.2

`workbox-build`

`v5.1.1`: Workbox v5.1.1

`workbox-routing`

`workbox-webpack-plugin`

`workbox-webpack-plugin`

`v5.1.0`

`v5.0.0`: Workbox v5.0.0

`v4.3.1`: Workbox v4.3.1

`workbox-broadcast-update`

`v4.3.0`: Workbox v4.3.0

`workbox-background-sync`

`workbox-background-sync`

`v4.2.0`: Workbox v4.2.0

`workbox-core`

`workbox-webpack-plugin`

`v4.1.1`: Workbox v4.1.1

`workbox-window`

`v4.1.0`: Workbox v4.1.0

`workbox-build`

`workbox-window`

`workbox-precaching`

`workbox-background-sync`

`workbox-broadcast-update`

`v4.0.0`: Workbox v4.0.0

`workbox-window`