{"id":17077,"library":"workbox-cli","title":"Workbox CLI","description":"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.","status":"active","version":"7.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/googlechrome/workbox","tags":["javascript","workbox","workboxjs","service worker","caching","fetch requests","offline","cli"],"install":[{"cmd":"npm install workbox-cli","lang":"bash","label":"npm"},{"cmd":"yarn add workbox-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add workbox-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment for executing the CLI commands.","package":"node","optional":false}],"imports":[{"note":"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.","symbol":"workbox-cli (general invocation)","correct":"npx workbox-cli <command> [options]"},{"note":"This command uses a configuration file to automatically generate a new service worker, including precaching assets based on specified patterns.","wrong":"import { generateSW } from 'workbox-cli'","symbol":"generateSW","correct":"npx workbox-cli generateSW ./workbox-config.js"},{"note":"This command takes an existing service worker file and injects a precache manifest into it, allowing for more custom service worker logic.","wrong":"import { injectManifest } from 'workbox-cli'","symbol":"injectManifest","correct":"npx workbox-cli injectManifest ./workbox-config.js"},{"note":"The wizard command provides an interactive, guided process to help you create a basic Workbox configuration file tailored to your project.","wrong":"import { wizard } from 'workbox-cli'","symbol":"wizard","correct":"npx workbox-cli wizard"}],"quickstart":{"code":"/* workbox-config.js */\nmodule.exports = {\n  globDirectory: 'dist/',\n  globPatterns: [\n    '**/*.{html,js,css,png,jpg,gif,svg,json,webmanifest}'\n  ],\n  swDest: 'dist/sw.js',\n  clientsClaim: true,\n  skipWaiting: true,\n  navigateFallback: '/index.html',\n  runtimeCaching: [{\n    urlPattern: new RegExp('^https://fonts.(?:googleapis|gstatic).com/'),\n    handler: 'StaleWhileRevalidate',\n    options: {\n      cacheName: 'google-fonts',\n      expiration: {\n        maxEntries: 50,\n        maxAgeSeconds: 60 * 60 * 24 * 30,\n      },\n    },\n  }],\n};\n\n// To run this example:\n// 1. Create a directory named 'dist' in your project root.\n// 2. Place some static files (e.g., index.html, style.css) into 'dist'.\n// 3. Save the above content as 'workbox-config.js' in your project root.\n// 4. Open your terminal in the project root and run:\n//    npx workbox-cli generateSW workbox-config.js\n// This will generate 'dist/sw.js' based on your configuration.","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.0.0 or higher. For NVM users, run `nvm install 20 && nvm use 20`.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"The Workbox CLI undergoes regular dependency updates, some of which address critical vulnerabilities. Running outdated versions can expose your project to known security risks.","severity":"gotcha","affected_versions":"<7.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to run `workbox-cli` version 7 or higher with an unsupported Node.js version.","error":"Error: Minimum required Node.js version is 20.0.0. You are running v18.17.0."},{"fix":"Either install it globally (`npm install -g workbox-cli`) or use `npx workbox-cli <command>` to execute the latest version without global installation.","cause":"The `workbox-cli` package is not installed globally or `npx` is not resolving the package correctly.","error":"`workbox-cli: command not found`"},{"fix":"Verify that the `globDirectory` property in your configuration file points to an actual, existing directory where your static assets are located.","cause":"The `globDirectory` path specified in the `workbox-config.js` does not exist or is incorrect.","error":"Error: [workbox-build] 'globDirectory' must be a valid directory."}],"ecosystem":"npm","meta_description":null}