From 610564a5083eb807eb1556e1eea7b1383841fa86 Mon Sep 17 00:00:00 2001 From: Max Black Date: Sat, 29 Nov 2025 17:51:52 -0800 Subject: [PATCH] docs(npm-install): explain package-lock.json behavior during install --- docs/lib/content/commands/npm-install.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/lib/content/commands/npm-install.md b/docs/lib/content/commands/npm-install.md index e1e17e6d70466..7163f928de109 100644 --- a/docs/lib/content/commands/npm-install.md +++ b/docs/lib/content/commands/npm-install.md @@ -19,6 +19,16 @@ 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 verifies that `package.json` and `package-lock.json` are in sync: + +* **If they match:** npm uses the versions specified in `package-lock.json` to ensure reproducible builds across environments. + +* **If they don't match:** If you've modified `package.json` so that the version ranges no longer match what's in `package-lock.json`, npm treats it as if you ran `npm install @` for the changed packages. It will update `package-lock.json` with the new resolved versions that satisfy the updated `package.json` ranges. + +In essence, `package-lock.json` locks your dependencies to specific versions, but `package.json` is the source of truth for acceptable version ranges. When they agree, the lockfile wins. When they conflict, `package.json` wins and the lockfile is updated. + A `package` is: * a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file