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.

• 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-webpack-plugin

• This plugin requires now requires webpack v4 or higher.

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.