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

[MaxBlack-dev]

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

[wraithgar]

This seems to contradict itself, it does not install the exact versions in package-lock if the package-lock needs to be updated.

[MaxBlack-dev]

Thanks for catching that! You're absolutely right - that was contradictory. I've updated the text to remove the confusing statement about updating package-lock.json from the "If they match" scenario, since that's already covered in the "If they don't match" case. The text now simply says npm "uses the versions specified in package-lock.json" without the contradictory language.

[wraithgar]

We may need to explain what "in sync" means. There are two ways the file can be out of sync. If I have a package.json that says semver: ^7.0.0 and I have [email protected] in my tree, but then manually change package.json to have [email protected], when I next run npm install the only change to my lockfile will be the metadata in it that mirrors the package.json

[email protected] /Users/wraithgar/Development/scratch/lock
└── [email protected]

~/D/s/lock (main|✔) $ npm pkg get dependencies.semver
"^7.0.0"
~/D/s/lock (main|✔) $ npm pkg set dependencies.semver='^7.1.0'
~/D/s/lock (main|✚1) $ npm i

up to date in 1s
~/D/s/lock (main|✚2) $ git diff
diff --git a/package-lock.json b/package-lock.json
index ad48b26..1e047f7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,7 +9,7 @@
       "version": "1.0.0",
       "license": "ISC",
       "dependencies": {
-        "semver": "^7.7.3"
+        "semver": "^7.1.0"
       }
     },
     "node_modules/semver": {
diff --git a/package.json b/package.json
index 279765d..df1e3f3 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,6 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
-    "semver": "^7.0.0"
+    "semver": "^7.1.0"
   }
 }

So the npm install <package>@<new-version> isn't wholly correct, as that would have also changed the package.json to have the new version as the new baseline for the version range.

~/D/s/lock (main|✚2) $ npm i semver@latest

up to date in 1s
~/D/s/lock (main|✚1) $ git diff 
diff --git a/package.json b/package.json
index 279765d..76daf15 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,6 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
-    "semver": "^7.0.0"
+    "semver": "^7.7.3"
   }
 }

The other way of course is if you change package.json to have a range outside of what's currently set there. If I were to change semver from "^6" to "^7" then it would be closer to as if you ran npm install package@new-version but it still wouldn't change the entry in package.json.

the TLDR is we may want to avoid an "as if" and have a little more direct (yet succinct) explanation.

[MaxBlack-dev]

You're absolutely right - I've removed the misleading "as if" analogy and provided a more direct explanation. The updated text now clarifies what "in sync" means (when lockfile versions satisfy package.json ranges) and explains the actual behavior: npm resolves new versions when ranges conflict and updates the lockfile accordingly. I also added the nuance you mentioned about metadata-only updates when changing ranges within the same major version (like ^7.0.0 to ^7.1.0). Thanks for the detailed examples!

[wraithgar]

We probably want to explain the way to NOT have npm change these files:

"If you want to install packages and ensure that these files match, and that npm will not change your package.json, consider running npm ci"

[MaxBlack-dev]

Great suggestion! I've added a paragraph at the end of the section recommending npm ci for users who want to ensure strict synchronization without npm modifying package.json. This provides a clear path for those who need that behavior.

[wraithgar]

I re-read this after having not seen it for a few days and it read very very well. Thanks for working through this.