cli icon indicating copy to clipboard operation
cli copied to clipboard

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

Open MaxBlack-dev opened this issue 1 month ago • 0 comments

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

MaxBlack-dev avatar Nov 30 '25 01:11 MaxBlack-dev