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

Bubblewrap: How to Publish Your Progressive Web App (PWA) in the Google Play Store
Traditionally, when developers wanted to distribute their web-based apps through app stores like Google Play, there was only one option: Apache Cordova. In the meantime, Progressive Web Apps (PWA) have arrived. The life of a PWA starts in the browser, and users can choose to…
Christian Liebel
Project Fugu – neue Fähigkeiten braucht das Web
Mit Project Fugu mischen Google, Microsoft und Intel die Welt der webbasierten Anwendungsentwicklung gründlich auf. Fähigkeiten, die bisher nur nativen Anwendungen oder über Wrapper-Ansätze wie Apache Cordova oder GitHub Electron zugänglich waren, sollen ihren Weg in den Browser…
Christian Liebel
Push API: Advanced Progressive Web Apps - Push Notifications Under Control - Part 2
This part of our article series on PWA push notifications focuses on the Push API that deals with creating push subscriptions and receiving push messages. If you want to learn more about web-based notifications in general, check out the first part of our series on the…
Christian Liebel
Running Your ASP.NET Core Blazor WebAssembly Application as a Progressive Web App (PWA)
As already outlined in my previous article, a Blazor application almost always has to integrate with the JavaScript world, and especially with the DOM layer in the browser. In this article, I am going to quickly show you how to transform your Blazor WebAssembly application into a…
Christian Weyer