fix(docs): clarify what install type gets .bins by wraithgar · Pull Request #3491 · npm/cli (original) (raw)
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
"on install" was ambiguous because it wasn't clear if it meant "when npm
install is ran on this project" or "when this project is installed
somewhere else"
References
Related to #3488
TBH, even knowing the distinction you’re trying to make from comments you left in #3488 this change wouldn’t make that clear to me.
“On install” vs “when this package is installed” read the same to me, as someone just trying to npm install a package.
is that wording meaningful to more experienced npm devs?
npm install installs the dependencies of a given modulenpm install x installs the package x into a given module, this is what is meant by "installing a package"
The fact that some people have a mental model of "running npm install" means "installing a package" instead of "installing the dependencies for a package" is probably larger than this PR can address. They are definitely not the same thing.
What wording would you recommend then?
I’m not at a computer at the moment. But distinguishing those two cases by path might be more clear.
roughly:
When installing to $globalDir, this script’s bin gets installed. When installing to node_modules/.bin, this script’s dependencies’ “bin” get installed.
(and maybe also a note about the thing you mentioned — that it’s not recommended to directly use nod_modules/.bin scripts directly.)
I think mentioning the .bin at all is a mistake. Gonna tweak the copy here to remove that and make it clear what the differences are, and the way to invoke those bins.
To use this, supply a `bin` field in your package.json which is a map of
command name to local file name. When this packaged is installed, npm
will symlink that file into a place where it can be invoked by name if
installed globally, or by `npm exec` when installed in another package.
Ok that's done. Thanks for helping make sure the docs make sense to you.
| installs. |
|---|
| command name to local file name. When this packaged is installed, npm |
| will symlink that file into a place where it can be invoked by name if |
| installed globally, or by `npm exec` when installed in another package. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| installed globally, or by `npm exec` when installed in another package. |
|---|
| installed globally, or by `npm exec` or `npm run-script` when installed in another package. |
“when installed globally” is only true when the PATH contains the global npm bin location; should that be called out?
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually run-script is incorrect. That only works for scripts entries, not bin. Removing that.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
npm run-script entries in "another package" definitely has access to the bin tho; that's what i was trying to convey.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah yeah, you can't npm run-script that package by name but you can refer to it by name in things run via npm run-script. I hope the new copy reflects this better.
Copy has been updated to clarify even more how the bins are intended to be used locally or globally, and a note on adding your global bin to PATH was added to the appropriate section in `folders
Thanks @ljharb. We were too late for today's release so this'll go out in two weeks.
"on install" was ambiguous because it wasn't clear if it meant "when npm install is ran on this project" or "when this project is installed somewhere else"
PR-URL: #3491 Credit: @wraithgar Close: #3491 Reviewed-by: @ljharb
This was referenced
May 20, 2024