`npm ci` validates `package-lock.json` and could fail to resolve

[fritzy]

What and Why

Starting in npm@8.6.0, the npm ci command validates that the package-lock.json is consistent with the developer defined package.json. Previously, npm ci would blindly install whatever was in the lock file. We implemented this bugfix for several reasons.

• overrides defined in the package.json could be ignored
• invalid trees, including unresolvable peer dependencies would be installed
• developer configuration options were ignored
• an attacker could make subtle changes to package-lock.json

Implementing this fix resolves an entire class of bugs where invalid dependency trees are installed. As a result, a number of CI workflows started producing errors rather than install invalid dependency trees. This has been a controversial fix.

Ways That npm ci Validation Can Fail

• different configuration between npm install and npm ci like --legacy-peer-deps or --force
• manually edited package-lock.json files
• edits to the package.json like changed deps and overrrides without generating a new package-lock.json with npm install
• an npm install bug that produced an incorrect tree or incorrect package-lock.json in a previous version

Resolving Your Project

In some cases, simply generating a new package-lock.json with npm install will fix the issue, depending the reason the package-lock.json is out of sync with your package.json.

If you're using --legacy-peer-deps with npm install, make sure you also use it with npm ci, perhaps by setting it in your .npmrc.

More complicated cases involve incorrectly resolved peer dependencies. This is common when using React 18, as many packages have semver ranges not including react@18, but still happen to mostly work. This is best resolved through package.json overrides.

Discussions and References

• Most recently npm CLI issue #4998. I made this statement.
• Previous npm CLI issue #4664 in which @nlf makes some clarifying statment.
• This change was implemented in pull request #4666
• Thoughts on bugfixes vs. breaking changes

Next Steps

If you find a bug related to npm ci validation of package-locks.json beyond what is covered above, please file a bug report.

If you would like to suggest changes, please use our RFC process. You can create an RRFC, or participate in discussions on that repo.