Repository navigation
npm 12 - drops npm-shrinkwrap.json #1117
Description
Situation
npm 12 drops npm-shrinkwrap.json used in this repo as a published lockfile. The npm 12.0.0 changelog states:
npm shrinkwrapis removed, theshrinkwrapconfig alias is removed, andnpm-shrinkwrap.jsonis no longer loaded or honored at the project root or from inside dependency tarballs. Rename project-rootnpm-shrinkwrap.jsontopackage-lock.json; usebundleDependenciesif you need to ship a locked dependency tree.
npm install under npm 12 installs dependencies according to their SemVer range specified in package.json and ignores the lower locked versions specified in npm-shrinkwrap.json.
Example impact
If the repo is cloned and dependencies installed under npm 12, then npm test fails.
npm install ignores the locked prettier@3.6.2 and installs instead prettier@^3.6.2 from package.json which causes prettier@3.9.6 to be installed, and written into the new lockfile package-lock.json.
prettier@3.9.0 introduced formatting improvements which flagged a white space formatting issue in lib/reporter/logger.js that was not previously flagged.
Edit: A workaround for this example impact was implemented through PR #1119.
It can potentially impact other dependencies where versions locked in npm-shrinkwrap.json are different from a fresh resolution based on ^x.y.z SemVer ranges in package.json.
Steps to reproduce
Ubuntu 24.04.4 LTS, Node.js 24.19.0, initially with npm 11.17.0
git clone https://github.com/nodejs/citgm
cd citgm
git clean -xfd # if repeating
npm install -g npm@12.0.2
npm install
npm testLogs
$ npm test
npm notice run citgm@10.0.2 test
npm notice run npm run lint && npm run tap
npm notice run citgm@10.0.2 lint
npm notice run npm run lint:eslint && npm run lint:prettier
npm notice run citgm@10.0.2 lint:eslint
npm notice run eslint . --cache
npm notice run citgm@10.0.2 lint:prettier
npm notice run prettier --check .
Checking formatting...
[warn] lib/reporter/logger.js
[warn] Code style issues found in the above file. Run Prettier with --write to fix.Suggestion
Review also how this impacts use of citgm when installing using npm install -g citgm as specified in the README > Installation section.
For the Prettier issue, that was used here more as an illustration of compatibility issues, update to latest and fix the formatting.
Activity
ljharb commentedon Aug 6, 2026
I'm confused, what's the bug here? That a shrinkwrap file is ignored? That was an intentional change in v12. Rename the file to
package-lock.jsonand it should work fine.MikeMcC399 commentedon Aug 18, 2026
PR #1103 from @targos introduced
npm-shrinkwrap.jsonin Sep 2025.It's also mentioned in nodejs/node-core-utils#976 where
npm-shrinkwrap.jsonreplacespackage-lock.json.If there is to be a return to using
package-lock.jsongenerally, that may also need a general discussion. It impacts which versionsnpm install -g citgmactually installs, and so it would be a breaking change.MikeMcC399 commentedon Aug 18, 2026
I fixed the Prettier incompatibility in #1119
That only resolved that particular issue though.
ljharb commentedon Aug 18, 2026
ah, so the citgm package was intentionally shipping a shrinkwrap to lock consumer trees? that's the harmful behavior that npm 12 disallows by ignoring shrinkwrap.
MikeMcC399 commentedon Aug 19, 2026
I would suggest to rename
npm-shrinkwrap.jsontopackage-lock.jsonfor compatibility with npm 12 as also suggested by @ljharb.Downstream consumers of citgm are then free to update dependencies within the SemVer range defined in
package.json, which is particularly important for being able to resolve emerging vulnerabilities.This is however a breaking change and that should be accompanied by a major version bump for citgm.
MikeMcC399 commentedon Aug 19, 2026
PR #1129 proposes the rename of
npm-shrinkwrap.jsontopackage-lock.jsonfor compatible usage on supported npm versions, including npm 12.ljharb commentedon Aug 19, 2026
One approach could be, publish a patch that sets engines.npm to < 12, and then publish the major without the shrinkwrap file and without an engines.npm restriction.
MikeMcC399 commentedon Aug 26, 2026
I don't think that would be necessary as far as usage in nodejs/node via Jenkins is concerned. citgm just gets installed as latest and any EBADENGINE warnings are ignored. If that weren't the case, it would already have failed trying to test against Node.js 26.
The npm 12 issues are in practice actually quite minor, but still deserve cleaning up. Hopefully the remaining PRs I've submitted can be reviewed and merged.
MikeMcC399 commentedon Oct 9, 2026
Closing this issue, as the steps to reproduce are no longer accurate.
#1188 fixes
npm testcompatibility with Node.js v27 nightly.I'll revisit after the release of Node.js 27 Alpha, planned for Oct 28, 2026.