generate-service-worker

Generate Service Worker

A node module for generating service worker files based on provided configuration options.

Why?

There are several other popular service worker generators out there (sw-precache, offline-plugin, etc), but they focus only on caching, and are not testable or easy to experiment with. Service workers also include support for other tools like notifications and homescreen installs. This generator attempts to account for a wider variety of configurable options.

GenerateServiceWorker supports generating a service worker with a root configuration, and any number of other experimental service workers. This is perfect for experimenting with different caching strategies, or rolling out service worker changes. The runtime file generated by service-worker-plugin makes it particularly easy to utilize your own experiment framework alongside the generated experimental service worker files if you can statically host the service workers.

Caching strategies inspired by sw-toolkit.

Use

const generateServiceWorkers = require('generate-service-worker');

const serviceWorkers = generateServiceWorkers({
  cache: {
    offline: true,
    precache: ['/static/js/bundle-81hj9isadf973adfsh10.js'],
    strategy: [{
      type: 'prefer-cache',
      matches: ['\\.js']
    }],
  }
}, {
  'roll_out_notifications': {
    notifications: {
      default: {
        title: 'Pinterest',
        body: 'You\'ve got new Pins!'
      }
    },
  }
});

Configurations

GenerateServiceWorker currently supports caching and notifications. The following are the configuration options for each.

Caching

The cache key is used for defining caching strategies. The strings in precache will be used to prefetch assets and insert them into the cache. The regexes in strategy.matches are used at runtime to determine which strategy to use for a given GET request. All cached items will be removed at installation of a new service worker version. Additionally, you can use your own custom cache template by including the full path in the template property. We suggest forking our templates/cache.js file to get started and to be familiar with how variable injection works in the codebase. If the offline option is set to true, the service worker will assume that an html response is an "App Shell". It will cache the html response and return it only in the case of a static route change while offline.

const CacheType = {
  offline?: boolean,
  precache?: Array<string>,
  strategy?: Array<StrategyType>,
  template?: string,
};
const StrategyType = {
  type: 'offline-only' | 'fallback-only' | 'prefer-cache' | 'race',
  matches: Array<regex>,
};

Strategy Types

strategy	description
offline-only	Only serve from cache if browser is offline.
fallback-only	Only serve from cache if fetch returns an error status (>= 400)
prefer-cache	Always pull from cache if data is available
race	Pull from cache and make fetch request. Whichever returns first should be used. (Good for some low-end phones)

Notifications

The notifications key is used for including browser notification events in your service worker. To enable the notifications in your app, you can call runtime.requestNotificationsPermission() from the generated runtime file. The backend work is not included. You will still need to push notifications to your provider and handle registration. Additionally, you can use your own custom notifications template by including the full path in the template property. We suggest forking our templates/notifications.js file to get started and to be familiar with how variable injection works in the codebase.

const NotificationsType = {
  default: {
    title: string,
    body?: string,
    icon?: string,
    tag?: string,
    data?: {
      url: string
    }
  },
  duration?: number,
  template?: string,
});

Event Logging

The log key is used for defining which service worker events your API wants to know about. Each string should be a valid url path that will receive a 'GET' request for the corresponding event.

const LogType = {
  notificationClicked?: string,
  notificationReceived?: string
};

License

MIT