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.

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

1. Detected whether or not a given fetch event had a mode of 'navigate'.
2. 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

• @azizhk
• @jaulz

Bug Reports

• @derekdowling
• @emillundstrm
• @lukas2005
• @kaykayehnn

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

Installation of the latest pre-release version

We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.

🎉 What's New?

Improvements to the JSDoc documentation for all of the build tools. [#2320]

⚠️ Breaking Changes

whitelist/blacklist (in the NavigationRoute class) and navigateFallbackWhitelist/navigateFallbackBlacklist (in the build tools) have been renamed to allowlist/denylist and navigateFallbackAllowlist/navigateFallbackDenylist. Functionality remains the same. [#2325]

🐛 What's Fixed?

workbox-build

• Consistently use absolute file paths in the return value of the injectManifest mode. [#2301]
• Set revision: null instead of deleting the revision property when the build tool determines that the revision isn't necessary. [#2326]

workbox-core

• No longer overwrites a __WB_DISABLE_DEV_LOGS value that's explicitly set by your service worker script. [#2296]

workbox-strategies

• The handle() method of each strategy now supports passing in a string URL as the request property, matching the behavior of the (now deprecated) makeRequest() method. [#2317]

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

Installation of the latest pre-release version

We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.

🎉 What's New?

All browser packages

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

workbox-precaching

• Calling precache()/precacheAndRoute() and passing in an precache manifest entry that is just a string has been deprecated. It will trigger a warning message in v5, and will be treated as a runtime error in a future release. If you need to use a hardcoded URL as a manifest entry, first ensure that it contains inline revision information, like a hash. Then, instead of passing in a string like '/app.1234abcd.js', use {url: '/app.1234abcd.js', revision: null} to explicitly state that the revision is meant to be null. [#2262]

🐛 What's Fixed?

workbox-routing

• Fixed a ReadableStream bug in development mode in Safari. [#2268]

workbox-precaching

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

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

Installation of the latest pre-release version

We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.

🎉 What's New?

TypeScript

• All public workbox types are now exported directly from workbox-core [#2255]
• All packages have switched to using "strict": true in their TypeScript config. [#2241, #2244, #2256 2246]

workbox-precaching

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

🐛 What's Fixed?

workbox-webpack-plugin

• Missing source map assets are is no longer treated as a fatal error. [#2251]

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

⚠️ Breaking Changes

workbox-precaching

• The createHandlerForURL() method has been renamed to createHandlerBoundToURL() to make its intended usage more clear. [#2254]

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

Installation of the latest pre-release version

We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.

🐛 What's Fixed?

TypeScript

• Various type annotations have been updated for accuracy. [#2200, #2208]

All build tools

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

workbox-build

• Fixed a bug that could lead to the output directory being prepended twice when writing the service worker to disk. [#2223]

• Make sure that all swSrc and swDest files are left out of the generated precache manifest. [#2232]

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

• Instead of adding the __WB_REVISION__ query parameter to outgoing network requests that should be cache-busted, explicitly set the cache mode to 'reload' if needed. When cache-busting is not needed, set cache to 'default'. [#2222]

workbox-range-requests

• Fixed a bug causing an invalid 206 Partial Content response to be used when the incoming request used Range: bytes=0-. [#2237]

workbox-webpack-plugin

• Fixed an edge case that could lead to build errors when other plugins generate assets. [#2219]

workbox-window

• The message event listener is now added earlier, inside of the constructor rather than the register() method. [#2211]

Thanks

Special thanks to @lukas2005 for their bug reports, and @azizhk for their contributions that went into this release!

🎉 What's New?

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

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

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'),
    };
  },
});

workbox-core

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;
});

workbox-precaching

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.

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

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.

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]

🐛 What's Fixed?

workbox-routing

• A RouteHandlerObject type has been added to fix TypeScript typing issue when using strategy classes as route handlers. [#2183]

workbox-webpack-plugin

• importScriptsViaChunks will only call importScripts() on assets in that chunk which have a .js extension. [#2164]
• The GenerateSW mode will now work properly when there are multiple compilations (via, e.g., webpack-dev-server). [#2167]
• The json-stable-stringify dependency has been replaced by fast-json-stable-stringify. [#2163]
• 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]

Thanks

Special thanks to @kaykayehnn for their bug reports and contributions that went into this release.

🎉 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

• Various fixes and enhancements to the initial set of TypeScript annotations. [#2118, #2119, #2120, #2121, #2156]

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.

🎉 What's New?

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

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/registerRoute';
import {CacheFirst} from 'workbox-strategies/CacheFirst';
import {Plugin as ExpirationPlugin} from 'workbox-expiration/Plugin';

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.

Note: The only browser-based Workbox package we haven't converted to TypeScript is workbox-sw, which we don't recommend using with bundlers. As mentioned in the v5.0.0-alpha.0 release notes, our build tools are shifting away from a dependence on a CDN. However, if there are strong use-cases for wanting type definitions for workbox-sw, please let us know, and we can re-evaluate.

🐛 What's Fixed?

Build Tools

• Fixed an incorrect assumption about the location of node_modules, which could lead to a failed generateSW build process. [#2110]
• Opt-out of auto-discovering a local Babel configuration file, and instead always use the default @babel/preset-env configuration during the generateSW build process. [@2113]

workbox-window

• Added the isUpdate property to the controlling event, which was documented but not actually implemented. [#2114 ]

Thanks

Special thanks to @kaykayehnn for their bug reports and contributions that went into this release.

Overview of Workbox v5

We're happy to announce the first alpha release of Workbox's v5! This release brings a number of significant changes to all of our build tools: workbox-build, workbox-cli, and workbox-webpack-plugin.

🎉 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-alpha.0/workbox-sw.js') and relying on workbox-sw to dynamically pull in the Workbox runtime code that you neeed 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 genereate 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-proceessing 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 entres. (Developers who have files that exist outside of the webpack asset pipeline are encouragede 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 peform extensive post-processing of a precache manifest:

const manifestTransform = (originalManifest, compilation) => {
  // If anything needs to be propogated 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 v4, 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 simplifiede 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 choosen 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.

⚠️ Breaking Changes

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.

We are working on updating the documentation to list the full set of supported options for each mode, but for this alpha, we encourage you to rely on the built-in option validation along with manual inspection of the validation logic if there is any uncertainty.

Thank you for your patience as we get everything documented.

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.

Installation of the latest pre-release version

We are using the next tag in npm for the current pre-release version. To install a given module use, e.g., npm install --save-dev workbox-webpack-plugin@next.

🐛 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 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 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)
);

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]

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.

The first beta release of Workbox v4 includes the following developer-visible changes from the previous alpha release.

🎉 What's New?

• [BREAKING CHANGE] The workbox.backgroundSync.Queue class has been updated to give developers much 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.

• [BREAKING CHANGE] 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.

• [BREAKING CHANGE] 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.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)

• Improved logging when using workbox.routing.NavigationRoute. When a URL matches the blacklist, there's now a message logged with higher priority when using the development builds. (#1741)

• When using workbox-precaching, the temporary cache is now cleaned up following service worker activation. (#1736)

🐛 What's Fixed?

This release fixes an issue (#1677) that several users have reported, triggered by precaching a URL that returns a 30x redirect to another URL. For instance, having '/index.html' listed in your precache manifest can trigger this issue, if your web server responds to requests for '/index.html' with a 301 redirect to the destination URL '/'. When the issue manifests itself, the final, redirect content ends up being served with an incorrect Content-Type: response header, which can in turn lead problems displaying that cached content.

If you do use 30x redirects for some of your URLs, we recommend updating to this latest release of Workbox.

In order to "clear out" the problematic content that was previously precached with an incorrect Content-Type, after updating Workbox, you can deploy a small change to URLs that you know are affected (i.e. make any change to your '/index.html' file, if that's being fulfilled with a 30x redirect).

It's also possible to force all previously cached entries to be precached again by changing the cacheId option in "generate SW" mode, or by including

workbox.core.setCacheNameDetails({precache: 'my-new-id'});

in your service worker source file in "inject manifest" mode.

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🎉 What's New?

Support for navigation preload

The new workbox-navigation-preload module provides a simple way of opting-in to navigation preload on browsers that support the feature. When run on browsers which lack navigation preload support, using the module will have no effect.

To take advantage of this new feature, you should make sure to set up a route that will match navigation requests, and uses a strategy that makes use of the response from the network, like networkFirst, staleWhileRevalidate, networkOnly, or cacheFirst.

// Enable navigation preloads.
workbox.navigationPreload.enable();

// Swap in networkOnly, cacheFirst, or staleWhileRevalidate as needed.
const strategy = workbox.strategies.networkFirst({
  cacheName: 'cached-navigations',
  plugins: [
    // Any plugins, like workbox.expiration, etc.
  ],
});

const navigationRoute = new workbox.routing.NavigationRoute(strategy, {
  // Optionally, provide a white/blacklist of RegExps to determine
  // which paths will match this route.
  // whitelist: [],
  // blacklist: [],
});

workbox.routing.registerRoute(navigationRoute);

Developers who are already handling navigations by responding with precached HTML (potentially configured with an App Shell fallback) do not need to enable navigation preload! This feature is intended to reduce navigation latency for developers who can't precache their HTML, but still want to use Workbox to handle caching of other assets on their sites.

workbox.strategies now supports using custom CacheQueryOptions

Developers who want to customize how workbox.strategies performs its internal cache lookups can now pass in a matchOptions parameter to use as the CacheQueryOptions when cache.match() is called under the hood.

// Ignore all query parameters when performing cache lookups.
const strategy = workbox.strategies.staleWhileRevalidate({
  cacheName: 'runtime-cache',
  matchOptions: {
    ignoreSearch: true,
  },
});

Many thanks to @torbs for contributing this in #1561!

🐛 What's Fixed?

• A fix for an issue that could prevent workbox.expiration.Plugin from working as intended in Microsoft Edge. Thanks to @josephliccini for contributing #1510!

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🐛 What's Fixed?

• Don't alias the exported workbox.core.registerQuotaExceededCallback symbol [#1553] (Thanks to @xe21500 and others for reporting)
• Properly set Cache-Control on CDN hosting [#1539]
• Link to workbox.setConfig() docs after calling workbox copyLibraries [#1553]

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🎉 What's New?

Cache maintenance improvements

Two new features are available to help developers deal with cache maintenance, and in particular, storage quota errors.

First, a new deleteCacheAndMetadata() method has been added to the workbox.expiration.Plugin class. This can be called manually, and it will delete all entries in the cache that the plugin is associated with, as well as clear out all metadata related to cache expiration for the plugin instance. While it's always been possible to explicitly call caches.delete(<cacheName>), that would not clear out any expiration metadata, and could lead to unexpected expiration behavior the next time the cache was recreated. (#1500)

Next, a new purgeOnQuotaError parameter can be passed in when configuring workbox.expiration.Plugin. It defaults to false, but if set to true, you can opt-in to clearing all entries in a given cache (via a call deleteCacheAndMetadata() made automatically) whenever a quota errors occurs anywhere in Workbox. This allows you to mark certain runtime caches as being "safe" for automatic cleanup, clearing up room for your web app's more critical cache storage usage. (#1505)

Opting-in to this behavior explicitly in your service worker looks like:

workbox.routing.registerRoute(
  new RegExp('/images/'), // Change to the routing criteria you need.
  workbox.strategies.cacheFirst({
    cacheName: 'images',
    plugins: [
      new workbox.expiration.Plugin({
        maxEntries: 10,
        purgeOnQuotaError: true, // Opt-in to automatic cleanup.
      }),
    ],
  })
);

When using generateSW in a build tool along with the runtimeCaching option, you can achieve something similar with the following configuration:

generateSW({
  // ...other options...
  runtimeCaching: [{
    urlPattern: new RegExp('/images/'),
    cacheName: 'images',
    handler: 'cacheFirst',
    options: {
      expiration: {
        maxEntries: 10,
        purgeOnQuotaError: true,
      },
    },
  }],
});

Automatic cache cleanup is still in its early phases, and we encourage developers who use runtime caching (especially of opaque resources, which can lead to high quota usage) to give the new functionality a try, and provide feedback.

The fetchDidFail lifecycle event is passed a new error parameter

Developers using the fetchDidFail lifecycle event to write plugins which respond to a failed network request now have access to the original underlying exception, via the error property of the callback's parameter. (#1486)

More information is available in our Custom Plugins guide.

gzip'ed CDN assets

Users of the CDN copies of the Workbox runtime libraries will now benefit from Content-Encoding: gzip support, leading to smaller initial downloads. (#1523)

🐛 What's Fixed?

• Explicitly check whether ReadableStream is functional, and trigger non-streamed fallback logic when it's not, to workaround an issue with the current Edge build and workbox-streams. (#1476)
• Improve the code that swaps 'prod' for 'dev' in copyWorkboxLibraries. The new replacement logic is more robust when your destination path includes the string 'prod'. (#1488)
• The workbox-webpack-plugin integration tests are now run against webpack v4, instead of v3. (webpack v3 still remains supported; this only affects the test suite.) (#1492)

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🎉 What's New?

A new workbox-streams module

The workbox-streams module provides an easy-to-use wrapper on top of the Streams API, allowing you to create a streaming response from a sequence of multiple sources.

The new module offers a convenience workbox.streams.strategy() method that can be used as a strategy in a workbox.routing configuration, allowing you to respond to matching requests with a stream:

const apiStrategy = workbox.strategies.staleWhileRevalidate();
const streamsStrategy = workbox.streams.strategy([
  () => caches.match('start.html'),
  () => `<p>Here's an API call, using a stale-while-revalidate strategy:</p>`,
  ({event}) => apiStrategy.makeRequest({
    event,
    request: '/api/date',
  }),
  () => caches.match('end.html'),
]);
workbox.routing.registerRoute(
  new RegExp('/index'),
  streamsStrategy
);

For more information and usage examples, please see the documentation and the live demo. (#1439)

Improved resiliency during unexpected cache misses

If a cache entry that would normally be used to fulfill a request is unexpectedly missing, workbox.routing.registerNavigationRoute() will now fall back to the network to obtain that response. Previously, this would lead to a failed navigation. (#1460)

precacheAndRoute() now accepts options in injectManifest mode

Previously, when using injectManifest mode with workbox-build or workbox-cli, the default regular expression would look for precacheAndRoute([]) inside of your swSrc file, and use that [] as the point at which to inject the manifest.

We've relaxed the default regular expression so that, in addition to supporting the previous usage, it will also work with precacheAndRoute([], {...}), where {...} are the options that you might want to pass in to configure precaching behavior. (#1459)

Changes to swSrc will trigger a new webpack dev server build

When using workbox-webpack-plugin's InjectManifest mode inside of a webpack dev server environment, making updates to the swSrc file will now trigger a fresh build. Thanks to @green-arrow for the contribution! (#1432)

🐛 What's Fixed?

• Resolved an issue with workbox.strategies.staleWhileRevalidate() and workbox.strategies.cacheFirst() in the Samsung Internet browser. (#1457)
• Moved to using the public compiler.inputFileSystem API when working with the webpack filesystem. Thanks to @DorianGrey for the contribution! (#1437)

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🎉 What's New?

workbox-webpack-plugin offers more control over paths and filenames

New precacheManifestFilename and importsDirectory options were added to the webpack plugins, giving developers more control over where their generated files are saved.

When importWorkboxFrom: 'local' and output.publicPath is configured, the output.publicPath value will be prepended to the modulePathPrefix used to determine where the Workbox libraries are dynamically loaded from. This amounts to a change in the previous behavior, but based on developer expectation, the previous behavior was considered a bug.

See #1403 for more details about the change, and the documentation for the complete list of configuration options.

New makeRequest() method added to classes under workbox.strategies

Most developers will use one of Workbox's strategies as part of a router configuration. This setup makes it easy to automatically respond to specific fetch events with a response obtained from the strategy.

However, there are situations where making a request using a strategy outside of the standard router setup could be useful. For instance, you might be implementing your own routing logic, or you might want to create a composite response that contains information from multiple smaller responses, stitched together. There are also situations where you'd normally call fetch() directly, but you'd like to take advantage of the plugin integration offered by a strategy class.

See #1408 for more details.

🐛 What's Fixed?

• Use waitUntil only when it's available (#1392) (Thanks to @beatrizdemiguelperez for reporting the underlying issue: #1386)
• Correctly identify when response does not have date header set (#1422) (Thanks to @matthewjmay for identifying the issue and contributing the fix!)
• Properly deal with null cachedResponses passed to Range plugin. (#1427)

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

🎉 What's New?

• Webpack now logs errors when using glob patterns that are probably not intended to be used (#1380)
• Webpack supports absolute swDest paths (#1370 )

🐛 What's Fixed?

• Plugins for workbox-precaching setup for install and activate events. (#1367)
• workbox-precaching had an intermittent issue where the temporary cache was dropping requests (#1368)

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/

Overview of Workbox V3

Workbox v3 has been focused on reducing the size of the library, while lowering the friction for usage. This has been accomplished thanks to a significant refactoring of the existing codebase. We believe the migration process for most users should be minimal, taking a few hours.

Developers are encouraged to view our documentation, including a migration guide for moving from either Workbox v2 or from sw-precache/sw-toolbox to Workbox v3.

Many thanks to @beatrizdemiguelperez, @raejin, @goldhand for contributing code for the v3 release, and to all the members of the community who tested and gave feedback during our alpha and beta periods.

🥅 High-level Goals for v3

Minimize the size of Workbox

The size of the Workbox libraries has been reduced. Instead of opting everyone in to a monolithic bundle, only code for the features you use will be imported at runtime.

Workbox has official CDN support

We provide a Google Cloud Storage-based CDN of the Workbox runtime libraries, making it easier to get up and running with Workbox.

Improved webpack Plugin

workbox-webpack-plugin integrates more closely with the webpack build process, allowing for a zero-config use case when you want to precache all the assets in the build pipeline.

Achieving these goals, and cleaning up some aspects of the previous interface that felt awkward or led to antipatterns, required introducing a number of breaking changes in the v3 release.

Better Debugging and Logs

The debugging and logging experience has been vastly improved. Debug logs are enabled by default whenever Workbox is used from a localhost origin and all logging and assertions are stripped from the production builds

🎉 New Functionality

workbox-build

• globFollow and globStrict added to workbox-build. This means symbolic links will be followed when searching for files and any errors discovered by glob will now throw. (#1104)

workbox-cli

• Support --injectManifest in the workbox-cli wizard. (#1171)

workbox-precaching

• workbox-precaching supports two new configuration options, cleanUrls and urlManipulation. By default cleanUrls is true and will append .html to a reqest when looking for a precache hit (i.e. /about will check for /about.html). urlManipulation can be a function enabling you to express a mapping between the server-side URL and the underlying local file. (#1154)

• If a precached request is not in the cache, we fallback to the network. (#1302)

• Precaching will store requests in a temporary cache on install and copy these requests to final cache during the activate step. (#1316)

• The precaching IndexedDB name is now derived from the cache name - allowing multiple precaches on a single origin. (#1346)

workbox-strategies

• Fallback to the network response whena network timeout is reached and there is no cache hitfor the network-first strategy. (#1301)
• Support for configuring fetch options in a strategy. (#1340)

workbox-webpack-plugin

• Adds support for webpack v4, while retaining support for webpack v3. (#1275)

• workbox-webpack-plugin now supports {test, include, exclude}-style filtering, providing an additional way of controlling which assets are included in the precache manifest. By default, assets matching /\.map$/ or /^manifest\.js(?:on)$/ are excluded. (#1149)

⚠️ Breaking Changes

Build Configuration

The following changes affect the behavior of all of our build tools (workbox-build, workbox-cli, workbox-webpack-plugin), which share a common set of configuration options.

• The 'fastest' handler name was previously valid, and treated as an alias for 'staleWhileRevalidate', when configuring runtimeCaching. It's no longer valid, and developers should switch to using 'staleWhileRevalidate' directly. (#915)

• Several runtimeCaching.options property names have been updated, and additional parameter validation is in place that will cause a build to fail if an invalid configuration is used. See the documentation for runtimeCaching for a list of currently supported options. (#1096)

• A new importWorkboxFrom option can be used to determine where the Workbox libraries are read from: the CDN, locally, or from a custom bundle (when using webpack).

workbox-background-sync

• There are significant changes to the API surface in v3. Developers should consult the documentation for current guidance. (#868)

• The maxRetentionTime configuration option is now interpreted as a number of minutes, rather than milliseconds. (#1268)

• The tag name is now used when responding to a sync event. (#1280)

workbox-build

• The default destination of a service worker for the CLI has changed from 'build/' to the location of the globDirectory (i.e. the directory searched for files to precache). (#1105)

• The getFileManifestEntries() function has been renamed to getManifest(), and the promise returned now includes additional information about the URLs which are precached.

• The generateFileManifest() function has been removed. Developers are encouraged to call getManifest() instead, and use its response to write data to disk in the appropriate format.

workbox-cache-expiration

• The plugin API has stayed the same, however there are significant API changes impacting developers who use it as a standalone class. Consult the documentation for the updated API surface. (#920)

• workbox-cache-expiration now throws an error if you attempt to expire entries on the default runtime cache (i.e. the shared cache used by all strategies by default). (#1079)

workbox-cli

• The set of command line options, and the way of reading in stored configuration, have all changed. Developers should consult the documentation or run the CLI with the --help flag for guidance. (#865)

• Support for the workbox-cli alias for the binary script has been removed. The binary can now only be accessed as workbox. (#730)

workbox-google-analytics

• While the API surface has not changed, the underlying implementation was updated to use the workbox-background-sync library, and therefore rely on the Background Sync API. (#244)

workbox-precaching

• The precache() method previously performed both the cache modifications and set up routing to serve cached entries. Now, precache() only modifies cache entries, and a new method, addRoute(), has been exposed to register a route to serve those cached responses. Developers who want the previous, two-in-one functionality can switch to calling precacheAndRoute(). This enables more developer flexibility. (#886).

• workbox-broadcast-update will no longer be automatically configured to announce cache updates for precached assets. To get this behavior, you can add the plugin manually. (#1073)

workbox-routing

• The Router will now evaluate Routes in a first-registered-wins order. This is the opposite order of Route evaluation that was used in v2, where the last-registered Route would be given precedence. (#845)

• The ExpressRoute class, and support for "Express-style" wildcards have been removed. This reduces the size of workbox-routing considerably. Strings used as the first parameter to workbox.routing.registerRoute() will now be treated as exact matches. Wildcard or partial matches should be handled by RegExps—using any RegExp that matches against part or all of the request URL can trigger a route. (#1012)

• The addFetchListener() helper method of the Router class has been removed. Developers can either add their own fetch handler explicitly, or use the interface provided by workbox.routing, which will implicitly create a fetch handler for them. (#914)

• The registerRoutes() and unregisterRoutes() methods were removed. The versions of those methods that operate on a single Route were not changed, and developers who need to register or unregister multiple routes at once should make a series of calls to registerRoute() or unregisterRoute() instead. (#856)

workbox-strategies (formerly know as workbox-runtime-caching)

• The workbox-runtime-caching module is now officially known as workbox-strategies, and has been published on npm under its new name. (#1045)

• The syntax for specifying plugins when configuring a strategy has changed. Each plugin needs to be explicitly listed in the plugins property of the strategy's configuration. (#1071)

• Defining a strategy that applies to the default cache name and which uses cache expiration is no longer supported. When configuring cache expiration, you must also configure a specific cache name. (#1014)

• The cacheWillMatch lifecycle method has been renamed to cachedResponseWillBeUsed. This should not be a visible change for developers unless they wrote their own plugins that reacted tocacheWillMatch. (#713)

workbox-sw

• The handleFetch option has been removed. (#1002)

• skipWaiting and clientsClaim are no longer options passed to the WorkboxSW constructor. Instead, they have been changed to methods of the same name that could be called on the workbox namespace. (#853)

workbox-webpack-plugin

• The plugin has been substantially rewritten, and in many cases, can be used in a "zero-configuration" mode. Consult the documentation for the updated API surface. (#696)

🎉 What's New?

• Attempting to cache a POST request will no throw a useful WorkboxError (#1336)
• Adding support to configure fetch options in a Strategy (#1340)

🐛 What's Fixed?

• Fixes BroadcastChannel on Safari Tech Preview where it's not supported. (#1304)
• Fixes broadcastUpdate in workbox-build config (#1334)
• Precaching to a temp cache in install and moving to final cache during activate step (#1316)
• Precaching cache name is now defined from the cache name - allowing multiple precaching (#1346)

📖 Learn More

Check out our docs @ developers.google.com/web/tools/workbox/next/

What's new?

The 2.1.3 release contains a few changes to the workbox-background-sync and workbox-broadcast-cache-update modules to ensure that they will not attempt to use the Broadcast Channel API on a browsers that lacks support for it.

Safari is one such browser.

Notable PRs

• Gracefully no-op when BroadcastChannel doesn't exist (#1291)

The first beta release of Workbox v3 includes additional integration tests and demos, as well as the following developer-visible changes from the previous alpha release.

🎉 What's New?

• [BREAKING CHANGE] The background sync module's maxRetentionTime setting is now interpreted as a number of minutes, rather than milliseconds (#1268)

🐛 What's Fixed?

• Honor publicPath when determining the precache manifest URL. (#1233)
• Show the --help message when there are no params passed to workbox-cli. (#1242)
• Tweak wording for root of web app question. (#1243)
• Refactor the way CLI parameters are processed by workbox-cli. (#1246)
• Ignore .map when suggesting extensions to precache in the workbox-cli wizard. (#1255)
• Make workbox sw chunk prefix with public path (#1265) (Thanks to @raejin for their contribution!)

The latest alpha release of Workbox includes some project health improvements, as well as the following developer-visible changes from the previous alpha release.

🎉 What's New?

• #1171 Support --injectManifest in the workbox-cli wizard.

🐛 What's Fixed?

• #1173 Properly deal with webpack's publicPath + importWorkboxFrom: 'local'
• #1181 Don't copy the same workbox-sw.js(.map) files twice
• #1203 Tweak async/await usage to avoid a bug in the final prod bundle.
• #1184 Switching to a db name instead of just a store name
• #1216 Call new on the corresponding Plugin class.

🎉 What's New?

• #1138 Plugins can now be added to workbox-precaching; this is useful for adding plugins like workbox-broadcast-cache-update.
• #1149 workbox-webpack-plugin now supports {test, include, exclude}-style filtering, providing an additional way of controlling which assets are included in the precache manifest. By default, assets matching /\.map$/ or /^manifest\.js(?:on)$/ are excluded.
• #1154 workbox-precaching supports two new configuration options, cleanUrls and urlManipulation. By default cleanUrls is true and will check the precache for a with .html on the end (i.e. /about will check for /about.html. urlManipulation can be a function enabling you to express a mapping between the server-side URL and the underlying local file.

🐛 What's Fixed?

• #1130 A cleaner service worker template.
• #1127, #1128, #1126, #1133, #1132 Various improvements to the test suite.
• #1139 Fix for an IDB bug, which could prevent v2 to v3 migrations from succeeding.
• #1155 Fix for a bug that could cause workbox-background-sync to enter a loop of repeated registrations.
• #1168 A fix for broken expiration.

⚠️ Breaking Changes

• #1137 The importWorkboxFromCDN boolean option, which was supported in previous v3 alpha releases of workbox-build, has been replaced by importWorkboxFrom. Valid values for importWorkboxFrom are 'cdn', 'local', null, or (when used from the workbox-webpack-plugin) the name of a webpack chunk.
• #1143 The workbox-webpack-plugin module now exposes two top-level webpack plugins, named GenerateSW and InjectManifest. Developers need to explicitly use one of these two plugins, depending on whether they want to create a new service worker file each time they run their build (GenerateSW) or whether they want to use an existing service worker file but inject updated precache manifest information each time they build (InjectManifest).
• #1160 The valid runtimeCaching options have been updated, representing a break from the older syntax supported by sw-precache. The following example contains the full set of currently supported options:

runtimeCaching: [{
  urlPattern: /api/,
  handler: 'networkFirst',
  options: {
    networkTimeoutSeconds: 10,
    cacheName: 'my-api-cache',
    expiration: {
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
    cacheableResponse: {
      statuses: [0, 200],
      headers: {'x-test': 'true'},
    },
    broadcastUpdate: {
      channelName: 'my-update-channel',
    },
    plugins: [
      {cacheDidUpdate: () => /* custom plugin code */}
    ],
  },
}]

🎉 What's New?

• #1138 Plugins can now be added to workbox-precaching; this is useful for adding plugins like workbox-broadcast-cache-update.
• #1149 workbox-webpack-plugin now supports {test, include, exclude}-style filtering, providing an additional way of controlling which assets are included in the precache manifest. By default, assets matching /\.map$/ or /^manifest\.js(?:on)$/ are excluded.
• #1154 workbox-precaching supports two new configuration options, cleanUrls and urlManipulation. By default cleanUrls is true and will check the precache for a with .html on the end (i.e. /about will check for /about.html. urlManipulation can be a function enabling you to express a mapping between the server-side URL and the underlying local file.

🐛 What's Fixed?

• #1130 A cleaner service worker template.
• #1127, #1128, #1126, #1133, #1132 Various improvements to the test suite.
• #1139 Fix for an IDB bug, which could prevent v2 to v3 migrations from succeeding.
• #1155 Fix for a bug that could cause workbox-background-sync to enter a loop of repeated registrations.

⚠️ Breaking Changes

• #1137 The importWorkboxFromCDN boolean option, which was supported in previous v3 alpha releases of workbox-build, has been replaced by importWorkboxFrom. Valid values for importWorkboxFrom are 'cdn', 'local', null, or (when used from the workbox-webpack-plugin) the name of a webpack chunk.
• #1143 The workbox-webpack-plugin module now exposes two top-level webpack plugins, named GenerateSW and InjectManifest. Developers need to explicitly use one of these two plugins, depending on whether they want to create a new service worker file each time they run their build (GenerateSW) or whether they want to use an existing service worker file but inject updated precache manifest information each time they build (InjectManifest).
• #1160 The valid runtimeCaching options have been updated, representing a break from the older syntax supported by sw-precache. The following example contains the full set of currently supported options:

runtimeCaching: [{
  urlPattern: /api/,
  handler: 'networkFirst',
  options: {
    networkTimeoutSeconds: 10,
    cacheName: 'my-api-cache',
    expiration: {
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
    cacheableResponse: {
      statuses: [0, 200],
      headers: {'x-test': 'true'},
    },
    broadcastUpdate: {
      channelName: 'my-update-channel',
    },
    plugins: [
      {cacheDidUpdate: () => /* custom plugin code */}
    ],
  },
}]