If you are working with Service Workers for the first time you'll probably have noticed that the Service Worker's functionality can be found on different objects. This can be a little bit confusing.

First of all the API is a little bit misleading because navigator.serviceWorker is not an instance of the Service Worker itself - it's only a container. The Service Worker itself is provided by the property controller of this ServiceWorkerContainer.

  • navigator.serviceWorker: ServiceWorkerContainer
  • navigator.serviceWorker.controller: ServiceWorker

And there's also the ServiceWorkerRegistration that's not accessible as a property but can be accessed by different methods.

Let's start with the ServiceWorkerContainer! It allows you to access the current Service Worker and also allows you to receive messages from it in your application.

navigator.serviceWorker.addEventListener('message', event => {
    console.log('Message from service worker received: ', event.data);

The ServiceWorkerContainer also allows you to register a new Service Worker. The register() method responds with a promise that resolves with a ServiceWorkerRegistration object if the registration was successful. If there's already a registered Service Worker you will get the current ServiceWorkerRegistration - otherwise a new one.

navigator.serviceWorker.register('serviceWorker.js', registration => {
    console.log('Service worker successfully registered');

The ServiceWorkerRegistration represents - as the name reads - the registration of the Service Worker. Besides the register()-method this registration can also be accessed in other ways:

  • navigator.serviceWorker.ready(): The returning promise of this method will never be rejected and waits until the Service Worker is ready.
  • navigator.serviceWorker.getRegistration(scope): Returns a promise that resolves with the Service Worker registration of your specific scope (usually given as relative url but also optional). If no registration is available the promise resolves with undefined.
  • navigator.serviceWorker.getRegistrations(): Returns a promise that resolves with an array of all active Service Worker registrations. If there's no active registration the promise will resolve with an empty array.

The serviceWorkerRegistration allows you to access several APIs and functions you can use to improve your web application (only a few examples):

On the registration.active-property you have access to the active Service Worker. This is an instance of the ServiceWorker-interface. This object is the instance that controls your site and also your network requests. If a Service Worker is registered for the first time it won't control your site instantly and a reload of the page is necessary.

The active Service Worker is also accessible with window.navigator.controller but be careful! If you force a page reload this property is null. The property will also be null if there's no active Service Worker - registration.active is still available and gives you the last value set as active Service Worker. But why do you need your active Service Worker? The Service Worker is necessary if you want to send messages to your Service Worker instance and communicate with your Service Worker.


Also you can watch state changes of the Service Worker on its instance.

navigator.serviceWorker.controller.onstatechange = event => {
    const serviceWorker = navigator.serviceWorker.controller;
    console.log('Current service worker state: ', serviceWorker.state);

As you see there are different ways to access your Service Worker functionality and the naming isn't clear all the time. The Service Worker specification is still a draft at W3C and so it maybe changes and becomes more clear when the specification is finished. I hope I was able to bring a little light into the darkness and it is a little bit clearer now.

Stay tuned and have fun. :-)

Related Articles

 | Christian Liebel

Article Series Overview, Web Components & Architecture Canvas & Input ⬅ Copy & Paste Images (coming soon) Accessing Files & File Handler (coming soon) Dark Mode Support (coming soon) Summary (coming soon) Canvas: A Bitmap for the Web First, you need an element to draw on…

Read article
 | Christian Liebel

Article Series Overview, Web Components & Architecture ⬅ Canvas & Input Copy & Paste Images (coming soon) Accessing Files & File Handler (coming soon) Dark Mode Support (coming soon) Summary (coming soon) New Possibilities: An Overview of the Project Everyone knows and loves the…

Read article
 | Christian Liebel

In the previous parts of this article series, we learned that Apple does not support the standardized web-based push mechanisms, and there is no sign of a possible timeline for implementation. Therefore we have to look at additional ways to bring the users' attention back to our…

Read article