From abae00ca05925e521696dd12480853509aab6c0a Mon Sep 17 00:00:00 2001 From: Gar Date: Thu, 28 Jan 2021 10:20:20 -0800 Subject: [PATCH] docs(npm): update npm command docs These are the base docs for the npm cli itself that populates `man npm`, Mostly grammar fixes, some additions and clarifications in places, new links to some appropriate other docs PR-URL: https://github.com/npm/cli/pull/2565 Credit: @wraithgar Close: #2565 Reviewed-by: @nlf --- docs/content/commands/npm.md | 105 ++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 45 deletions(-) diff --git a/docs/content/commands/npm.md b/docs/content/commands/npm.md index dc6ba3d25e371..d01146d37041c 100644 --- a/docs/content/commands/npm.md +++ b/docs/content/commands/npm.md @@ -20,36 +20,42 @@ npm is the package manager for the Node JavaScript platform. It puts modules in place so that node can find them, and manages dependency conflicts intelligently. -It is extremely configurable to support a wide variety of use cases. -Most commonly, it is used to publish, discover, install, and develop node +It is extremely configurable to support a variety of use cases. Most +commonly, you use it to publish, discover, install, and develop node programs. Run `npm help` to get a list of available commands. ### Important -npm is configured to use npm, Inc.'s public registry at +npm comes preconfigured to use npm's public registry at https://registry.npmjs.org by default. Use of the npm public registry is -subject to terms of use available at https://www.npmjs.com/policies/terms. +subject to terms of use available at +https://www.npmjs.com/policies/terms. -You can configure npm to use any compatible registry you like, and even run -your own registry. Use of someone else's registry may be governed by their -terms of use. +You can configure npm to use any compatible registry you like, and even +run your own registry. Use of someone else's registry is governed by +their terms of use. ### Introduction You probably got npm because you want to install stuff. -Use `npm install blerg` to install the latest version of "blerg". Check out -[`npm install`](/commands/npm-install) for more info. It can do a lot of stuff. +The very first thing you will most likely want to run in any node +program is `npm install` to install its dependencies. -Use the `npm search` command to show everything that's available. -Use `npm ls` to show everything you've installed. +You can also run `npm install blerg` to install the latest version of +"blerg". Check out [`npm install`](/commands/npm-install) for more +info. It can do a lot of stuff. + +Use the `npm search` command to show everything that's available in the +public registry. Use `npm ls` to show everything you've installed. ### Dependencies -If a package references to another package with a git URL, npm depends -on a preinstalled git. +If a package lists a dependency using a git URL, npm will install that +dependency using the [`git`](https://github.com/git-guides/install-git) +command and will generate an error if it is not installed. If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use @@ -64,20 +70,22 @@ the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki). ### Directories -See [`folders`](/configuring-npm/folders) to learn about where npm puts stuff. +See [`folders`](/configuring-npm/folders) to learn about where npm puts +stuff. In particular, npm has two modes of operation: -* global mode: - npm installs packages into the install prefix at - `prefix/lib/node_modules` and bins are installed in `prefix/bin`. * local mode: npm installs packages into the current project directory, which - defaults to the current working directory. Packages are installed to - `./node_modules`, and bins are installed to `./node_modules/.bin`. + defaults to the current working directory. Packages install to + `./node_modules`, and bins to `./node_modules/.bin`. +* global mode: + npm installs packages into the install prefix at + `$npm_config_prefix/lib/node_modules` and bins to + `$npm_config_prefix/bin`. Local mode is the default. Use `-g` or `--global` on any command to -operate in global mode instead. +run in global mode instead. ### Developer Usage @@ -85,20 +93,22 @@ If you're using npm to develop and publish your code, check out the following help topics: * json: - Make a package.json file. See [`package.json`](/configuring-npm/package-json). + Make a package.json file. See + [`package.json`](/configuring-npm/package-json). * link: - For linking your current working code into Node's path, so that you - don't have to reinstall every time you make a change. Use - `npm link` to do this. + Links your current working code into Node's path, so that you don't + have to reinstall every time you make a change. Use [`npm + link`](/commands/npm-link) to do this. * install: - It's a good idea to install things if you don't need the symbolic link. - Especially, installing other peoples code from the registry is done via - `npm install` + It's a good idea to install things if you don't need the symbolic + link. Especially, installing other peoples code from the registry is + done via [`npm install`](/commands/npm-install) * adduser: - Create an account or log in. Credentials are stored in the - user config file. + Create an account or log in. When you do this, npm will store + credentials in the user config file config file. * publish: - Use the `npm publish` command to upload your code to the registry. + Use the [`npm publish`](/commands/npm-publish`) command to upload your + code to the registry. #### Configuration @@ -108,20 +118,20 @@ npm is extremely configurable. It reads its configuration options from * Command line switches: Set a config with `--key val`. All keys take a value, even if they are booleans (the config parser doesn't know what the options are at - the time of parsing). If no value is provided, then the option is set - to boolean `true`. + the time of parsing). If you do not provide a value (`--key`) then + the option is set to boolean `true`. * Environment Variables: Set any config by prefixing the name in an environment variable with `npm_config_`. For example, `export npm_config_key=val`. * User Configs: - The file at $HOME/.npmrc is an ini-formatted list of configs. If + The file at `$HOME/.npmrc` is an ini-formatted list of configs. If present, it is parsed. If the `userconfig` option is set in the cli - or env, then that will be used instead. + or env, that file will be used instead. * Global Configs: - The file found at ../etc/npmrc (from the node executable, by default - this resolves to /usr/local/etc/npmrc) will be parsed if it is found. - If the `globalconfig` option is set in the cli, env, or user config, - then that file is parsed instead. + The file found at `./etc/npmrc` (relative to the global prefix will be + parsed if it is found. See [`npm prefix`](/commands/npm-prefix) for + more info on the global prefix. If the `globalconfig` option is set + in the cli, env, or user config, then that file is parsed instead. * Defaults: npm's default configuration options are defined in lib/utils/config-defs.js. These must not be changed. @@ -132,15 +142,17 @@ See [`config`](/using-npm/config) for much much more information. Patches welcome! -If you would like to contribute, but don't know what to work on, read -the [contributing guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) -and check the issues list. +If you would like to help, but don't know what to work on, read the +[contributing +guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and +check the issues list. ### Bugs -When you find issues, please report them: +When you find issues, please report them: + -Be sure to follow the template and bug reporting guidelines. +Please be sure to follow the template and bug reporting guidelines. ### Feature Requests @@ -153,8 +165,11 @@ Or suggest formal RFC proposals: * ### See Also + * [npm help](/commands/npm-help) * [package.json](/configuring-npm/package-json) -* [npm install](/commands/npm-install) -* [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) +* [npm config](/commands/npm-config) +* [npm install](/commands/npm-install) +* [npm prefix](/commands/npm-prefix) +* [npm publish](/commands/npm-publish)