Keep package-lock.json committed, leave npm’s package-lock setting enabled, and use npm ci when an install must reproduce the committed dependency tree without changing it. Use npm install for deliberate dependency work, then review the manifest and lockfile changes before committing.
Keep the lockfile enabled and commit it
package-lock.json records the dependency tree npm generated so teammates, deployment environments, and CI can install the same resolved dependencies. Commit it alongside package.json rather than relying on each machine to resolve the manifest’s version ranges independently. See npm’s package-lock.json documentation.
The npm package-lock setting is enabled by default. Avoid setting it to false for routine project work: with that setting, npm ignores package lockfiles during installs and does not write one when saving is enabled. If the project needs to state the default explicitly, put this in its .npmrc:
package-lock=trueChoose the install command for the job
| Command or setting | Effect | Use it when |
|---|---|---|
npm install |
Uses the lockfile when its resolved versions satisfy the manifest’s ranges; dependency work can update the manifest and lockfile. | Setting up a project or intentionally adding or updating dependencies. |
npm ci |
Requires a lockfile, rejects a mismatch between the lockfile and package.json, removes the existing node_modules directory, and does not write either manifest or lockfile. |
Installing the committed dependency state from scratch in CI, deployment, or a local clean install. |
Because npm ci removes node_modules, do not use it when you need to preserve the existing installation directory. npm describes its installs as frozen: npm ci documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Make installs consistent across machines
Some npm options change the shape of the dependency tree. If the lockfile was created using options such as legacy-peer-deps or install-links, use the same options when running npm ci. Otherwise, a clean install may not reproduce the tree represented by the lockfile. A committed project-level .npmrc can preserve these settings for developers and CI. The npm ci configuration notes document this requirement.
For example, if the project intentionally created its lockfile with legacy peer-dependency handling, its .npmrc could include:
legacy-peer-deps=trueAlign npm versions in local development and CI where practical. npm associates lockfile version 1 with npm 5/6, version 2 with npm 7/8, and version 3 with npm 9 and later. npm can use data from lockfiles made for other generations, but older formats may lack metadata that npm then fetches, and installation can update the lockfile. When changing npm generations, inspect the resulting lockfile diff. See the lockfile format documentation.
Make dependency changes deliberately
-
Use
npm installwhen you intend to add, update, or otherwise change dependencies. If you want newly added dependencies recorded as exact versions inpackage.json, use--save-exact.The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Rank #3
-
Review changes to both
package.jsonandpackage-lock.json. Confirm that the resolved dependency changes are expected before committing them. -
Run the project’s normal tests and checks against the updated dependency tree before merging.
npm documents --save-exact and install behavior in its npm install documentation.
Decide how peer-dependency conflicts should behave
By default, npm may resolve certain peer-dependency conflicts and issue a warning. Set strict-peer-deps=true when conflicts should instead stop the install for review. This can prevent a questionable peer resolution from passing unnoticed, but it also means installs fail until the conflict is addressed. The setting is documented for npm ci and npm install.
To apply the choice consistently at project level, add this line to the project’s .npmrc:
strict-peer-deps=trueTreat security fixes as dependency changes
npm audit fix applies remediations using npm install behavior, so it can change the dependency tree. Review its lockfile diff and run the project’s normal verification before accepting the change. If you want to update the lockfile without modifying the current node_modules, use npm audit fix --package-lock-only. See the npm audit documentation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
