serviceworker-webpack-plugin

1.0.2 verified Sat Apr 25 auth: no javascript

A webpack plugin (v1.0.2, latest) that simplifies creating a service worker to cache all webpack bundle assets. It automatically resolves asset names (including hashed names for long-term caching) and provides them to a custom service worker script via a global `serviceWorkerOption` variable. Supports webpack 4 only (peer dependency). Key differentiator: it handles non-deterministic asset names and integrates with webpack's dev server. Alternatives like `workbox-webpack-plugin` are more full-featured but heavier; this plugin is minimal and focused.

Common errors

error TypeError: ServiceWorkerWebpackPlugin is not a constructor ↓

cause CommonJS require returns the module object, not the constructor directly

fix

Use const ServiceWorkerWebpackPlugin = require('serviceworker-webpack-plugin').default

error Module not found: Can't resolve 'serviceworker-webpack-plugin/lib/runtime' ↓

cause Incorrect import path or missing dependency

fix

Ensure correct import: import runtime from 'serviceworker-webpack-plugin/lib/runtime'

error Error: serviceWorkerOption is not defined ↓

cause The global variable is only available inside the service worker file processed by the plugin

fix

Reference serviceWorkerOption only in the file specified as entry in the plugin options

Warnings

breaking v1.0.0 dropped webpack 3 support; requires webpack ^4 ↓

fix Upgrade to webpack 4 or stay on v0.2.3 for webpack 3

deprecated v0.2.0 changed default publicPath from '' to '/'; can cause double slashes in asset paths ↓

fix Set publicPath explicitly to '' if using a relative path, or upgrade to latest

gotcha Runtime import must be from serviceworker-webpack-plugin/lib/runtime, not the main package ↓

fix Use `import runtime from 'serviceworker-webpack-plugin/lib/runtime'`

gotcha The default export in CommonJS requires `.default` access ↓

fix Use `const ServiceWorkerWebpackPlugin = require('serviceworker-webpack-plugin').default`

gotcha Plugin does not support webpack 5; unmaintained for newer webpack versions ↓

fix Consider using workbox-webpack-plugin for webpack 5 projects

Install

npm install serviceworker-webpack-plugin

yarn add serviceworker-webpack-plugin

pnpm add serviceworker-webpack-plugin

Imports

ServiceWorkerWebpackPlugin
wrong
```
const ServiceWorkerWebpackPlugin = require('serviceworker-webpack-plugin').default;
```
correct
```
import ServiceWorkerWebpackPlugin from 'serviceworker-webpack-plugin';
```
Default export is the constructor. In CommonJS, use require('serviceworker-webpack-plugin').default; plain require('serviceworker-webpack-plugin') returns the module object.
runtime
wrong
```
import { runtime } from 'serviceworker-webpack-plugin';
```
correct
```
import runtime from 'serviceworker-webpack-plugin/lib/runtime';
```
The runtime module is a separate file in the lib folder, not part of the main export. Must import with relative path.

serviceWorkerOption

wrong

import { serviceWorkerOption } from 'serviceworker-webpack-plugin';

correct

// Global variable injected into the service worker script at build time

This is a global variable injected into the service worker file by the plugin. It is not importable.

Quickstart

Demonstrates setup: plugin in webpack config, custom service worker that caches all assets, and runtime registration in main bundle.

// webpack.config.js
import path from 'path';
import ServiceWorkerWebpackPlugin from 'serviceworker-webpack-plugin';

export default {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.[chunkhash].js',
    publicPath: '/',
  },
  plugins: [
    new ServiceWorkerWebpackPlugin({
      entry: path.join(__dirname, 'src/sw.js'),
    }),
  ],
};

// src/sw.js
self.addEventListener('install', function(event) {
  event.waitUntil(
    caches.open('my-cache').then(function(cache) {
      return cache.addAll(serviceWorkerOption.assets);
    })
  );
});

self.addEventListener('fetch', function(event) {
  event.respondWith(
    caches.match(event.request).then(function(response) {
      return response || fetch(event.request);
    })
  );
});

// src/index.js
import runtime from 'serviceworker-webpack-plugin/lib/runtime';

if ('serviceWorker' in navigator) {
  runtime.register();
}