service-worker-webpack

1.0.0 verified Sat Apr 25 auth: no javascript

A minimal Webpack plugin wrapper around Workbox (v6+) to generate a service worker that precaches static assets. Current stable version is 1.0.0, which follows semantic versioning. Works with Webpack 4 and 5, and ships TypeScript type definitions. Key differentiators: zero-config setup (just add the plugin), optional logging controls, and development mode support with proper cleanup of stale service workers.

Common errors

error Cannot find module 'service-worker-webpack' ↓

cause Package not installed or installed incorrectly (not in devDependencies).

fix

npm install --save-dev service-worker-webpack

error ServiceWorkerPlugin is not a constructor ↓

cause Incorrect import: using ES import syntax on a CJS-only module.

fix

Change import to: const { ServiceWorkerPlugin } = require('service-worker-webpack');

error TypeError: webpack.optimize.SplitChunksPlugin is not a constructor ↓

cause This package does not export SplitChunksPlugin; user may have confused it with webpack's built-in plugin.

fix

Use webpack's optimize.splitChunks configuration instead.

Warnings

gotcha When enableInDevelopment is false (default), the generated service worker in dev mode is a no-op that immediately unregisters any existing service worker. This can surprise developers who expect caching to work in development. ↓

fix Set enableInDevelopment: true in the plugin options during debugging, or accept that caching is disabled in development.

gotcha Workbox logging is verbose. By default, it logs in non-production mode; setting enableWorkboxLogging: false may still show logs if webpack mode is not 'production'. ↓

fix Explicitly set enableWorkboxLogging: false to suppress all workbox logs regardless of mode.

gotcha The plugin does not support custom service worker scripts via swSrc (unlike workbox-webpack-plugin). Users needing custom SW logic must use workbox-webpack-plugin directly. ↓

fix Switch to workbox-webpack-plugin if custom swSrc is required.

breaking Version 1.0.0 requires Webpack 4.37+ or 5.9+. Older Webpack versions (e.g., 4.36) are not supported. ↓

fix Upgrade webpack to ^4.37.0 || ^5.9.0.

Install

npm install service-worker-webpack

yarn add service-worker-webpack

pnpm add service-worker-webpack

Imports

ServiceWorkerPlugin
wrong
```
import { ServiceWorkerPlugin } from 'service-worker-webpack';
```
correct
```
const { ServiceWorkerPlugin } = require('service-worker-webpack');
```
This package does not export ESM; only CJS require() works. For projects using ESM, use dynamic import or transpile.

ServiceWorkerPlugin (default import)

wrong

import ServiceWorkerPlugin from 'service-worker-webpack';

correct

const ServiceWorkerPlugin = require('service-worker-webpack').ServiceWorkerPlugin;

No default export exists; must use named export via require.

type ServiceWorkerPluginOptions

wrong

import type { ServiceWorkerPluginOptions } from 'service-worker-webpack';

correct

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

TypeScript types are bundled but only accessible via the same require; no separate type export path.

Quickstart

Adds a service worker that precaches all output static assets using Workbox, with minimal configuration.

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

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    new ServiceWorkerPlugin({
      enableInDevelopment: false,
      enableWorkboxLogging: false,
    }),
  ],
};