Skip to main content

Serwist

First added

Workbox

About

A class to aid in handling service worker registration, updates, and reacting to service worker lifecycle events.

Parameters

  • scriptURL — The service worker script associated with this instance. Using a TrustedScriptURL is supported.
  • registerOptions — The service worker options associated with this instance.

Methods and fields

  • async register({ immediate = false }) — 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.
  • async update() — Checks for updates of the registered service worker.
  • 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.
  • 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 activate but not start controlling the page unless clients.claim() is called in the service worker.
  • getSW() — 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.
  • async messageSW(event) — 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 sent by calling event.ports[0].postMessage(...) in the service worker, which will resolve the promise returned by messageSW(). If no response is sent, the promise will never resolve.
  • messageSkipWaiting() — Sends a { type: "SKIP_WAITING" } message to the service worker that is currently waiting and associated with the current registration. If there is no current registration, or no service worker is waiting, calling this will have no effect.
  • handleCache(event) — Caches new URLs on demand. Call this method from the service worker’s message event. To trigger the handler, send a message of type "CACHE_URLS" alongside a list of URLs that should be cached as urlsToCache.

Usage

declare const confirmUpdate: () => boolean;
// ---cut-before---          
import { Serwist } from "@serwist/window";

if ("serviceWorker" in navigator) {
  const serwist = new Serwist("/sw.js", { scope: "/", type: "classic" });

  serwist.addEventListener("waiting", () => {
    serwist.addEventListener("controlling", location.reload);
    if (confirmUpdate()) {
      serwist.messageSkipWaiting();
    }
  });

  void serwist.register();
}

More resources

Here is a list of resources you can read to learn more about Serwist: