🎉 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 */}
    ],
  },
}]

🎉 Whats New

• #1108 Added workbox-range-requests to v3
• #1104 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.

🐛 Whats Fixed

• #1111 Fixed a bug in precaching where indexedDB wasn't updating correctly
• #1112 Fixes updates to precaching indexedDB schema when upgrading from V2 to V3
• #1116 Fixes a grouping issue in logs if precaching fails.

⚠️ Breaking Changes

• #1105 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).
• #1079 workbox-cache-expiration now throws an error if you attempt to use it on the runtime cache (i.e. the shared cache used by all strategies by default)

What's new?

The 2.1.2 release contains a deprecation warning that's logged when Express-style routes containing wildcard characters are passed in to WorkboxSW.registerRoute().

Developers are urged to use RegExps as an alternative, in preparation for the deprecation in Workbox v3.

Notable PRs

• v2: Warn on usage of Express-style wildcard characters

What's new?

The 2.1.1 release contains a small change to ensure that the workbox-webpack-plugin is compatible with node 4.x.

Notable PRs

• Ensure untranspiled node 4+ compat for the v2 webpack plugin (thanks to @pskanawat for reporting!)

What's new?

The 2.1.0 release fixes a longstanding issue in workbox-sw that could cause routes established via router.registerRoute() to inadvertently take precedence over the internal route that is intended for precached assets.

As described in this issue, the impacted code might look like:

// The internal route to serve the precached assets *should* have
// taken precedence... but prior to the 2.1.0 release, it didn't.
workboxSW.precache([]);

// This is a very broad wildcard match!
// Previously, it would cause precached assets to be served network-first.
// As of the 2.1.0 release, it will no longer apply to precached assets.
workboxSW.router.registerRoute(
  '/*',
  workboxSW.strategies.networkFirst()
);

Our documentation states that precached assets are always served via a cache-first route, so this previous behavior is considered a bug.

If, for some reason, your service worker depended on this buggy behavior, please update your code prior to upgrading to 2.1.0.

Bug Fixes

• Give a precache-specific Router precedence (thanks to @jaspermdegroot for reporting!)

What's new?

The 2.0.3 release adds babel-preset-env-based transpilation into the build process for our browser libraries, currently targeted at compatibility with Chrome 51 and above. Following this change, the Workbox libraries should work within Samsung Browser 5 (which shares code with Chrome 51), while maintaining its existing compatibility with "evergreen" browsers.

Bug Fixes

• Using async, await makes workbox without further transpilation break on Samsung Internet (Thanks to @HenrikJoreteg for reporting!)

This release adds support for stable versions of Samsung Browser. Workbox was previously not transpiling async/await functions but now uses babel-preset-env to support versions of Chrome >= 51.

What's new?

The 2.0.1 release contains two bug fixes in the public interfaces.

Bug Fixes

workbox-build

• Fix backslashes replacement. (Thanks, @XhmikosR!)

workbox-sw

• Ensure that ignoreUrlParametersMatching works with directoryIndex

What's new?

The v2.0.0 introduces several breaking changes to interfaces, along with bug fixes and new functionality. Please read carefully before upgrading!

Note that all Workbox packages have been tagged with the 2.0.0 version number on npm, regardless of whether they have breaking changes or not.

Breaking changes

workbox-cli

• Move towards using 'workbox' over 'workbox-cli'.
  The workbox-cli alias for the command line interface is now deprecated, in favor of the preferred workbox alias. Using workbox-cli will log a warning message, and it will be removed as an alias in a future release. Developers are encouraged to switch to using workbox now.

workbox-routing

• No longer register a fetch handler for each Router by default
  We've made registering a fetch handler optional, allowing developers who want more control to use the Router class from inside any fetch handler.
  Developers who are using the workbox-routing module directly can call router.addFetchListener() to mimic the previous behavior.

workbox-runtime-caching

• Rename cacheWillMatch to cachedResponseWillBeUsed
  Developers who have implemented their own Workbox plugins that respond to cacheWillMatch lifecycle events should rename the method they expose to cachedResponseWillBeUsed. Developers using the pre-made plugins do not need to change anything.
• Adds JSDocs for the lifecycle methods, and awaits the return of each.
  The underlying RequestWrapper object that triggers request lifecycle methods will now always await the methods' return values. No changes should be necessary unless you've implemented your own plugin which returns a Promise and you do not want the RequestWrapper to delay while waiting for it to resolve.

New features

workbox-range-requests

• New library to support Range requests
  This allows Workbox to honor the Range: request header when fulfilling requests for cached resources. This comes up often when playing back cached media content.

Other changes

workbox-build

• Improved the workbox-build JSDoc

workbox-sw

• Ensure that ignoreUrlParametersMatching works with directoryIndex

workbox-webpack-plugin

• adding manifest transform for webpack public path

What's new?

The v1.3.0 release contains a few bug fixes for the workbox-build and workbox-sw projects.

It also includes some internal testing changes.

Note that packages that have not changed since the last release will not be tagged with a new version number on npm.

workbox-build

• fixed: bug that cauases passed in manifestTransforms not to run (thanks to @HenrikJoreteg)

workbox-routing

• Adds JSDocs for the handleFetch parameter

workbox-sw

• Fix for multiple cacheId prefixes in the precache handler (thanks to @HenrikJoreteg for reporting)
• Add all of workbox-sw's devDependencies to fix Lerna's versioning.

What's new?

The v1.2.0 release contains a number of smaller changes and bug fixes across several packages; note that packages that have not changed since the last release will not have a 1.2.0 version published on npm.

workbox-background-sync

• fixing queue initialization bug

workbox-build

• typo: fix small typo (thanks to @markgoho)
• Copies sourcemap over with source files
• Adding defaults to workbox-build
• Add use strict to generate-sw for Node 4 support (thanks to @MaxLeiter)
• Adds support for manifestTransforms

workbox-cache-expiration

• Fixes a bug with cacheFirst handler + maxAgeSeconds + CORS request (h/t to @pbakaus for reporting)

workbox-precaching

• Adding some logging for the precache details

What's new?

The v1.1.0 release contains a number of smaller changes and bug fixes across multiple packages.

workbox-sw

• You can now unregister previously registered routes using workbox-sw: #632
• The URL's query parameters will be included when matching NavigationRoute's white/blacklist: #637
• Makes it easier to register custom Route instances when using workbox-sw: #639
• Support for using non-GET HTTP verbs in workbox-sw's routes: #662

workbox-build / workbox-cli / workbox-webpack-plugin

• Ignore node_modules by default when using workbox-build: #609
• Improvements to workbox-cli when run from a directory that doesn't have subdirectories, or has hidden directories: #614 and #616
• workbox-build no longer unconditionally prepends a leading '/': #560

workbox-background-sync

• Fixes to replaying requests in workbox-background-sync: #601
• Added additional callbacks to workbox-background-sync: #666

Common

• Smaller dev bundles: #594
• Hashes present in request URLs will be stripped: #633