sw-service

Service Worker Service

The sw-service package streamlines the registration of Service Workers on client devices, simplifying the process of delivering enhanced functionality and offline capabilities through Progressive Web Apps. This package offers a user-friendly approach to managing PWA installations, providing a seamless experience for both developers and end users.

If you are looking for a tool to generate the Service Worker for your app, some options are: sw-builder and PWA Builder.

If your service worker is generated after the build process but you wish to test the registration flow during development, create an empty sw.js file and pass its path to the register method.

For an example on how to implement this package, visit uipalettes.

Getting Started

Install the package:

npm install -S sw-service

Usage

Register the Service Worker:

import { SWService } from 'sw-service';

SWService.register({ 
  path: '/sw.js',
  options: { 
    scope: '/',
    updateViaCache: 'none'
  }
  debugMode: true 
});

Trigger the PWA Installer:

import { SWService } from 'sw-service';

if (SWService.installer?.canAppBeInstalled()) {
  SWService.installer.installApp();
}

Update the Service Worker and refresh the app:

import { SWService } from 'sw-service';

SWService.updateApp();

Types

IAppInstallerService

The service in charge of managing the PWA's Installation process.

interface IAppInstallerService {
  // properties
  installationPromptOutcome: IInstallationPromptOutcome | undefined;
  appInstalled: boolean | undefined;
  runningInstalledApp: boolean;

  // actions
  canAppBeInstalled: () => boolean;
  installApp: () => Promise<void>;
}

IInstallationPromptOutcome

The action taken by the user once the installation prompt is displayed.

type IInstallationPromptOutcome = 'accepted' | 'dismissed';

IUserChoice

The result of the user's interaction with the installation prompt.

interface IUserChoice {
  outcome: IInstallationPromptOutcome;
  platform: string;
}

ISWService

The singleton that will handle the Service Worker's state as well as its functionality.

interface ISWService {
  // properties
  registration: ServiceWorkerRegistration | undefined;
  worker: ServiceWorker | undefined;
  registrationError: string | undefined;
  registrationDurationSeconds: number;

  // sub modules
  installer: IAppInstallerService | undefined;

  // service worker registration
  register(options?: ISWRegistrationOptions): void;
  updateApp(): Promise<void>,
}

ISWRegistrationOptions

The options that can be passed when registering the Service Worker.

interface ISWRegistrationOptions {
  // the path to the service worker file. Defaults to: '/sw.js'
  path?: string;

  // the options that can be passed to the Service Worker registration. Defaults to: { scope: '/' }
  // https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register#options
  options?: RegistrationOptions;

  // enables debug mode in the service worker, as well as the rest of the sub modules
  debugMode?: boolean;
}

Built With

• TypeScript

Running the Tests

# e2e tests
npm run test:e2e

# integration tests
npm run test:integration

# unit tests
npm run test:unit

License

MIT

Deployment

Install dependencies:

npm install

Build the library:

npm start

Publish to npm:

npm publish