npm ci for Reproducible Installs
You'll learn why npm ci is the gold standard for consistent, reliable installs in CI/CD pipelines.
What Is npm ci?
While npm install is flexible and convenient for local development, npm ci (short for "clean install") is designed for automated environments where reproducibility matters more than convenience. It's stricter, faster, and guarantees that every installation produces exactly the same node_modules tree.
Think of npm install as a chef improvising with available ingredients, while npm ci follows the recipe to the letter every single time—no substitutions allowed.
How npm ci Differs
When you run npm ci:
- Deletes
node_modulesentirely before installing (always starts fresh) - Requires
package-lock.jsonto exist (fails without it) - Never modifies
package-lock.json(read-only operation) - Installs exact versions from the lockfile, no resolution attempts
- Fails fast if there's any mismatch between
package.jsonandpackage-lock.json
This strictness prevents the "works on my machine" problem. Your CI server, your teammate's laptop, and production will all have identical dependencies.
When to Use npm ci
Use npm ci in:
- CI/CD pipelines (GitHub Actions, Jenkins, etc.)
- Docker image builds
- Deployment scripts
- Any automated environment requiring consistency
Use npm install for:
- Local development
- Adding/updating packages
- Interactive workflows
Key Takeaway: npm ci sacrifices flexibility for reproducibility—use it in automated builds to guarantee every environment installs the exact same dependency tree from your lockfile.