Adding a new package

The following are the steps that need to be taken in order to create a brand-new package as part of the Workbox monorepo. Note that some of the steps assume that you're creating a package that runs in the service worker and can be loaded by workbox-sw; if you're creating a node-based build tool, or a package that runs in the window context, you'll only need to follow a subset of these.

Many pieces of the build and test infrastructure will automatically pick up new packages without you having to explicitly enable anything, by virtue of a wildcard match for anything under the packages/ directory.

New service worker packages only

1. Update packages/workbox-build/package.json to include a reference to the new package in dependencies.

2. Update MODULE_KEY_TO_NAME_MAPPING in packages/workbox-sw/controllers/WorkboxSW.mjs to include a mapping between the workbox.* namespace and the underlying package name. This mapping should match the workbox.browserNamespace metadata found in the new package's package.json, e.g.:

"workbox": {
  "browserNamespace": "workbox.somethingNew",
  "packageType": "browser"
}

3. Update various tests that check the number/names of the packages that workbox-build knows about to account for the new packages' files:

   • test/workbox-build/node/dependency-check.js
   • test/workbox-build/node/entry-points/generate-sw.js
   • test/workbox-build/node/lib/copy-workbox-libraries.js
   • (potentially others)

4. If this is a package that you expect most developers will use, then include it in infra/pr-bot/aggregate-size-plugin.js so that it's size is aggregated into the total size of the Workbox runtime.

All new packages

1. Pre-publish a v0.0.1 release to npm in order to claim the package name, prior to committing code to GitHub! This will prevent malicious folks from grabbing our new package name before we get a chance to cut an official Workbox release.

2. After publishing to npm, ensure that other members of the workboxjs organization have read-write access for the new project:

   • Visit the WorkboxJS npm teams page.
   • Grant access to the newly published package using the "+ Add Existing Package" button.