Service Worker Development Cookbook

A service worker is a script that stands between your browser and the network, giving you, among other things, the ability to intercept network requests, and respond to them in different ways.

In order for your website or app to work, the browser fetches its assets, such as HTML pages, JavaScript, CSS, images, and fonts. In the past, managing these resources was mainly the browser's responsibility. If the browser couldn't access the network, you would probably see its Unable to connect to the Internet message. There were techniques you could use to encourage the local caching of assets, but the browser often had the last say.

One feature service worker uses heavily is promises. So it is important to have a good understanding of promises.

Promises are a great mechanism for running async operations with success dependent on one another. This is central to the way service workers work.

Promises can do a great many things, but for now, all you need to know is that if something returns a promise, you can attach .then() to the end and include callbacks inside it for success, failure, and so on, or you can insert .catch(), the end if you want to include a failure callback.

Let's compare a traditional synchronous callback structure to its asynchronous promise equivalent:

sync

try {
  var value = Fn();
  console.log(value);
} catch(err) {
  console.log(err);
}

async

Fn().then(function(value) {
  console.log(value);
  }).catch(function(err) {
  console.log(err);
});

In the sync example, we have to wait for Fn() to run and return a value before any more of the code can execute. In the async example, Fn() returns a promise for the value, then the rest of the code can carry on running. When the promise resolves, the code inside then will be run asynchronously.

If you are using a newer version of a browser, the chances are that service workers are already enabled on it. But, if that is not the case, we will have to change few things in the browser settings. In the following section, we are going to cover how to enable service worker features in Chrome and Firefox.

Follow the steps below to enable service worker in Chrome and Firefox.

This recipe assumes you run Windows 7 or higher with Internet Information Service (IIS) enabled.

Follow these instructions to enable SSL:

This recipe assumes that you are running OS X 10.11, El Capitan, or higher. We are going to use a command-line utility called Vim for editing files, which already comes with Mac. Make sure not to use the number pad with Vim. Please be aware that this process is lengthy.

Follow these instructions to enable SSL:

Before registering for a GitHub account, please make sure you have a valid e-mail address.

Follow these instructions to set up GitHub pages:

To get started, with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the first recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up your file structure:

We started off by making sure that the service worker feature is available with the line if ('serviceWorker' in navigator). If that's not the case, then we set the message to unavailable. If your browser does not support service workers, you will get this message.

Now we register the service worker with the empty JavaScript file and the scope. To ensure the registration is only applicable to the current directory and those underneath it, we override the default scope of '/' with './' in the line { scope: './' } as the scope has to be of the same origin.

If you decide that your script files should sit elsewhere, you will need a special header, such as Service-Worker-allowed: true or a specific content-type, such as text/javascript.

If the registration was successful, we print the message successful to the status message.

Otherwise, we print the error message as the status. The reason for the error could be something going wrong during the registration, for example, the service-worker.js file may not available or it may contain a syntax error.

We can unregister the service worker by calling the following unregister() function:

serviceWorker.unregister().then(function() {
    document.getElementById('status').innerHTML = 'unregistered';
})

Known issues

There are a couple of issues with the Chrome browser when working with service workers, which might confuse you.

The ERR_FILE_EXISTS error message

Reloading pages with service workers will always show an ERR_FILE_EXISTS error message, even if there's nothing wrong with your code.

This seems to occur when we are trying to access an already registered service worker.

Stale console messages

Logging messages from the service worker scripts such as the console.log may not clear from the console, which seems like the events are being fired too many times on subsequent page loads.

To get started with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the previous recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up your file structure:

When the registration is successful, we inspect the state of the registration and print it to the browser. In this case it is installing, waiting, or active:

 if (registration.installing) {
          serviceWorker = registration.installing;
          printState('installing');
        } else if (registration.waiting) {
          serviceWorker = registration.waiting;
          printState('waiting');
        } else if (registration.active) {
          serviceWorker = registration.active;
          printState('active');
        }

The printState(state) helper function will print out the state to the browser.

At the end we attach an event listener to the service worker called statechange. The callback of this event listener will print the state changes to the browser:

if (serviceWorker) {
          printState(serviceWorker.state);

          serviceWorker.addEventListener('statechange', function(e) {
            printState(e.target.state);
          });
        }

When the registered service worker is in the activated state, we can refresh the page to see the service worker taking control.

To demonstrate a page loading, without the service worker taking control, press Shift and refresh the page. You will see the activate event logged in the web console.

We are subscribing to two event listeners in the service-worker.js file, install and activate:

self.addEventListener('install', function(e) {
  console.log('Install Event:', e);
});

self.addEventListener('activate', function(e) {
  console.log('Activate Event:', e);
});

These events get fired when this version of the script first gets registered for the given scope.

The install event is a good place to prefetch data and initialize caches, and the activate event works well for cleaning up data from the old version of the script.

When the service worker is successfully registered, it will go through the following stages.

To get started with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the previous recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up debugging for service workers:

The resulting page chrome://serviceworker-internals shows the registered service workers. It also shows basic action buttons, which are explained in detail as follows:

When you are working with DevTools open, you might want to check to make sure that the Disable cache is not checked in the Network tab. If that option is checked, the requests will go to the network instead of the service worker.

To get started with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the previous recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up your file structure (or you can find the files in the provided directory, 01/05):

When the registration is successful, we inspect the state of the registration and print it to the browser.

In the service-worker.js file, we always fetch the response from the network:

event.respondWith(
        fetch(event.request).then(function(response) {

If we received an error response, we return the stale version from the cache:

if(response.status >= 500) {
                    cache.match(event.request).
					then(function(response) {
                        // Return stale version from cache
                        return response;
})

If we can't find the stale version, we return the network response, which is the error:

}).catch(function() {
                        
return response;
});

If the response was successful (response code 200), we update the cached version:

} else {
cache.put(event.request, response.clone());
   return response;
}

The put() method of the cache interface allows key/value pairs to be added to the current cache object. The put() method also overrides any key/value pair previously stored in the cache that matches the request:

fetch(url).then(function (response) {
  return cache.put(url, response);
});

To get started with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the previous recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up your file structure (these can also be found in the provided directory, 01/03):

After the service worker registers itself successfully, we check to make sure that it is currently handling the network operations:

if (navigator.serviceWorker.controller) {
printStatus('The service worker is currently handling 
network operations.');
…
}

In this case, we are calling the showRequest() function to add an event listener to the URL shorten button, and show the request block. Otherwise, the whole request block will be hidden:

function showRequest() {
   document.getElementById('url-shorten-btn')
.addEventListener('click', sendRequest);
   document.getElementById('request').style.display = 'block';
}

The sendRequest() function builds the HTTP request. It creates a POST request with a URL of the Google API for URL shortening:

xhr.open('POST',
        'https://www.googleapis.com/urlshortener/v1/url?' +
  'key=[Your API Key]');

You will have to obtain an API key for this service to be used. For this, follow these instructions:

If the Mock Response is checked, set the request header X-Mock-Response to yes:

if (document.getElementById('mock-checkbox').checked) {
      xhr.setRequestHeader('X-Mock-Response', 'yes');
    }

Now add an event listener to the load event and pass in a callback to assign the response data to the link displaying the result:

xhr.addEventListener('load', function() {
var response = JSON.parse(xhr.response);
var el = document.getElementById('short-url');

   el.href = response.id;
   el.innerHTML = response.id;
});

At the end of the sendRequest function, we are sending the original URL as well as the request object we built as a request:

request = {
        longUrl: document.getElementById('long-url').value
      };
xhr.send(JSON.stringify(request));

In the service-worker.js file, we are adding an event listener for the fetch event. We check that the request URL path has the urlshortner in it and the request header has X-Mock-Response:

if (requestUrl.pathname === '/urlshortener/v1/url' &&
    event.request.headers.has('X-Mock-Response')) {
…
   }

We build a mock response object with a body, status, and the headers:

   var response = {
      body: {
        kind: 'urlshortener#url',
        id: 'https://goo.gl/KqR3lJ',
        longUrl: 'https://www.packtpub.com/books/info/packt/about'
      },
      init: {
        status: 200,
        statusText: 'OK',
        headers: {
          'Content-Type': 'application/json',
          'X-Mock-Response': 'yes'
        }
      }
    };

Finally, we create a response with the mock response:

var mockResponse = new Response(
JSON.stringify(response.body), response.init);

console.log('Mock Response: ', response.body);
event.respondWith(mockResponse);

To get started with service workers, you will need to have the service worker experiment feature turned on in your browser settings. If you have not done this yet, refer to the previous recipe: Setting up service workers. Service workers only run across HTTPS. To find out how to set up a development environment to support this feature, refer to the following recipes: Setting up GitHub pages for SSL, Setting up SSL for Windows, and Setting up SSL for Mac.

Follow these instructions to set up your file structure:

In our index.html file, we're fetching a large uncompressed jQuery library:

<script src="https://code.jquery.com/jquery-2.2.0.js"></script>

In our service-worker.js file, the event listener of the install event is calling the skipWaiting() method, which forces the waiting service worker to become the active service worker:

self.addEventListener('install', function(event) {
    self.skipWaiting();
});

The skipWaiting() method is used inside the active event handler, which in turn uses Clients.claim() to ensure that updates to the underlying service worker take effect immediately, for both the current client and all other active clients:

self.addEventListener('activate', function(event) {
    if (self.clients && clients.claim) {
        clients.claim();
    }
});

In event listener for fetch, we pass in a Promise.race() function where the first iterable, which is timeout(400), gets resolved first:

self.addEventListener('fetch', function(event) {
  if (/\.js$/.test(event.request.url)) {
    event.respondWith(Promise.race([timeout(400), fetch(event.request.url)]));
  } else {
    event.respondWith(fetch(event.request));
  }
});

We will elaborate on the Promise.race() function soon. The timeout() function returns a promise with 408, which is the code for the request timed out status.

The Promise.race() method returns a promise that resolves, or rejects, as soon as one of the promises in the iterable resolves or rejects, with the value or reason from that promise:

var p1 = new Promise(function(resolve, reject) { 
    setTimeout(resolve, 400, "one"); 
});
var p2 = new Promise(function(resolve, reject) { 
    setTimeout(reject, 100, "two");
});

Promise.race([p1, p2]).then(function(value) {
  // Not called              
}, function(reason) {
  console.log(reason); // "two"
  // p2 is faster, so it rejects
});

As you can see, two is faster, so the result is reject.