We all know about npm install, but some of you might not know about npm ci (clean install). This command is super useful in CI environments. Using npm ci can make your build pipeline faster and more stable. Learning these commands helps you understand more about npm install and why package-lock.json & package.json are so important. Knowing these basics gives you better clarity.
What is npm ci (clean install)?
npm ci is a command used to install dependencies in a project, focusing on speed and consistency. It's specially helpful in continuous integration (CI) setups.
How is it different from npm install?
Faster Installation:
npm ciskips updating thepackage-lock.json. It strictly follows the lock fileโs dependencies, making the process quicker and predictable.Strict Lock File:
It uses the exact dependency versions in thepackage-lock.json. If thereโs any mismatch betweenpackage.jsonandpackage-lock.json, it will throw an error. This ensures all environments (local, CI, production) use the same dependencies.Clean Slate:
Before installing,npm cideletes thenode_modulesfolder to start fresh.
When to Use?
- CI/CD Pipelines: Perfect for automated build systems where you need fast, consistent installs without updates.
-
Trusted Lock File: Use when you want dependencies to exactly match whatโs defined in the
package-lock.json.
Here is a quick reference table that opens up many hidden areas for you by understanding the key differences between npm install and npm ci:
| Step | npm install | npm ci |
|---|---|---|
| 1. Dependency Resolution | Resolves dependencies based on package.json and updates package-lock.json to reflect any changes. |
Skips resolution, using exact versions in package-lock.json without referring to package.json for version ranges. |
| 2. Version Compatibility Check | Ensures dependencies meet specified ranges in package.json, updates package-lock.json if needed. |
Requires that versions in package-lock.json match package.json exactly; fails if out of sync. |
3. node_modules Cleanup |
Installs only missing or updated packages without removing node_modules, keeping existing dependencies that are unchanged. |
Deletes node_modules entirely before reinstalling everything fresh. |
| 4. Lockfile Generation | Generates a new package-lock.json if none exists; updates it based on package.json changes. |
Requires an existing package-lock.json and fails if missing or out of sync with package.json. |
5. Sync with package.json |
Updates package-lock.json to align with any new, modified, or removed dependencies in package.json. |
Requires package-lock.json to match package.json exactly; if not, it fails, ensuring strict version consistency. |
| 6. Installation of Dependencies | Installs dependencies into node_modules based on package.json, updating package-lock.json with any resolved versions. |
Installs dependencies exactly as specified in package-lock.json, ensuring reproducibility and ignoring version ranges in package.json. |
| 7. Lockfile Modifications | Modifies package-lock.json to match package.json changes automatically. |
Does not modify package-lock.json regardless of package.json changes, maintaining consistency. |
| 8. Network Requests | Fetches any new dependencies or updates not found in node_modules. |
Only fetches dependencies listed in package-lock.json, skipping additional checks. |
| 9. Speed | Slower, due to dependency resolution, potential lockfile updates, and incremental installs. | Faster, using only package-lock.json for exact installs, minimizing processing. |
| 10. Priority of Files |
package.json takes priority: dependencies are resolved based on it, and package-lock.json is updated to reflect any changes. |
package-lock.json takes priority: installs use exact versions from it, ignoring package.json except to check for sync errors (failing if they donโt match). |
| 11. Ideal Use Case | Best for local development when modifying or adding dependencies. | Best for CI/CD environments, production, or anytime consistency, speed, and reproducibility are essential. |
Top comments (0)