Package Exports

service-worker-webpack

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (service-worker-webpack) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

service-worker-webpack

A Webpack Plugin to generate a Service Worker. Powered by Workbox.

What is this? 🧐

A minimal wrapper around Workbox to quickly add a service worker via your webpack build process.

Motivation

Workbox is great -- it's well documented and straightforward to customize your service worker. workbox-webpack-plugin makes caching your webpack assets simple, but I found myself reimplementing the same patterns across projects. Specifically:

Wiring up service worker registration boilerplate
Toggling service worker development on/off in development
Toggling Workbox logging on/off when debugging

Installation & Usage 📦

Add this package to your project:

yarn add -D service-worker-webpack

Update your webpack.config.js:

const { ServiceWorkerPlugin } = require("service-worker-webpack");

module.exports = {
  plugins: [new ServiceWorkerPlugin()],
};

API Overview 🛠

Name	Description	Type
enableInDevelopment	Enable the service worker in local development. Depending on your service worker configuration, this can be problematic for developer workflows where you end up serving outdated cached files. If `false` then a placeholder service worker will be generated, which will immediately clear any previously installed service workers that may have been installed previously such as testing a production build locally. Defaults to `false`. Recommended: `false` for general development, `true` for first time setup and when debugging your application's service worker.	boolean \| undefined
enableWorkboxLogging	Enable workbox logging. Workbox logging is both very helpful and very chatty. By default, workbox will use the webpack mode to determine whether or not to enable workbox logging. When the mode is `production`, then logging is disabled. Otherwise, logging is enabled. Setting this to `true` enables workbox logging when the webpack `mode` is set to `production`. Setting this to `false` will disable workbox logging, which is likely preferred when not debugging your servicer worker. Note: This option is only relevant when using the service worker generated by workbox. It does not apply to the development service worker generated when `enableInDevelopment` is `false`, or if you supply your own service worker via workbox's `swSrc` field. Defaults to `unset`, falling back on the workbox behavior. Recommended: `false` for general development, `true` for first time setup and when debugging your application's service worker.	boolean \| undefined
registration.autoRegister	Autoregister the service worker. If `false`, then the application must initialize the service worker by invoking `register`. Set this to `false` if you'd like to take control over when you service worker is initialized. You'll then need to add something like the following to your application: import { Workbox } from "workbox-window"; if ("serviceWorker" in navigator) { const wb = new Workbox("/path-to-your-service-worker.js"); wb.register(); } Defaults to `true`. Recommended: `true`.	boolean \| undefined
registration.entry	The webpack entry to inject the auto registration code into. The resulting bundle must be present on all pages that expect to register the service worker. Defaults to `main`, the default entry	string \| undefined
registration.path	The registration path tells the browser where your service worker is located. Defaults to `/service-worker.js`.	string \| undefined
registration.scope	The scope of the service worker determines which files the service worker controls, in other words, from which path the service worker will intercept requests. The default scope is the location of the service worker file, and extends to all directories below. So if service-worker.js is located in the root directory, the service worker will control requests from all files at this domain. Defaults to `undefined` which sets the default scope as described above. The registration path tells the browser where your service worker is located.	string \| undefined
workbox	Options passed to `worbox-webpack-plugin`. See all available configuration options here. Defaults to `GenerateSW` which will generate a service worker with the workbox runtime included.	InjectManifestOptions \| GenerateSWOptions

Examples 🚀

Check out the service-worker-webpack-example.

Warning ⚠️

You must serve your application over HTTPS in production environments. Service Workers must be served from the site's origin over HTTPS. A special case is made for localhost, so this is generally not necessary during local development. HTTPS is not handled by this library.

The origin constraint means that the service worker can not control mysite.com if it was served from something like mycdn.mysite.com.

Contributing 👫

PR's and issues welcomed! For more guidance check out CONTRIBUTING.md

Licensing 📃

See the project's MIT License.