npm ci and npm install look interchangeable but aren't: npm ci deletes node_modules first and fails outright if package.json and the lockfile disagree, while npm install happily updates the lockfile to reconcile them. That distinction is exactly why CI pipelines should use ci, not install, confirmed against this app's own package-lock.json/package.json pairing.
npmpackage-jsonsemverlockfilesworkspaces
Curated Video Reference
YouTube
Hand-picked video lecture to deepen your understanding of Packages, npm & Publishing
1. What does the ^ (caret) prefix in a semver range like ^4.18.2 allow?
Interview Questions
2 questions
Cheatsheet
Download-ready reference
Cheatsheet
package.json key fields:
"type" → CJS vs ESM default for .js files (see Modules & File System)
"main" → legacy single entry point
"exports" → precise map: separate require()/import files, subpaths
"engines" → Node version requirement (WARNS, doesn't block by default)
"bin" → CLI command → script mapping
SEMVER ranges (MAJOR.MINOR.PATCH):
4.18.2 → exact only
~4.18.2 → PATCH updates only (4.18.x)
^4.18.2 → MINOR + patch updates (4.x.x), same MAJOR, npm's default
LOCKFILE (package-lock.json): pins EXACT resolved versions +
integrity hashes for the WHOLE tree, including transitive deps.
ALWAYS commit it.
npm install → resolves ranges, UPDATES lockfile if needed, forgiving
npm ci → deletes node_modules, reads lockfile ONLY, FAILS on
any package.json/lockfile mismatch, use in CI/prod
⚠️ npm ci ≠ npm install, not interchangeable. ci = strict + fast.
workspaces: ["packages/*"] → monorepo: one install, shared deps
hoisted, internal packages symlinked together.
npm audit scans the LOCKFILE's dependency tree for known
vulnerabilities (see Security).
The beginner framing: every Node.js project has a package.json, but beyond "name", "version", and a dependencies list, most of its fields go unexamined until something breaks and forces a closer look. Understanding them ahead of time avoids that.
The precise mental model: package.json is both a manifest (metadata, entry points, dependency declarations) and a configuration surface (scripts, engine constraints, module resolution behavior), and several of its fields directly control how Node resolves and loads the package's code.
"type", determines whether .js files in this package are CommonJS or ESM by default (covered in depth in Modules & File System).
"exports", the modern, more precise successor to "main": an explicit map controlling exactly which files consumers are allowed to import/require, and which module system they get for each, this is what enables a single package to correctly serve both require() and import consumers with different files.
, declares the Node version range the package requires; npm warns (doesn't block by default) if the installed version doesn't satisfy it.
^ (caret) is npm's default when you npm install <package>, it assumes the package author follows semver honestly (breaking changes only in major version bumps), which is a convention, not something npm can enforce.
Lockfiles: reproducibility across machines and time#
package.json's ^4.18.2 is a range, it doesn't pin an exact version. package-lock.json pins the exact resolved version (and a cryptographic integrity hash) for every package in the entire dependency tree, including transitive dependencies your package.json never mentions directly. Without a committed lockfile, two different machines running npm install against the same package.json at different times could genuinely resolve different actual versions, the lockfile is what guarantees everyone (and CI) gets the identical dependency tree.
npm install # reads package.json, resolves ranges, UPDATES the lockfile if needednpm ci # reads package-lock.json ONLY, deletes node_modules first, # FAILS OUTRIGHT if package.json and the lockfile disagree
This is the distinction most easily missed: npm install is forgiving, if package.json and package-lock.json are slightly out of sync, it reconciles them (updating the lockfile) and proceeds. npm ci is strict and fast, it does a clean install using only what's already locked, and refuses to proceed at all if there's a mismatch, rather than silently resolving one. This is exactly why npm ci is the correct choice for CI pipelines and production builds: a mismatch there should be a loud, immediate failure, not something silently patched over mid-build.
The "workspaces" field lets a single npm install at the repo root manage dependencies for multiple packages living in one repository, hoisting shared dependencies to a single top-level node_modules where possible and symlinking internal packages to each other, the standard mechanism behind most JavaScript monorepos.
A repo's package.json has "express": "^4.18.0" in dependencies, but the committed package-lock.json still references express@4.17.9 from before a recent manual package.json edit that bumped the range.
npm ci
Does this succeed, silently resolve to a version satisfying ^4.18.0, or fail?
Solution
It fails outright, npm ci requires package.json and package-lock.json to already agree; it does not resolve or reconcile a mismatch the way npm install would. The error explicitly calls out the discrepancy between the declared range and what's locked. The fix is running npm install locally (which updates the lockfile to satisfy the new range), committing the updated package-lock.json, and only then will npm ci succeed again, this is a deliberate design choice, not a limitation, since it prevents a stale lockfile from silently drifting from what package.json actually declares.
"exports" and "type" directly control the module-resolution behavior covered in Modules & File System, this topic is where those package.json fields get their dedicated treatment, having only been introduced briefly there. And npm audit, mentioned in Security as a way to catch known dependency vulnerabilities, operates directly against the dependency tree this topic's lockfile discussion describes, the lockfile is what audit actually scans.
# CI config- run: npm install # ❌ can silently update the lockfile mid-build, masking drift
CI should use npm ci specifically, its strictness (failing loudly on mismatch, guaranteed clean node_modules) is exactly the property you want in an automated, reproducible build environment.
# .gitignorepackage-lock.json # ❌ defeats the entire purpose of having a lockfile
An uncommitted lockfile means every fresh npm install (including in CI) can resolve different transitive dependency versions, the exact non-reproducibility a lockfile exists to prevent.
3. Assuming ^ ranges never introduce breaking changes#
{ "dependencies": { "some-package": "^2.4.0" } }
^ relies on the package author correctly following semver, npm cannot enforce that a "minor" release truly contains no breaking changes; a poorly maintained package can break something even within a ^-allowed update.
Always commit package-lock.json, it's part of the project's reproducibility guarantee, not a disposable artifact.
Use npm ci in CI/production builds, npm install for local development where you're actively adding/updating dependencies.
Understand "exports" before publishing a package meant to support both require() and import consumers, "main" alone doesn't give you that precision.
Pin "engines" to the actual Node version range your code depends on (e.g., if using a feature confirmed stable only in a specific version), so consumers get an explicit signal rather than a silent incompatibility.
npm ci is typically faster than npm install for a clean install, specifically because it skips the dependency-resolution step entirely, it trusts the lockfile completely rather than re-resolving ranges, which is part of why it's the right default for CI beyond just its strictness.
Workspaces' dependency hoisting (sharing a single top-level node_modules across packages where possible) reduces both install time and disk usage compared to each package in a monorepo maintaining a fully separate node_modules.
"engines"
"bin", maps a command name to a script, making the package runnable as a CLI tool once installed (globally or via npx).
4.18.2
Minor AND patch updates, new features, no breaking changes (by semver convention)
>=4.18.2
Any version 4.18.2 or higher, unbounded
Rarely what you actually want
===
rMinor
&&
vPatch
<
rPatch)
return
false
;
return true; // same major, minor+patch >= the range's minor+patch
}
console.log(satisfiesCaret("4.18.5", "^4.18.2")); // true, minor+patch bump, same major
console.log(satisfiesCaret("4.17.0", "^4.18.2")); // false, minor went DOWN
console.log(satisfiesCaret("5.0.0", "^4.18.2")); // false, major changed