From 339145f64f82d540dbc72ef97b54ae20c34315dd Mon Sep 17 00:00:00 2001 From: Gar Date: Thu, 1 Jul 2021 08:18:23 -0700 Subject: [PATCH] fix(docs): clarify what install type gets .bins "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: https://github.com/npm/cli/pull/3491 Credit: @wraithgar Close: #3491 Reviewed-by: @ljharb --- docs/content/configuring-npm/folders.md | 6 ++++-- docs/content/configuring-npm/package-json.md | 12 +++++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/content/configuring-npm/folders.md b/docs/content/configuring-npm/folders.md index 75e31cd733161..218870765b262 100644 --- a/docs/content/configuring-npm/folders.md +++ b/docs/content/configuring-npm/folders.md @@ -45,14 +45,16 @@ Global installs on Windows go to `{prefix}/node_modules` (that is, no Scoped packages are installed the same way, except they are grouped together in a sub-folder of the relevant `node_modules` folder with the name of that scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place -the package in `{prefix}/node_modules/@myorg/package`. See [`scope`](/using-npm/scope) for more details. +the package in `{prefix}/node_modules/@myorg/package`. See +[`scope`](/using-npm/scope) for more details. If you wish to `require()` a package, then install it locally. #### Executables When in global mode, executables are linked into `{prefix}/bin` on Unix, -or directly into `{prefix}` on Windows. +or directly into `{prefix}` on Windows. Ensure that path is in your +terminal's `PATH` environment to run them. When in local mode, executables are linked into `./node_modules/.bin` so that they can be made available to scripts run diff --git a/docs/content/configuring-npm/package-json.md b/docs/content/configuring-npm/package-json.md index 5cacf68ba175f..0fc5dc5075ee3 100644 --- a/docs/content/configuring-npm/package-json.md +++ b/docs/content/configuring-npm/package-json.md @@ -341,9 +341,12 @@ install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.) To use this, supply a `bin` field in your package.json which is a map of -command name to local file name. On install, npm will symlink that file -into `prefix/bin` for global installs, or `./node_modules/.bin/` for local -installs. +command name to local file name. When this package is installed +globally, that file will be linked where global bins go so it is +available to run by name. When this package is installed as a +dependency in another package, the file will be linked where it will be +available to that package either directly by `npm exec` or by name in other +scripts when invoking them via `npm run-script`. For example, myapp could have this: @@ -388,6 +391,9 @@ executable! Note that you can also set the executable files using [directories.bin](#directoriesbin). +See [folders](/configuring-npm/folders#executables) for more info on +executables. + ### man Specify either a single file or an array of filenames to put in place for