hapi-sw

ServiceWorker generation plugin for Hapi.js

hapi-sw is a Hapi.js plugin that creates a Service Worker with Workbox.

Motivation

Service Workers are a building block for progressive web apps, but require intricate configuration. There are already great projects like Workbox that can help you generate Service Worker code effectively, but typically require some cross-cutting information that might not be readily available at build-time. Additionally, these tools make assumptions that favor static assets while ignoring the server-side routes which ultimately deliver those assets.

This plugin addresses that problem by generating a properly configured Service Worker dynamically, based on the assets and routes available to your server.

Usage

Add hapi-sw as a dependency to your Hapi.js project:

npm install hapi-sw --save

Register the plugin with a connected Hapi server, passing your configuration for Workbox as options for the plugin:

const Hapi = require('hapi');
const server = new Hapi.Server();

server.connection({ port: 3000 });

await server.register({
  plugin: require('hapi-sw'),
  options: {
    globDirectory: './assets',
    globPatterns: [
        '**/*.{css,js}',
        'img/**.*'
    ],
    runtimeCaching: [
          {
              urlPattern: new RegExp(CDN_DOMAIN),
              handler: 'CacheFirst'
          }
      ]
  }
});

// service worker now available at /service-worker.js
await server.start();

See the example code to get a more detailed understanding of what a typical setup might look like. Here's how to run it locally:

$ npm install
$ cd examples
$ node index.js

Note: This plugin has migrated from sw-precache to Workbox (v3.0.0+). See MIGRATION.md for migration details if you're upgrading from an older version.

When you register this plugin, a few things happen:

• Routes for the Service Worker and its registration code are added

  • /service-worker.js is source of the worker generated by Workbox
    • This file is generated dynamically whenever the server starts
    • The generated worker is cached for subsequent requests
  • /service-worker-registration.js is the example registration file, recommended by Workbox

• A listener is added to the 'route' event

  • Whenever any subsequent routes are added to the server, hapi-sw will inspect them for any custom plugin settings
  • This allows for route-scoped rules to be added to the options sent to Workbox
    • For instance, you could add a rule on a route to add that url to the pre-fetched cache:

server.route({
  path: '/',
  config: {
    plugins: {
      sw: {
          templatedURLs: [
            './templates/homepage.html',
            './templates/layout.html'
          ]
      }
    }
  }
})

Configuration

All top-level settings given at registration are passed through to Workbox. See the Workbox documentation for the full list of options and what they do.

Required Workbox Options

{
  globDirectory: './',           // Base directory for glob patterns
  globPatterns: ['**/*.{js,css}'], // File patterns to cache
  swDest: 'service-worker.js'    // Output path for generated worker
}

Route Configuration

The following options may be set in a route's sw plugin config:

• templatedURLs (formerly dynamicUrlToDependencies)
• dontCacheBustURLsMatching (formerly dontCacheBustUrlsMatching)
• navigateFallback
• runtimeCaching

Any rules passed to these settings will be scoped to the route's path unless otherwise specified.

Legacy Configuration Support

The plugin supports legacy sw-precache options with deprecation warnings. See MIGRATION.md for details on migrating from sw-precache to Workbox configuration.