docs(npm-install): explain package-lock.json behavior (#8797)

MaxBlack-dev · Max Black · web-flow · commit 5552e465125c · 2025-12-17T09:44:10.000-08:00
## Description This PR adds documentation explaining how `npm install` behaves with respect to `package.json` and `package-lock.json`, a common source of confusion for npm users. ## Changes - Added a new section "How `npm install` uses `package-lock.json`" to the `npm install` documentation - Explained the two scenarios: - When `package.json` and `package-lock.json` are in sync: exact versions from lockfile are installed - When they conflict: `package.json` wins and `package-lock.json` is updated - Clarified that `package.json` is the source of truth for version ranges, while `package-lock.json` locks to specific versions - Noted the relationship to `npm ci` behavior ## Context The npm install documentation previously didn't explain how it handles the interaction between `package.json` and `package-lock.json`. Users were confused about when versions from the lockfile are used versus when they're updated. This PR incorporates the explanation from Kat Marchán that was referenced in the issue to provide clear guidance. Closes #4866 Co-authored-by: Max Black <husivm@google.com>
diff --git a/docs/lib/content/commands/npm-install.md b/docs/lib/content/commands/npm-install.md
@@ -19,6 +19,18 @@ If the package has a package-lock, or an npm shrinkwrap file, or a yarn lock fil
 
 See [package-lock.json](/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/commands/npm-shrinkwrap).
 
+#### How `npm install` uses `package-lock.json`
+
+When you run `npm install` without arguments, npm compares `package.json` and `package-lock.json`:
+
+* **If the lockfile's resolved versions satisfy the `package.json` ranges:** npm uses the exact versions from `package-lock.json` to ensure reproducible builds across environments.
+
+* **If the ranges don't match:** npm resolves new versions that satisfy the `package.json` ranges and updates `package-lock.json` accordingly. This happens when you modify version ranges in `package.json` (e.g., changing `^7.0.0` to `^8.0.0`). Note that changing a range within the same major version (e.g., `^7.0.0` to `^7.1.0`) will only update the metadata in the lockfile if the currently installed version still satisfies the new range.
+
+In essence, `package-lock.json` locks your dependencies to specific versions, but `package.json` is the source of truth for acceptable version ranges. When the lockfile's versions satisfy the `package.json` ranges, the lockfile wins. When they conflict, `package.json` wins and the lockfile is updated.
+
+If you want to install packages while ensuring that `package.json` is not modified and that both files are strictly in sync, use [`npm ci`](/commands/npm-ci) instead.
+
 A `package` is:
 
 * a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file
