[RRFC] Promote npm add to a top-level command

[ruyadorno]

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

References

• Related to: [RRFC] Run preinstall / postinstall scripts on single package installation #325

cc @karlhorky @wraithgar

[ruyadorno]

Some more ideas to be explored:

• Given that add would now be its own top-level command, maybe it should disallow a no args usage (warn in npm7 possibly throw in npm8)
• npm install <pkg> should probably run preadd, add, postadd for compatibility ?
• on the other way round npm add <pkg> should probably also run preinstall, install and postinstall lifecycle scripts?

[karlhorky]

Thanks for your thought and work here @ruyadorno !

Haven't thought about this at length yet, but a first few ideas:

1. I like the parity of the command name with yarn add - didn't know about this alias
2. install also running the new preadd, add and postadd lifecycle scripts for compatibility seems good / necessary - otherwise I guess many users will not remember to change their npm install muscle memory to enjoy the benefits of something like typesync
3. Is add understandable / semantic enough that it will have different behavior than install? I guess if install has identical behavior then the naming is not really an issue

[darcyclarke]

Linking #364 as they can potentially be linked based on how we end up implementing npm add

[isaacs]

Some questions that should be answered in the RFC:

• does the scripts.add get run when upgrading a package? (If so, do we specify the version being replaced? If so, how?)
• does it get run once or multiple times, if multiple packages are added? 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?)
• Are we adding a remove lifecycle script event for parity when packages are removed?
• Is npm install foo still going to be supported? (Yes, it has to be.) Is npm 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.)