@afspeirs/service-worker

Integrate a service-worker easily into your website

About The Project

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.

Table of contents

• Getting Started
• Prerequisites
  • Create config file
  • postbuild script
• Installation
• Usage
• API
  • registerServiceWorker
• Custom Events
  • sw:content-cached
  • sw:new-content-available
• Roadmap
• License

Getting Started

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.

Prerequisites

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 config file

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

postbuild script

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

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

npm i -S @afspeirs/service-worker

Usage

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,
});

API

Function: registerServiceWorker

Registers a service worker using the Workbox library and dispatches custom events based on the service worker's installation status.

| Parameter | Type | Default value | Required | Description | | ------------------- | ------- | ---------------------- | -------- | ---------------------------------------------- | | register | boolean | N/A | Yes | When to register the service worker | | pathToServiceWorker | string | '/service-worker.js' | No | The path to where the service worker is stored |

Usage Example:

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

registerServiceWorker({
  register: true,
  // register: import.meta.env.PROD,
  // register: process.env.NODE_ENV === 'production',
  pathToServiceWorker: '/custom-service-worker.js',
});

Custom Events

sw:content-cached

This event is dispatched (on the window) when the service worker is installed for the first time and the content is cached.

Usage Example:

window.addEventListener('sw:content-cached', () => {
  console.log('Content has been cached for offline use.');
});

sw:new-content-available

This event is dispatched (on the window) when a new version of the service worker is installed and there is new content available.

Usage Example:

window.addEventListener('sw:new-content-available', () => {
  console.log('New content is available. Please refresh the page.');
});

Roadmap

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

License

ISC License © Andrew Speirs