tools/README.node_modules.md
Cockpit uses Node.js and the npm package manager to build its code and run browser integration tests. These are not used at runtime or when building/installing from a release tarball.
package.json has two npmjs package
lists: runtime dependencies like PatternFly or React which are included into
Cockpit's pages and run in the browser; and devDependencies like esbuild or linters
which are only used at build/test time.
When building from Git, the node_modules/ directory is managed as a git
submodule from the node-cache repository in the same project as the main
repository (ie: cockpit-project/node-cache). That means that normal builds
won't need to run npm install. Checking out the correct version of the
node_modules directory is managed by the script tools/node-modules, which
is automatically invoked from the build system on an as-needed basis, and has
good caching. You can also do a recursive git checkout, if you'd prefer to
build in a no-network environment, but you'll lose the caching benefits.
The gitlink for node_modules/ is always kept in sync with the package.json
file used to fetch that set of modules with npm install.
If you modify package.json, the node_modules will need to be regenerated,
and a new commit recorded. That can be managed locally by running
tools/node_modules install
which will produce a commit which is available for local testing.
When you are ready to open a pull request with your changes, push the newly
created node_modules commit to the cache by running
tools/node_modules push
Then create a pull request with your package.json and node_modules changes.
Each pull request runs the reposchutz workflow to ensure that the branch is consistent wrt. package.json and node_modules/. This is purely read-only and does not need any secrets.
This section documents the way to setup the node-cache repository on GitHub. All projects in the cockpit-project organization share the same repository.
Each project's "release" and "dependabot" workflows need write access to the node-cache repository for taggging releases or rebuilding node_modules/ respectively. These happen via workflow environments, whose deploy keys are set up in bot's setup-deploy-keys script.
For other projects/orgs or forks, you can create a node-cache repository from
scratch manually (unless you want to fork/re-use setup-deploy-keys):
node-cache repository under the same project as the main
repository (or fork it)README. At least one commit on a
named branch needs to be present in order for the GitHub web UI to function
properly (eg: generate diffs, show tree contents, etc.)ssh-keygen -t ed25519 -C 'node-cache deploy' -f "${XDG_RUNTIME_DIR}/deploy-key" -N ''node-cache upload in the "environments" settings of the
primary repository.deploy-key to the node-cache upload
environment as a secret with the name NODE_CACHE_DEPLOY_KEYdeploy-key.pub as a deploy key to node-cache with
write access enabled:
https://github.com/cockpit-project/node-cache/settings/keys/newrm ${XDG_RUNTIME_DIR}/deploy-key*