npm install vs npm ci for CI/CD dependency consistency

Deterministic Builds in CI/CD

For automated pipelines, npm ci is the correct choice for ensuring dependency consistency. While npm install is designed for local development where version ranges may be updated, npm ci enforces a strict match with the package-lock.json. If the lockfile and package.json are out of sync, npm ci will fail the build rather than modifying the lockfile, preventing "dependency drift" between environments.

Resolution Overhead in Large Dependency Trees

In projects with over 5,000 packages, the resolution phase of npm install introduces significant CPU and memory overhead. This is because npm install must evaluate version ranges, check for compatible updates, and calculate a valid dependency graph. In contrast, npm ci skips the resolution logic entirely, extracting the exact versions from the lockfile. Although npm ci deletes the existing node_modules folder, the time saved by bypassing the resolution phase typically outweighs the I/O cost of the clean installation in large-scale trees.

Peer Dependency Handling and Manual Lockfile Changes

The behavior regarding peer dependency conflicts differs based on the command's goal:

• npm install: Attempts to resolve conflicts by updating the dependency tree or the lockfile to satisfy the peer requirements.
• npm ci: Does not attempt to resolve conflicts. If a manually modified lockfile contains a peer dependency conflict that cannot be satisfied by the locked versions, the installation will fail.

This rigidity ensures that developers must resolve conflicts locally and commit a verified lockfile before the code reaches the pipeline.

Implementation Steps for CI/CD

1. Ensure package-lock.json is committed to version control.
2. Configure the CI pipeline to execute npm ci instead of npm install.
3. Verify the build fails if the lockfile is missing or mismatched.

Verification

To verify the environment is deterministic, you can run the following in a clean shell:

# Generate a lockfile locally first
npm install

# Run clean install in CI environment
npm ci

Note: If your project uses a custom registry or private proxy, please specify if the CI environment has different authentication scopes, as this can affect installation failure rates.