Integrate a service-worker easily into your website

I am always using the same code across all of my web apps to install a service worker.

So I thought why not make it an npm package

This projects contains the code I use within every project to initialise the service worker and dispatch custom events to signal when there is an update available and when the assets have been cached.

• Getting Started
• Prerequisites
  • Create config file
  • postbuild script
• Installation
• Usage
• API
  • registerServiceWorker
    • register parameter
    • pathToServiceWorker parameter
• Roadmap
• License

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Because we use workbox-window in this package. workbox-cli has been set as a peer dependency (which means that it will be installed in your project for you). This means that you can use workbox-cli commands within your builds scripts.

Create a config file called workbox.config.cjs (The name doesn't really matter, you just need to enter the same filename in the postbuild step)

module.exports = {
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{css,js,png,html,webmanifest}',
  ],
  swDest: 'dist/service-worker.js',
  skipWaiting: true,
  clientsClaim: true,
};

For more information view the documentation site for generateSW config options

Update your package.json to have the following postbuild script so that the service-worker is generated:

"scripts": {
  ...
  "postbuild": "workbox generateSW workbox.config.cjs"
  ...
}

For more information view the documentation site for generateSW

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

npm i -S @afspeirs/service-worker

Once installed in your project you can include import/require the code.

For example in a JavaScript project (using Vite):

import { registerServiceWorker } from '@afspeirs/service-worker';

registerServiceWorker({
  register: import.meta.env.PROD,
  pathToServiceWorker: '/service-worker.js',
});

This is the only exported function from the package currently.

registerServiceWorker(register: boolean, pathToServiceWorker: string = '/service-worker.js')

Supported params for the registerServiceWorker function are listed below.

If present, the request will be performed as soon as the component is mounted

Example:

import { registerServiceWorker } from '@afspeirs/service-worker';

registerServiceWorker({
  register: import.meta.env.PROD,
  // register: process.env.NODE_ENV === 'production',
});

If present, the service worker at the path will be used

Example:

import { registerServiceWorker } from '@afspeirs/service-worker';

registerServiceWorker({
  register: true,
  pathToServiceWorker: '/sw.js',
});

• Simplify the prerequisite steps and make it so that it can be controlled by this package

ISC License © Andrew Speirs