Switching to Workbox

Writing a good, healthy, bug-free service-worker script and its installer script is a pretty hefty task. There are multiple pitfalls and they aren’t always visible before time. The worst part is, if something goes wrong, things can get out of hand pretty quickly.

Just watch this talk by Alexander Pope - ServiceWorkers Outbreak.

ServiceWorker libraries

In 2015, Google launched sw-precache and sw-toolbox for making our lives easier.


At first glance, it might appear to be a tool to simply cache static assets on page load. Turns out, it is a one-size-fits-all solution for writing service-workers.

With a vast array of options to use, one can write a service-worker in a simple and declarative manner, without having to worry about implementations.

cacheId                       [String]
clientsClaim                  [Boolean]
directoryIndex                [String]
dontCacheBustUrlsMatching     [Regex]
dynamicUrlToDependencies      [Object<String, Buffer, Array<String>>]
handleFetch                   [boolean]
ignoreUrlParametersMatching   [Array<Regex>]
importScripts                 [Array<String>]
logger                        [function]
maximumFileSizeToCacheInBytes [Number]
navigateFallback              [String]
navigateFallbackWhitelist     [Array<RegExp>]
replacePrefix                 [String]
runtimeCaching                [Array<Object>]
skipWaiting                   [Boolean]
staticFileGlobs               [Array<String>]
stripPrefix                   [String]
stripPrefixMulti              [Object]
templateFilePath              [String]
verbose                       [boolean]


Maybe you have your own service-worker script. Maybe you don’t need all the pre-caching features and all you care about is runtime caching (caching certain network requests)

This is where sw-toolbox comes in. It is a much smaller and lightweight module that deals specifically with runtime caching.

Using sw-toolbox is also pretty easy. The whole process can be broken into parts:

  1. Add sw-toolbox to your sw.js with importScripts().
  2. Setup routes and their handlers.



  function(request, values) {
    return new Response('handled URL: ' + request.url);

Moving towards a better future

Google talks about building a new, more modular tooling library here.

In parallel, we are working on the next generation of Service Worker tooling over in Workbox. This new work is more modular and will enable a number of libraries with additional capabilities to be built.

Workbox is a new project that aims to modularise the whole service-worker build process, adding background sync and offline analytics. Workbox is also backwards compatible with sw-precache and sw-toolbox and adopts their options.

Here’s a list of options that I’ve worked out from the source.

sw-precache workbox
cacheId cacheId
clientsClaim clientsClaim
directoryIndex directoryIndex
dontCacheBustUrlsMatching dontCacheBustUrlsMatching
dynamicUrlToDependencies dynamicUrlToDependencies
handleFetch handleFetch
ignoreUrlParametersMatching ignoreUrlParametersMatching
maximumFileSizeToCacheInBytes maximumFileSizeToCacheInBytes
navigateFallback navigateFallback
navigateFallbackWhitelist navigateFallbackWhitelist
runtimeCaching runtimeCaching
skipWaiting skipWaiting
staticFileGlobs staticFileGlobs


How to use Workbox, you say?

Workbox’s official website has all the documentation and loads of examples to help get started. Just to help you out, here are some common links:

A word of caution. At the time of writing, Workbox is pretty young (v1.0.1) and the docs feel inadequate. If you’re a power-user and want to dive deep into docs before using third party software, you might not like working with Workbox.