How to use the command 'npm ci' (with examples)

The npm ci command is a specialized command in the Node.js package manager, npm, tailored for automated environments such as Continuous Integration (CI) and Continuous Deployment (CD). This command ensures a clean and consistent installation of project dependencies specified in a package-lock.json or npm-shrinkwrap.json file. Unlike npm install, npm ci is designed to enhance predictability and reliability by replicating an exact environment previously established, which is crucial in automation setups.

Use case 1: Clean Install Project Dependencies

Code:

npm ci

Motivation:

In automated environments, such as CI pipelines, it’s imperative to install project dependencies in a manner that ensures consistency with the tested environment. Using npm ci guarantees that the installed modules match exactly with those listed in the package-lock.json file, eliminating the risk of mismatched dependency versions. This leads to more predictable deployments and helps maintain stability and compatibility across multiple environments.

Explanation:

• npm: The command-line interface for interacting with the Node.js package ecosystem.
• ci: Stands for “clean install.” It installs modules based on the exact versions listed in the package-lock.json or equivalent file. It deletes the node_modules folder before starting the installation to ensure no leftovers from previous installations.

Example Output:

added 1253 packages, and audited 1253 packages in 10s

1253 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Use case 2: Install Project Dependencies while Omitting a Dependency Type

Code:

npm ci --omit=dev

Motivation:

When setting up an environment for production, it’s often unnecessary and sometimes problematic to include development dependencies, which are only required during the development phase and not in production. By using the --omit=dev flag, developers can exclude these dependencies, resulting in a leaner, production-ready deployment. This can also help in reducing the size of the deployed application and minimizing potential security risks associated with unused packages.

Explanation:

• ci: As previously mentioned, stands for “clean install,” ensuring a consistent installation.
• --omit=dev: This flag tells npm ci to exclude all packages listed under the “devDependencies” in the package.json. Other options include “optional” and “peer” for excluding optional and peer dependencies, respectively.

Example Output:

added 1046 packages, and audited 1046 packages in 8s

1046 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Use case 3: Install Project Dependencies without Running Pre-/Post-Scripts

Code:

npm ci --ignore-scripts

Motivation:

Pre- and post-scripts defined in the package.json are often used for tasks such as compiling code, running tests, or performing setup actions. However, in certain system environments or production deployments, executing these scripts automatically can be undesirable or even harmful. Using --ignore-scripts helps skip these hooks, allowing for a more controlled or faster installation without any additional process overhead or potential failure due to script misconfigurations.

Explanation:

• ci: Ensures a clean and consistent installation.
• --ignore-scripts: Instructs npm to skip executing any pre- or post-install scripts defined in the package.json, thus focusing exclusively on dependency installation without side effects from other scripts.

Example Output:

added 1253 packages, and audited 1253 packages in 9.5s

1253 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Conclusion:

The npm ci command is a powerful tool within the npm ecosystem designed for precision and efficiency in dependency management, particularly in automated environments. Each use case illustrates a unique scenario where npm ci brings value by ensuring a predictable, secure, and optimized setup of project dependencies. Whether it’s maintaining consistency across builds, tailoring installations for production, or ensuring installations devoid of scripts, npm ci provides a robust solution for developers seeking to streamline their workflows.