Repository navigation
Plans for npm 10 #884
Description
The npm team is working on npm 10, and we are currently in the planning and early development phase. In opening this issue our goal is to facilitate discussion about our planned breaking changes in npm 10 and work towards our goal of landing npm 10 in Node.js 20 and 18.
Breaking Changes
During the discussion about npm 9 we landed on a list of guidelines on integrating new major versions of npm with Node. We plan on following these guidelines again, and we consider all breaking changes listed below to fall within those guidelines.
- Update engines to
>=16.14^18.17.0 || >=20.5.0- Tracking issue: Engines setting for npm 10 and beyond npm/statusboard#640
- Remove implicit
if-presentlogic from run-script in workspace mode- Currently when calling
npm run-scripton workspaces if any of the scripts are missing it is treated as a silently ignored error, making there an implicit "if-present" config in this mode. Users who want this behavior will need to include this config.
- Currently when calling
- Remove the following deprecated or unused configs:
tmp,ci-name,hashAlgorithm,metrics-registry- All these configs are either deprecated or are entirely unused in the npm CLI. We see these changes as low impact, but we always treat the removal of a config item as a breaking change.
- Use
@npmcli/agent- The existing http agent and proxy libraries we use do not have very good timeout configurations and also diverge from the spec in odd ways. The new agent is intended to be identical to the existing way of doing things, but because of the scope of the change we are waiting on a semver major before cutting over.
- Remove "strict mode" from
npm-package-argnpm-package-argcan be set to run in a RFC 8909 compliant "strict mode" by setting the environment variableNPM_PACKAGE_ARG_8909_STRICT=1. We don't have any real plan with making that mode permanent so we are removing this functionality. Too many existing packages rely on our technically spec divergent behavior and it is not worth breaking so many people to force compliance. Anyone currently using this mode will need to find a third party way to strictly enforce the package specs in their package.json.
- Don't retry 409 errors during
npm publish- Currently if the npm CLI gets a 409 from the registry during publish it attempts a single retry by re-fetching the manifest and attempting to apply a new patch on what's being published. This is not the safest approach, especially as the code used to patch is not the same code that is used to build the original manifest. It is much safer to simply have the user re-run the publish command.
Note: the following changes were originally planned but are not a part of npm@10
Expand the list of default ignored files obeyed duringpackandpublishTracking issue: [FEATURE] Expand the list of default ignored files npm/npm-packlist#48RFC issue: RFC: Expand list of ignored files npm/rfcs#114The exact list of files is still being discussed, but npm will start ignoring more files by default from being included in packaged tarballs. The npm CLI currently defines this list innpm-packlistand it includes files like.npmignoreand.gitignore. The original RFC proposes adding files to that list such as.editorconfig,.github/, and more.
Implement the "obey user specifier" RFCRFC issue: add "obey user specifier" RFC npm/rfcs#547The npm CLI will now save the same specifier used to install a package to package.json, egnpm install eslint@=8.8.0will save"8.8.0"as the specifier foreslintinstead of"^8.8.0"as it does now. This will only affect installs run with an argument, and barenpm installcommands will not churn the lockfile or package.json.
Testing
citgm was very helpful during the release of npm 9 in finding unintended consequences of our breaking changes. One new thing we will be doing during this release cycle is running our own modified version of citgm in GitHub Actions during all prereleases candidates of npm 10 to ensure we find breaking change bugs as early as possible.
Testing will also happen in CI during each pull request that is opened by the npm team.
Timeline
Our goals with this timeline are to ensure that npm 10 changes can be tested within Node as early as possible. We want to open PRs to main so that CI can be run against each prerelease of npm 10. The initial PRs will be labeled to only request-ci and not ready to be merged.
Once npm 10 is stable (Task 4) we will open a new PR that will be ready for review and to land on main. Once that PR is merged we will open PRs for both Node 20 and Node 18 backports. Our goal with these PRs is again to allow testing to happen as early as possible.
For Node 20 our goal is that npm 10 could be included in the tentative 2023-09-12 v20.10.0 release. For Node 18, assuming that npm 10 has shipped to users and we've fixed any bugs that have been raised, our goal is that npm 10 could be included in the tentative 2023-10-xx v18.20.0 release.
| Status | Task | Date | |
|---|---|---|---|
| 1 | ✅ | First prerelease (npm@10.0.0-pre.0) |
|
| 2 | ✅ | Open initial PR* to Node.js main branch for CI only nodejs/node#48934 |
|
| 3 | ✅ | Second prerelease | |
| 4 | ✅ | Major release (npm@10.0.0) |
|
| 5 | ✅ | Open PR to Node.js main branch for review nodejs/node#49423 |
|
| 6 | ✅ | Land npm 10 on Node.js main branch |
|
| 7 | ✅ | Promote npm@10.0.0 to latest |
|
| 8 | main (Task 6 |
||
| 9 | ✅ | Open PR requesting backport to Node.js 18 nodejs/node#49611 | main (Task 6) |
| 10 | Release npm 10 in Node.js 20 | 2023-09-12** v20.7.0 | |
| 11 | Release npm 10 in Node.js 18 | 2023-10-xx** v18.20.0 |
* Unmerged pull requests will be closed and a new one opened for each (pre)release. Any new PR will contain all the changes from all previous unmerged PRs.
** Tentative Node.js release date
Activity
mcollina commentedon Jul 15, 2023
The plan looks solid and I don’t think there would be issue in shipping npm v10 in Node 20. However, I feel that shipping such an update to Node v18 might be too risky for two reasons:
I don’t think there is much time to iron out possible bugs with thr given timeline.
Lastly, I recommend the npm team to stop treating the LTS release as their target and align their releases to Node.js. We could have avoided this discussion entirely if you released npm v10 in March or April.
ruyadorno commentedon Jul 19, 2023
From the list of breaking changes I believe this is the most likely to have a potential to be disruptive to the community, if the goal is to land on LTS I would advise the team to be very defensive about expanding that list. It might be worth holding on to the next major which hopefully aligns better with our release calendar.
wraithgar commentedon Jul 28, 2023
I agree and this is really the suggestion that moved the needle back to "let's not do this". We were already on the fence on this one and the cost/benefit is not anywhere near the level that we would want on a breaking change.
lukekarrys commentedon Aug 31, 2023
npm@10has been released and promoted tolatest. I updated my original comment which some changes as to what breaking changes actually landed innpm@10as well as updating the dates to when those events happened.The PR to land
npm@10innodejs/node#mainhas been opened here and is ready for review: nodejs/node#49423lukekarrys commentedon Sep 11, 2023
I have opened a PR requesting to backport
npm@10to Node 18 here: nodejs/node#49611. This PR is just to run CI and facilitate discussion, since I expect opening the PR to generate more 👀 from contributors.npm@10should be landing in Node 20 soon and we can continue to get and respond to user feedback.We've already triaged and fixed one regression (npm/cli#6760) from npm 9 to 10 and are continuing to monitor new issues coming in for npm 10. At this time we have no new npm P0 or P1 bugs in
npm@10.Based on the list of breaking changes that ended up in npm@10 (2 of the more potentially disruptive changes were dropped from the release), we think it makes sense to land
npm@10in Node 18 before LTS. The smaller set of ubreaking changes means the potential surface area for user disruption is smaller than then the process of updating npm 8 to 9.Addressing this point directly, our future plans will take this into account. Going forward we want to align more closely with Node around major versions to make this process much smoother. But we think in the case an exception for npm 10 should be discussed.
mcollina commentedon Sep 12, 2023
It would be best to avoid shipping npm 10 in a release, given that
globnow depends on BlueOak-1.0.0 licensed software, which is against the IP policy of the foundation. I've already asked an opinion to the Foundation legal staff.I'm acting out of caution here.
bricss commentedon Sep 12, 2023
It looks like BlueOak-1.0.0 is very much state-of-the-art permissive license, that is shipped within npm v9 in Node already.
And here is good article about it.
N.B.: Trying a new permissive software license
mcollina commentedon Sep 12, 2023
Ref nodejs/node#49625.
lukekarrys commentedon Oct 6, 2023
We've opened a new PR to backport
npm@10tov18: nodejs/node#50030. The npm team considers this PR ready to land inv18now thatnpm@10.1.0has shipped withv20.8.0. I will be checking the requested CI runs once they complete to ensure the same coverage as the previous draft PR (nodejs/node#49611).The latest version
npm@10.2.0fixes one more P1 regression we found fromnpm@9. We've been triaging the same list of issues I linked previously and we have no new npm P0 or P1 bugs in npm@10 currently.Based on the list of breaking changes that ended up in npm@10 (2 of the more potentially disruptive changes were dropped from the release), we think it makes sense to land npm@10 in Node 18 before
LTSmaintenance. The smaller set of ubreaking changes means the potential surface area for user disruption is smaller than then the process of updating npm 8 to 9.I am tagging @nodejs/releasers @mcollina @ruyadorno in this comment since we would like to come to a resolution quickly before the final release of
v18later this month.richardlau commentedon Oct 6, 2023
Node.js 18 is already LTS. Do you mean before it enters maintenance?
FWIW I'm preparing a Node.js 18 release for Tuesday but I'm intending it to be a revert release to undo the libuv updates in Node.js 18.18.0 -- I will not have time to do a full Node.js 18 release. Node.js 18.17.0, 18.17.1 and 18.18.0 all contained regressions which I would like to sort out before landing anything else in Node.js 18.
lukekarrys commentedon Oct 6, 2023
Yes, that is what I meant and corrected my previous comment.
wraithgar commentedon Oct 12, 2023
Now that Node.js
v18.18.1has shipped, do we have a better idea of whether or not we can land this?mark-wiemer commentedon Nov 4, 2023
Hi, very new to this issue, and a bit confused. npm 10 is out now and able to be installed without any pre-release flags. It doesn't come bundled with Node 18 yet, is that why this issue is still open? When should we expect a more formal "announcement" or summary of finalized changes with npm 10? Ref the GitHub blog for npm 9
Apollon77 commentedon Nov 7, 2023
please consider using npm@10.2.2 at least because of the current fixed node-gyp issues with Python 3.12 ... see nodejs/node-gyp#2869 ... because this already hits some users (and GitHub has alreayd started to update their runners to Python 3.12 - actions/runner#2972). The same 8also if off topic here) would be cool to see ot too late in node.js 20.
PS: I personally would love a "fix node.js 16 version" with also npm 10, but that might not going to happen because formally EOL ;-) ... it will just be forseeable that isues arise when Python 3.12 spreads on the users systems
6 remaining items
Apollon77 commentedon Jan 6, 2024
The main reason in my eyes is that node-gyp had compatibility issues with python 3.12 which means that all node-gyp binary package builds would fail. The fix was in npm 10.2.3 or such ... It seems that the npm team decided to do not do a backporting of inclusion of new node-gyp intp an older npm major version ...
So in fact the issue was really big (and with Node.js 18 being LTS sinsce aprio 2025 thats a long timeframe to risk this. But agreed ... backporting would also have had been an dea, but I assume too late now
theJC commentedon Jan 31, 2024
We are very interested in getting 10.3.0 of npm or higher pulled in, due to the fix/revert that restores SIGTERM/SIGINT signal forwarding to child processes - npm/run-script#188
Any chance guidance can be provided as to what Node release we can get an npm version that comes with that has this fix in place? This issue has significant ramifications on the behavior of our services runtime and allowing Node services launched by npm to honor kubernetes shutdown process and the signals it sends to provide time for draining/etc.
richardlau commentedon Jan 31, 2024
@theJC I've volunteered to do a Node.js 20 release in February for exactly this reason (to include npm 10.3.0). Our usual policy is that changes should first go out in a current release (i.e. Node.js 21) for two weeks so the exact timing depends on when we get a Node.js 21 release out with that version of npm.
theJC commentedon Jan 31, 2024
Sorry @richardlau , I didn't indicate, but we are specifically looking for a node 18 release to contain 10.3.0 or higher (Node18 is the only version our company supports at this time) to address the repair of the SIGNAL propagation breakage on that version line.
theJC commentedon Jan 31, 2024
Can anyone provide details on how best to provide input/encouragement or learn about the process that would be required to consider getting npm 10.3.0+ be the version distributed in a soonish/upcoming Node 18.X release?
bricss commentedon Jan 31, 2024
It will get into next release of v21, coz it already landed in da
main3 weeks ago, and anyone can pull it up forbackportin da v18 in any moment 🤷richardlau commentedon Jan 31, 2024
It won't need a manual backport but will need to go out in a Node.js 21 release first.
theJC commentedon Feb 9, 2024
How do we get the next version of Node 21 (21.6.2) to be bumped to having the 10.3.0 or higher version of npm?
mhdawson commentedon Mar 7, 2024
@lukekarrys this may be a case of changes in npm10 versus 9 causing Node.js problems when upgrading in the 18.x line -npm/cli#7272
lukekarrys commentedon Mar 8, 2024
Thanks for the ping @mhdawson. I've collected that issue along with a few others (that I don't have links to right now) that are all around network requests and the http agent we use.
As an aside, the original purpose of this issue was tracking inclusion of npm 10 across Node.js versions which has been completed. I'm going to close this now and will track these bugs in
npm/clias they get fixed.NewEraCracker commentedon Dec 21, 2024
Note: npm 10.8.3 can run on Node.js 16.20.2, although it's not officially supported.
Later versions of npm (e.g. 10.9+) have breaking changes in their dependencies and are not compatible with Node.js 16.
Running npm 10.8.3 is a more stable option compared to npm 9, which has known bugs.
To install npm 10.8.3 on Node.js 16.20.2, use the following command, at your own risk:
npm i -g npm@10.8.3 --forceMy two cents.
wraithgar commentedon Jan 2, 2025
Please do not install npm in environments it is not supported in. npm makes a good faith effort to run in node versions as low as 6, but only insofar as it will log a warning before any exceptions are thrown due to unsupported node syntax. Those exceptions can happen at any time, and may not happen on every npm command.
If you are truly concerned about security you should also be updating to a supported version of Node.js, in addition to the latest npm.
build: Update dependency nodejs to v18.20.5 (#500)