🐛 What's Fixed?
workbox-broadcast-update
- Fixed a bug where some private symbols were not being properly exported from
workbox-core
, which preventedworkbox-broadcast-update
from notifying on navigation requests. [#2050]
🎉 What's New?
workbox-background-sync
- Adds a new
getAll()
method to theQueue
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, whennavigationPreload: true
. [#2007] - Properly passes in a custom channel name when using the
broadcastUpdate
option inruntimeCaching
. [#2017]
workbox-background-sync
- Fixes a bug in which a
Request
wasn't beingclone()
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
ofsame-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 tofalse
) toworkbox-build
'sgenerateSW
andgenerateSWString
modes, which would also expose it to the wrappers likeworkbox-cli
andworkbox-webpack-plugin
. [#1981]
workbox-core
-
Adds
workbox.core.cacheNames.prefix
andworkbox.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 theWorkbox
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()
ormessageSW()
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 aWorkbox
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, amessage
listener is now added to the service worker output, which allows you to invokeskipWaiting()
from the window viapostMessage()
[#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 storeRequest
bodies asBlob
objects in IndexedDB, but this does not work in Safari. All request bodies are now stored asArrayBuffer
objects [#1932].
workbox-broadcast-update
- If the the
BroadcastCacheUpdate
instance is passed aninstall
event (which happens when using it as a precache plugin) rather than afetch
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 aroutes
getter method, giving developers access to the underlyingMap
of routes that have been registered for a given router. [#1714] -
The
Router#handleRequest()
method no longer requires anevent
be passed, which allows routing logic to be used programmatically, outside of the context of afetch
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 theBroadcastChannel
API by iterating over all the open window clients and sending them the update message viapostMessage()
API. In addition, thechannel
parameter is no longer required. If no channel is given the default channel nameworkbox
is used (no channle is used for browsers that don't support theBroadcastChannel
API). [#1673]
Build tools
- Support for a new
boolean
configuration option,cleanupOutdatedCaches
, has been added to theGenerateSW
mode of all of the build tools. It defaults tofalse
. When set totrue
, a call toworkbox.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 themaxAgeSeconds
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 forresponse.ok
(which is true for any status code in the range200
-209
). In practice, this means that partial responses with a status code of206
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 toinject-manifest
plugin. [#1763]
workbox-core
-
To work around an issue that could lead to failed navigations,
fetchOptions
are no longer set whenrequest.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 existingself.__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 theworkbox-cli
'swizard
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 theworkbox-google-analytics.prod.js
andworkbox-google-analytics.dev.js
toworkbox-offline-ga.prod.js
andworkbox-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 variousstrategyName
handler values inruntimeCaching
are nowStrategyName
(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
, andworkbox.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 aworkbox.strategies.strategyName()
factory method, or by explicitly constructingnew workbox.strategies.StrategyName()
. To avoid confusion, theworkbox.strategies.strategyName()
approach is deprecated, and will be removed in v5. We encourage all developers to move to thenew workbox.strategies.StrategyName()
syntax. [#1831, #1842] -
Previously, the various
workbox-strategies
would behave differently in failure scenarios. Some, likenetworkFirst
, would resolve with anundefined
value when there was a network failure and a cache miss. Other strategies would reject with aNetworkError
under a similar failure. Starting in v4, we've standardized how all of theworkbox-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 aWorkboxError
. 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 allResponse
s cached during installation have a non-error (less than400
) HTTP status code. If anyResponse
s have an error code, theinstall
phase will now fail. (The next time the service worker starts up, installation will be re-attempted.) Developers who need to precacheResponse
s that have a 4xx or 5xx status code (e.g., precaching a/not-found.html
URL that is served with a status code of404
) can opt-in to allowing that by passing in a customcacheWillUpdate
plugin to theworkbox.precaching.PrecacheController
'sinstall
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 toworkbox.core.skipWaiting()
, andworkbox.clientsClaim()
has been renamed toworkbox.core.clientsClaim()
. If you are using theskipWaiting
orclientsClaim
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 async
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 theResponse
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 precachemanifest.json
by default. Previously, the default configuration would causeworkbox-webpack-plugin
to exclude files namedmanfiest.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 Fixed?
workbox-precaching
- Fixed a bug where precached assets would not trigger the
cacheDidUpdate
callback because the now contain a__WB_REVISION__
URL parameter. [#1914]
workbox-routing
- Fixed a bug where the message listener add via
addCacheListener
would throw an error if a message event was received where theevent.data
property was not an object. [#1913]
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 anisUpdate
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 theWorkbox
class will now include awasWaitingBeforeRegistration
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 viaaddCacheListener()
now no longer requiresevent.data.metadata
to equalworkbox-window
. This allows developers not usingworkbox-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 ofworkbox-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
workbox-window
package now ships with a few different build options, to help make it as easy as possible for people to include it in to their existing tool chain [#1895, #1899]. Here's what's currently supported: -
Requiring
workbox-window
in node (or any or environment that doesn't support native modules):
// Imports a UMD version with ES5 syntax
const {Workbox} = require('workbox-window');
- Importing
workbox-window
via webpack or Rollup in a context where your build does not automatically transpile anything innode_modules
:
// Imports the module version with ES5 syntax
import {Workbox} from 'workbox-window';
- Importing
workbox-window
via webpack or Rollup in a context where you can handle transpiling yourself (or you don't need to transpile to ES5):
// Imports the module version with ES2015+ syntax
import {Workbox} from 'workbox-window/Workbox.mjs';
Note: option 3 above will usually result in the smallest file size, so it's recommend to do that if your build supports it.
🐛 What's Fixed?
workbox-routing
- The
setCatchHandler()
andsetDefaultHandler()
methods were not properly migrated as part of the bundling changes in #1831. This has been fixed, and these method now work as they did before [#1898].