Repository navigation
[RRFC] Promote npm add to a top-level command #395
Description
Motivation ("The Why")
Users are often confused by the fact that npm install (no args) and npm install <pkg> have different behavior with regards to lifecycle scripts, updating the package-lock file and other possible nuances in arborist when adding new deps to the installed tree vs simply reifying a tree.
The lifecycle script discussion has happened to some extent already over at #325 and although there's some level of agreement on having it work with a new type of lifecycle script (such as a generic tree mutation event) I would like to propose an alternative that at the same time also aims to improve the UX around adding new dependencies to a project.
How
We currently have a npm add command that is lightly documented and works as an alias to npm install. The main idea to be proposed in an eventual RFC is to turn npm add into an actual top-level command (with its own docs page and associated tests) along with adding custom behavior to run new preadd, add and postadd lifecycle scripts.
This aims to improve some of the existing pain points:
- Add a way to run scripts after adding a new dependency (solves [RRFC] Run preinstall / postinstall scripts on single package installation #325)
- A more expressive syntax. Users are going to be aware that they're adding (and thus mutating the current installed tree) when using a different top-level command.
Desired Behaviour
Given a project with the following package.json:
{
"name": "project",
"version": "1.0.0",
"scripts": {
"preadd": "echo \"Ran prior to adding a new dep\""
}
}When adding a new dependency using npm add <pkg> the lifecycle script would be executed, e.g:
$ npm add abbrev
> project@1.0.0 preadd
> echo "Ran prior to adding a new dep"
Ran prior to adding a new dep
added 1 package, and audited 2 packages in 584ms
found 0 vulnerabilities
Activity
ruyadorno commentedon Jun 8, 2021
Some more ideas to be explored:
npm install <pkg>should probably runpreadd,add,postaddfor compatibility ?npm add <pkg>should probably also runpreinstall,installandpostinstalllifecycle scripts?karlhorky commentedon Jun 9, 2021
Thanks for your thought and work here @ruyadorno !
Haven't thought about this at length yet, but a first few ideas:
yarn add- didn't know about this aliasinstallalso running the newpreadd,addandpostaddlifecycle scripts for compatibility seems good / necessary - otherwise I guess many users will not remember to change theirnpm installmuscle memory to enjoy the benefits of something liketypesyncaddunderstandable / semantic enough that it will have different behavior thaninstall? I guess ifinstallhas identical behavior then the naming is not really an issuedarcyclarke commentedon Jun 16, 2021
Linking #364 as they can potentially be linked based on how we end up implementing
npm addisaacs commentedon Jun 21, 2021
Some questions that should be answered in the RFC:
scripts.addget run when upgrading a package? (If so, do we specify the version being replaced? If so, how?)npm add foo bar baz(If once, how do we identify what is being added? Or is it just "something is being added", and up to the user to sniff for it if they care?)removelifecycle script event for parity when packages are removed?npm install foostill going to be supported? (Yes, it has to be.) Isnpm add(no args) going to keep working? (Yes, if it's a nonbreaking change, but can warn in v7 if we intend to break it in v8.)