Using per project registries

Bytesafe supports using unique registries for each project. By setting up a registry and promoting a consistent workflow users can enable reproducible package installs and builds.

For each project there are users that are responsible for managing the set of dependencies and intentionally modify the contents of a registry.

Actions associated with managing / modifying packages and registry content:

• Creating / cloning registries and initial package.json
• Adding all package versions to the registry
• Adding new packages and updating versions when required
• Adding project level .npmrc files
• Commiting package.json & package-lock.json modyfications to repository

Likewise, projects have users, testers and build processes that mainly wants to consume the contents of a registry without making any modifications.

Actions for consuming registry contents WITHOUT modifying:

• Complete install of dependencies using npm ci

Leverage a per project registry to control the available package versions for a project. Together with intentional interactions with a registry, users can make sure all team members and build chains get and use the same intended package versions.

Creating and managing a project registry

Either create a new registry or clone an existing registry to get started.

After a registry has been setup, it is important that all team members and build tools use commands and workflows that suit their needs.

Npm client offers two different commands for installing all package dependencies, npm install and npm ci.

Adding and modifying registry contents with npm install

Using npm install is the preferred option when adding new dependencies to a project, while allowing updates of the dependencies or any lockfiles.

It can be used either to install a single package version or for complete installs.

Characteristics of npm install:

• Installs dependencies defined in package.json
• If a lockfile is available, it will be used as the source to resolve the dependencies.
• If no lockfile is available, npm install will create a new package-lock.json
• If a dependency is missing or is updated as part of the install, both package.json and lockfiles will be updated as well.

As npm install can update package versions and alter lockfiles, it should not be used if the intention is to recreate an exact state and set of dependencies defined by some other members of the team. Users should prefer npm ci for such scenarios.

Adding project dependencies to a registry

Packages can be added to the registry, using either a npm client (npm install) or Bytesafe CLI.

Using an existing package.json file, all dependencies can be installed and added using npm install together with --registry flag.

If the project has an existing package-lock.json file or any other lockfile, users should delete the lockfile before running npm install. This prevents the lockfile resolving dependencies using another package source than the intended registry.

To add new project dependencies, both to the project and to the registry, use npm install together with requested package version.

Commit lockfiles and project level .npmrc files

Make sure other team members use the same dependencies, by commiting any new lockfiles or changes to your repository.

For an extra level of control, teams should add a project level .npmrc file directing package requests to a specific registry.

Installing project dependencies without modifying them

The command npm ci (clean install) is intended to be used to get a reproducible state of dependencies (node_modules) after the install.

This is preferred for build environments (CI/CD) or any scenario where a user want to install a set of dependencies as defined by other team member (testing or contribution to other members project).

Characteristics of npm ci:

• Can only be used for complete installs
• Requires existing lockfile
• Does not alter the state of either the package.json or package-lock.json files (unlike npm install)
• Compares dependencies between package.json & package-lock.json, if any discrepancies are found it exits with error.
• If node_modules exists, it will delete this folder and contents

Using npm ci is the preferred option when installing and adding packages WITHOUT any intention of modifying or altering the set of dependencies used.