Workbox CLI

7.4.0 · active · verified Wed Apr 22

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.

Common errors

```
Error: Minimum required Node.js version is 20.0.0. You are running v18.17.0.
```
cause 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`
```
cause 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.
```
cause 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.

Warnings

breaking Workbox 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`.
gotcha The 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.
gotcha Incorrectly 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.

Install

npm install workbox-cli npm
yarn add workbox-cli yarn
pnpm add workbox-cli pnpm

Imports

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
wrong:
```
import { generateSW } from 'workbox-cli'
```
correct:
```
npx workbox-cli generateSW ./workbox-config.js
```
This command uses a configuration file to automatically generate a new service worker, including precaching assets based on specified patterns.
injectManifest
wrong:
```
import { injectManifest } from 'workbox-cli'
```
correct:
```
npx workbox-cli injectManifest ./workbox-config.js
```
This command takes an existing service worker file and injects a precache manifest into it, allowing for more custom service worker logic.
wizard
wrong:
```
import { wizard } from 'workbox-cli'
```
correct:
```
npx workbox-cli wizard
```
The wizard command provides an interactive, guided process to help you create a basic Workbox configuration file tailored to your project.

Quickstart

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.

view raw JSON →