fix(docs): clarify what install type gets .bins

[wraithgar]

"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

[NfNitLoop]

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.

[NfNitLoop]

“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?

[wraithgar]

npm install installs the dependencies of a given module
npm 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?

[NfNitLoop]

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.)

[wraithgar]

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.

[wraithgar]

Ok that's done. Thanks for helping make sure the docs make sense to you.

[ljharb]

Suggested change

	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?

[wraithgar]

The "source" of truth for executables is at https://docs.npmjs.com/cli/v7/configuring-npm/folders#executables so we should link there instead of trying to re-describe it.

Documenting "{prefix}/bin needs to be in your PATH" should probably be in the configuring section.

[wraithgar]

Actually run-script is incorrect. That only works for scripts entries, not bin. Removing that.

[ljharb]

npm run-script entries in "another package" definitely has access to the bin tho; that's what i was trying to convey.

[wraithgar]

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.

[wraithgar]

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

[wraithgar]

Thanks @ljharb. We were too late for today's release so this'll go out in two weeks.