Class: Workbox

Constructor

Workbox

new Workbox(scriptURL, registerOptions)

Creates a new Workbox instance with a script URL and service worker options. The script URL and options are the same as those used when calling navigator.serviceWorker.register(scriptURL, options). See: https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register

Parameter
scriptURL	(string or TrustedScriptURL) The service worker script associated with this instance. Using a `TrustedScriptURL` is supported.
registerOptions	Optional Object The service worker options associated with this instance.

Parameter

scriptURL

(string or TrustedScriptURL)

The service worker script associated with this instance. Using a TrustedScriptURL is supported.

registerOptions

Optional

Object

The service worker options associated with this instance.

Fires: message; installed; waiting; controlling; activated; redundant

Properties

active

Resolves to the service worker registered by this instance as soon as it is active. If a service worker was already controlling at registration time then it will resolve to that if the script URLs (and optionally script versions) match, otherwise it will wait until an update is found and activates.

Returns: Promise containing ServiceWorker

controlling

Resolves to the service worker registered by this instance as soon as it is controlling the page. If a service worker was already controlling at registration time then it will resolve to that if the script URLs (and optionally script versions) match, otherwise it will wait until an update is found and starts controlling the page. Note: the first time a service worker is installed it will active but not start controlling the page unless clients.claim() is called in the service worker.

Returns: Promise containing ServiceWorker

Methods

getSW

getSW() returns Promise containing ServiceWorker

Resolves with a reference to a service worker that matches the script URL of this instance, as soon as it's available.

If, at registration time, there's already an active or waiting service worker with a matching script URL, it will be used (with the waiting service worker taking precedence over the active service worker if both match, since the waiting service worker would have been registered more recently). If there's no matching active or waiting service worker at registration time then the promise will not resolve until an update is found and starts installing, at which point the installing service worker is used.

Returns: Promise containing ServiceWorker

messageSkipWaiting

messageSkipWaiting()

Sends a {type: 'SKIP_WAITING'} message to the service worker that's currently in the waiting state associated with the current registration.

If there is no current registration or no service worker is waiting, calling this will have no effect.

messageSW

async

messageSW(data) returns Promise containing Object

Sends the passed data object to the service worker registered by this instance (via getSW()) and resolves with a response (if any).

A response can be set in a message handler in the service worker by calling event.ports[0].postMessage(...), which will resolve the promise returned by messageSW(). If no response is set, the promise will never resolve.

Parameter
data	Object An object to send to the service worker

Returns: Promise containing Object

register

async

Registers a service worker for this instances script URL and service worker options. By default this method delays registration until after the window has loaded.

Parameter

options

Optional

Object

Values in options have the following properties:

Parameter

immediate

Optional

function()

Setting this to true will register the service worker immediately, even if the window has not loaded (not recommended).

update

async

update()

Checks for updates of the registered service worker.

Events

activated

WorkboxEvent

The activated event is dispatched if the state of a Workbox instance's registered service worker changes to activated.

Properties

Parameter
sw	ServiceWorker The service worker instance.
originalEvent	Event The original `statechange` event.
isUpdate	(boolean or undefined) True if a service worker was already controlling when this `Workbox` instance called `register()`.
isExternal	(boolean or undefined) True if this event is associated with an external service worker.
type	string `activated`.
target	Workbox The `Workbox` instance.

controlling

WorkboxEvent

The controlling event is dispatched if a controllerchange fires on the service worker container and the scriptURL of the new controller matches the scriptURL of the Workbox instance's registered service worker.

Properties

Parameter
sw	ServiceWorker The service worker instance.
originalEvent	Event The original `controllerchange` event.
isUpdate	(boolean or undefined) True if a service worker was already controlling when this service worker was registered.
isExternal	(boolean or undefined) True if this event is associated with an external service worker.
type	string `controlling`.
target	Workbox The `Workbox` instance.

installed

WorkboxEvent

The installed event is dispatched if the state of a Workbox instance's registered service worker changes to installed.

Then can happen either the very first time a service worker is installed, or after an update to the current service worker is found. In the case of an update being found, the event's isUpdate property will be true.

Properties

Parameter
sw	ServiceWorker The service worker instance.
originalEvent	Event The original `statechange` event.
isUpdate	(boolean or undefined) True if a service worker was already controlling when this `Workbox` instance called `register()`.
isExternal	(boolean or undefined) True if this event is associated with an external service worker.
type	string `installed`.
target	Workbox The `Workbox` instance.

message

WorkboxEvent

The message event is dispatched any time a postMessage is received.

Properties

Parameter
data	any type The `data` property from the original `message` event.
originalEvent	Event The original `message` event.
type	string `message`.
ports	Array of MessagePort The `ports` value from `originalEvent`.
target	Workbox The `Workbox` instance.

redundant

WorkboxEvent

The redundant event is dispatched if the state of a Workbox instance's registered service worker changes to redundant.

Properties

Parameter
sw	ServiceWorker The service worker instance.
originalEvent	Event The original `statechange` event.
isUpdate	(boolean or undefined) True if a service worker was already controlling when this `Workbox` instance called `register()`.
type	string `redundant`.
target	Workbox The `Workbox` instance.

waiting

WorkboxEvent

The waiting event is dispatched if the state of a Workbox instance's registered service worker changes to installed and then doesn't immediately change to activating. It may also be dispatched if a service worker with the same scriptURL was already waiting when the register() method was called.

Properties

Parameter
sw	ServiceWorker The service worker instance.
originalEvent	(Event or undefined) The original `statechange` event, or `undefined` in the case where the service worker was waiting to before `.register()` was called.
isUpdate	(boolean or undefined) True if a service worker was already controlling when this `Workbox` instance called `register()`.
isExternal	(boolean or undefined) True if this event is associated with an external service worker.
wasWaitingBeforeRegister	(boolean or undefined) True if a service worker with a matching `scriptURL` was already waiting when this `Workbox` instance called `register()`.
type	string `waiting`.
target	Workbox The `Workbox` instance.