Registry / devops / workbox-webpack-plugin

workbox-webpack-plugin

library7.4.0jsnpmunverified

The `workbox-webpack-plugin` is a core module within the Workbox library, designed to integrate service worker generation and management directly into a Webpack build pipeline. It facilitates the precaching of static assets by generating a manifest of local files, which `workbox-sw` then utilizes to ensure an application functions reliably offline. The current stable version is 7.4.0, with minor releases primarily focused on critical dependency updates and maintenance. Key differentiators include its seamless integration with Webpack, offering two primary modes: `GenerateSW` for fully automated service worker creation, and `InjectManifest` for more customized service worker logic while still leveraging Workbox's build-time precaching. This plugin supports modern JavaScript environments and has been rewritten in TypeScript since v6.5.0, providing robust type definitions.

devops

npm install workbox-webpack-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORKBOX-WEBPACK-PL

workbox-webpack-plugin

devopsjavascriptv7.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GenerateSW

✓ import { GenerateSW } from 'workbox-webpack-plugin';

✗ const { GenerateSW } = require('workbox-webpack-plugin');

ES Modules are the standard for modern Node.js and TypeScript projects. CommonJS `require` might work in some older setups but is not recommended for v7+.

InjectManifest

✓ import { InjectManifest } from 'workbox-webpack-plugin';

✗ import InjectManifest from 'workbox-webpack-plugin';

Both `GenerateSW` and `InjectManifest` are named exports. There is no default export for the plugin itself.

WorkboxWebpackPlugin

✓ import * as WorkboxWebpackPlugin from 'workbox-webpack-plugin';

Useful for accessing all exports or for environments where a direct named import is less convenient. Primarily for TypeScript users who want to reference the module.

This quickstart demonstrates a basic Webpack configuration using `GenerateSW` to create a service worker that precaches assets and implements a runtime caching strategy for Google Fonts. It includes configuration for a development server.

import path from 'path'; import { fileURLToPath } from 'url'; import { GenerateSW } from 'workbox-webpack-plugin'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); export default { mode: 'production', entry: './src/index.js', output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist'), clean: true, }, plugins: [ new GenerateSW({ clientsClaim: true, skipWaiting: true, // Define runtime caching strategies. E.g., for Google Fonts: runtimeCaching: [{ urlPattern: new RegExp('^https://fonts\\.gstatic\\.com/'), handler: 'CacheFirst', options: { cacheName: 'google-fonts-webfonts', expiration: { maxEntries: 30, maxAgeSeconds: 60 * 60 * 24 * 365, // 1 year }, cacheableResponse: { statuses: [0, 200], }, }, }], }), ], devServer: { static: './dist', open: true, }, // Workaround for Node.js 20+ and Webpack 5+ using ESM for config files experiments: { outputModule: true } };

Debug

Known issues

breakingWorkbox v7.0.0 increased the minimum required Node.js version to 16. Versions 7.x and above will not run on older Node.js environments.

fix

Upgrade your Node.js environment to version 16 or higher. The current recommended version is >=20.0.0 as per `engines` field.

affects: >=7.0.0

gotchaThe `workbox-webpack-plugin` (and Workbox library generally) has seen frequent dependency updates to address critical vulnerabilities. Always ensure you are on the latest patch release within your major version to receive these security fixes.

fix

Regularly update `workbox-webpack-plugin` and other Workbox modules to the latest patch version (e.g., `npm update workbox-webpack-plugin` or `yarn upgrade workbox-webpack-plugin`). Consider using a dependency monitoring tool.

affects: >=6.0.0

breakingWhile `workbox-webpack-plugin` was rewritten in TypeScript in v6.5.0, which provided public TypeScript definitions, older configurations (especially those relying on implicit types or specific internal structures) *might* encounter subtle compatibility issues, though no functional changes were anticipated.

fix

Ensure your Webpack configuration and any custom logic interacting with the plugin adhere to the public TypeScript interfaces. Review type definitions if encountering unexpected type errors during upgrade from pre-6.5.0 versions.

affects: >=6.5.0

Errors

Common errors & fixes

ERROR in Error: workbox-webpack-plugin@X.Y.Z requires a peer of webpack@^A.B.C || ^D.E.F but none is installed.

Webpack peer dependency mismatch. The installed Webpack version is incompatible with the version required by `workbox-webpack-plugin`.

fix

Install a compatible Webpack version (e.g., `npm install webpack@^5.91.0` or `yarn add webpack@^5.91.0`) or downgrade `workbox-webpack-plugin` to a version compatible with your Webpack setup. Refer to the package's `peerDependencies` in `package.json`.

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require` in a JavaScript file that is being interpreted as an ES Module (e.g., due to `"type": "module"` in `package.json` or a `.mjs` extension) for a Webpack config.

fix

Update your Webpack configuration file to use ES Module syntax (`import`/`export`) instead of CommonJS `require`. For example, `export default { ... }` for the config object and `import { GenerateSW } from 'workbox-webpack-plugin';`.

Service Worker failed to register: A bad HTTP response code (404) was received when fetching the script.

The generated service worker file (e.g., `sw.js` or `sw.bundle.js`) is not accessible at the expected URL, often due to incorrect Webpack output publicPath or incorrect `publicPath` in `workbox-webpack-plugin` options.

fix

Verify your Webpack `output.publicPath` is correctly configured to point to the root of your application, and ensure the `swDest` option in `GenerateSW` or `InjectManifest` matches the public URL where the service worker will be served (e.g., `publicPath: '/'`, `swDest: 'sw.js'`).

Upgrade

Version history

7.4.0latest on npm

Audit

Dependencies

webpackrequiredRequired as a peer dependency for Webpack build integration.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/googlechrome/workbox ↗

packagehttps://www.npmjs.com/package/workbox-webpack-plugin ↗

homepagehttps://developers.google.com/web/tools/workbox ↗