Registry / http-networking / workbox-cli

workbox-cli

library0.1.5jsnpmunverified

workbox-cli is the command-line interface for the Workbox library, a set of JavaScript modules for adding offline support to web applications. It streamlines the process of generating service workers and precaching assets, simplifying the integration of Workbox into projects without requiring complex custom build scripts. The current stable version is 7.4.0. Workbox CLI's release cadence generally aligns with the broader Workbox project, seeing frequent patch updates for dependency maintenance and security, with major versions introducing significant changes like Node.js version bumps. Its key differentiator is providing a user-friendly entry point for common Workbox use cases through a series of interactive wizards and declarative configuration files, abstracting away the underlying `workbox-build` module for a smoother developer experience.

http-networking devops

npm install workbox-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORKBOX-CLI

workbox-cli

http-networkingjavascriptv0.1.5

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.

workbox-cli (general invocation)

✓ npx workbox-cli <command> [options]

Workbox CLI is primarily used via its command-line interface for tasks like service worker generation. Direct JavaScript `import` or `require` of this package is not intended for typical use cases.

generateSW

✓ npx workbox-cli generateSW ./workbox-config.js

✗ import { generateSW } from 'workbox-cli'

This command uses a configuration file to automatically generate a new service worker, including precaching assets based on specified patterns.

injectManifest

✓ npx workbox-cli injectManifest ./workbox-config.js

✗ import { injectManifest } from 'workbox-cli'

This command takes an existing service worker file and injects a precache manifest into it, allowing for more custom service worker logic.

wizard

✓ npx workbox-cli wizard

✗ import { wizard } from 'workbox-cli'

The wizard command provides an interactive, guided process to help you create a basic Workbox configuration file tailored to your project.

This quickstart demonstrates how to use `workbox-cli` with a configuration file to generate a service worker that precaches assets and handles runtime caching for Google Fonts.

/* workbox-config.js */ module.exports = { globDirectory: 'dist/', globPatterns: [ '**/*.{html,js,css,png,jpg,gif,svg,json,webmanifest}' ], swDest: 'dist/sw.js', clientsClaim: true, skipWaiting: true, navigateFallback: '/index.html', runtimeCaching: [{ urlPattern: new RegExp('^https://fonts.(?:googleapis|gstatic).com/'), handler: 'StaleWhileRevalidate', options: { cacheName: 'google-fonts', expiration: { maxEntries: 50, maxAgeSeconds: 60 * 60 * 24 * 30, }, }, }], }; // To run this example: // 1. Create a directory named 'dist' in your project root. // 2. Place some static files (e.g., index.html, style.css) into 'dist'. // 3. Save the above content as 'workbox-config.js' in your project root. // 4. Open your terminal in the project root and run: // npx workbox-cli generateSW workbox-config.js // This will generate 'dist/sw.js' based on your configuration.

workbox --version

Debug

Known issues

breakingWorkbox v7.0.0 introduced a breaking change by raising the minimum required Node.js version. Projects using older Node.js versions will encounter errors.

fix

Upgrade your Node.js environment to version 20.0.0 or higher. For NVM users, run `nvm install 20 && nvm use 20`.

affects: >=7.0.0

gotchaThe Workbox CLI undergoes regular dependency updates, some of which address critical vulnerabilities. Running outdated versions can expose your project to known security risks.

fix

Always use the latest stable version of `workbox-cli` by regularly updating your installed package (`npm update workbox-cli` or `yarn upgrade workbox-cli`) or by using `npx workbox-cli` which fetches the latest version.

affects: <7.4.0

gotchaIncorrectly configuring `globDirectory` or `swDest` in your Workbox configuration file can lead to service workers not being generated, or generated in an unexpected location, failing to serve assets correctly.

fix

Ensure `globDirectory` points to the correct build output directory of your project, and `swDest` specifies a valid path within that directory (e.g., 'build/sw.js' if `globDirectory` is 'build/'). Always verify the paths relative to your project root.

affects: >=6.0.0

Errors

Common errors & fixes

Error: Minimum required Node.js version is 20.0.0. You are running v18.17.0.

Attempting to run `workbox-cli` version 7 or higher with an unsupported Node.js version.

fix

Upgrade Node.js to version 20.0.0 or newer. Use `nvm install 20 && nvm use 20` or update your system's Node.js installation.

`workbox-cli: command not found`

The `workbox-cli` package is not installed globally or `npx` is not resolving the package correctly.

fix

Either install it globally (`npm install -g workbox-cli`) or use `npx workbox-cli <command>` to execute the latest version without global installation.

Error: [workbox-build] 'globDirectory' must be a valid directory.

The `globDirectory` path specified in the `workbox-config.js` does not exist or is incorrect.

fix

Verify that the `globDirectory` property in your configuration file points to an actual, existing directory where your static assets are located.

Upgrade

Version history

0.1.5latest on npm

Audit

Dependencies

noderequiredRuntime environment for executing the CLI commands.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

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

packagehttps://www.npmjs.com/package/workbox-cli ↗

homepagehttps://developer.chrome.com/docs/workbox ↗