From 2f5c28a68719e948d2efedf463ebcb35972aaefb Mon Sep 17 00:00:00 2001 From: isaacs Date: Thu, 13 May 2021 13:46:30 -0700 Subject: [PATCH] fix(docs): autogenerate config docs for commands Add a script and Makefile rule to build the "Configuration" section for all command documentation based on the command classes' `params` list. Also correct several minor problems in the documentation, and add `params` listings for commands that were lacking them, to match the existing documentation and/or behavior within the code. PR-URL: https://github.com/npm/cli/pull/3243 Credit: @isaacs Close: #3243 Reviewed-by: @wraithgar --- Makefile | 3 + docs/content/commands/npm-access.md | 24 +++ docs/content/commands/npm-adduser.md | 51 +++-- docs/content/commands/npm-audit.md | 86 ++++++++ docs/content/commands/npm-bin.md | 20 ++ docs/content/commands/npm-bugs.md | 18 +- docs/content/commands/npm-cache.md | 12 +- docs/content/commands/npm-ci.md | 26 +++ docs/content/commands/npm-config.md | 44 ++++ docs/content/commands/npm-dedupe.md | 132 ++++++++++++ docs/content/commands/npm-deprecate.md | 24 +++ docs/content/commands/npm-diff.md | 84 ++++---- docs/content/commands/npm-dist-tag.md | 38 +++- docs/content/commands/npm-docs.md | 53 +++-- docs/content/commands/npm-doctor.md | 13 ++ docs/content/commands/npm-edit.md | 14 +- docs/content/commands/npm-exec.md | 79 ++++++- docs/content/commands/npm-explain.md | 11 +- docs/content/commands/npm-explore.md | 10 +- docs/content/commands/npm-find-dupes.md | 119 +++++++++++ docs/content/commands/npm-fund.md | 49 +++-- docs/content/commands/npm-help-search.md | 11 +- docs/content/commands/npm-help.md | 8 +- docs/content/commands/npm-hook.md | 24 +++ docs/content/commands/npm-init.md | 85 +++++--- docs/content/commands/npm-install-ci-test.md | 26 +++ docs/content/commands/npm-install-test.md | 164 +++++++++++++++ docs/content/commands/npm-install.md | 196 ++++++++++++------ docs/content/commands/npm-link.md | 164 +++++++++++++++ docs/content/commands/npm-logout.md | 42 +++- docs/content/commands/npm-ls.md | 93 ++++++--- docs/content/commands/npm-org.md | 41 ++++ docs/content/commands/npm-outdated.md | 37 +++- docs/content/commands/npm-owner.md | 24 +++ docs/content/commands/npm-pack.md | 54 ++++- docs/content/commands/npm-ping.md | 13 ++ docs/content/commands/npm-prefix.md | 20 ++ docs/content/commands/npm-profile.md | 51 ++++- docs/content/commands/npm-prune.md | 46 ++++ docs/content/commands/npm-publish.md | 86 ++++++++ docs/content/commands/npm-rebuild.md | 44 ++++ docs/content/commands/npm-repo.md | 45 +++- docs/content/commands/npm-restart.md | 26 +++ docs/content/commands/npm-root.md | 20 ++ docs/content/commands/npm-run-script.md | 85 ++++---- docs/content/commands/npm-search.md | 93 +++++---- docs/content/commands/npm-set-script.md | 37 +++- docs/content/commands/npm-star.md | 22 ++ docs/content/commands/npm-stars.md | 13 ++ docs/content/commands/npm-start.md | 26 +++ docs/content/commands/npm-stop.md | 26 +++ docs/content/commands/npm-team.md | 41 ++++ docs/content/commands/npm-test.md | 24 +++ docs/content/commands/npm-token.md | 50 +++++ docs/content/commands/npm-uninstall.md | 16 ++ docs/content/commands/npm-unpublish.md | 30 +++ docs/content/commands/npm-unstar.md | 33 +++ docs/content/commands/npm-update.md | 149 ++++++++++++- docs/content/commands/npm-version.md | 168 +++++++++------ docs/content/commands/npm-view.md | 48 ++++- docs/content/commands/npm-whoami.md | 22 +- docs/content/using-npm/config.md | 54 +++-- lib/access.js | 8 + lib/audit.js | 2 +- lib/bugs.js | 5 + lib/cache.js | 5 + lib/ci.js | 8 + lib/config.js | 10 + lib/dedupe.js | 16 ++ lib/deprecate.js | 8 + lib/diff.js | 16 ++ lib/doctor.js | 5 + lib/edit.js | 5 + lib/exec.js | 2 +- lib/explain.js | 5 + lib/explore.js | 5 + lib/find-dupes.js | 15 ++ lib/help-search.js | 5 + lib/help.js | 5 + lib/hook.js | 8 + lib/init.js | 2 +- lib/install-ci-test.js | 8 + lib/install.js | 11 + lib/link.js | 19 ++ lib/ls.js | 15 ++ lib/org.js | 10 + lib/outdated.js | 11 + lib/owner.js | 8 + lib/prefix.js | 5 + lib/profile.js | 10 + lib/prune.js | 2 +- lib/publish.js | 2 +- lib/rebuild.js | 9 + lib/restart.js | 8 + lib/run-script.js | 8 +- lib/search.js | 7 + lib/star.js | 8 + lib/stars.js | 7 + lib/start.js | 8 + lib/stop.js | 8 + lib/team.js | 10 + lib/test.js | 8 + lib/token.js | 10 + lib/unpublish.js | 5 + lib/unstar.js | 9 + lib/update.js | 14 +- lib/utils/config/definitions.js | 51 +++-- package.json | 1 + scripts/config-doc-command.js | 46 ++++ tap-snapshots/test/lib/publish.js.test.cjs | 2 +- .../lib/utils/config/describe-all.js.test.cjs | 54 +++-- .../test/lib/utils/npm-usage.js.test.cjs | 153 +++++++++++++- 112 files changed, 3313 insertions(+), 516 deletions(-) create mode 100644 scripts/config-doc-command.js diff --git a/Makefile b/Makefile index bb1b7526bb171..d35cbbf5f3b6b 100644 --- a/Makefile +++ b/Makefile @@ -73,6 +73,9 @@ man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js node scripts/config-doc.js +docs/content/commands/npm-%.md: lib/%.js scripts/config-doc-command.js lib/utils/config/*.js + node scripts/config-doc-command.js $@ $< + test: dev-deps node bin/npm-cli.js test diff --git a/docs/content/commands/npm-access.md b/docs/content/commands/npm-access.md index ed9c7775745ce..6d73d6a5e28ce 100644 --- a/docs/content/commands/npm-access.md +++ b/docs/content/commands/npm-access.md @@ -81,6 +81,30 @@ fail with an HTTP 402 status code (logically enough), unless you use Management of teams and team memberships is done with the `npm team` command. +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + + + ### See Also * [`libnpmaccess`](https://npm.im/libnpmaccess) diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md index 9ad4c27c6d8e5..f25d3ccd87ab4 100644 --- a/docs/content/commands/npm-adduser.md +++ b/docs/content/commands/npm-adduser.md @@ -35,37 +35,46 @@ your existing record. ### Configuration -#### registry + + +#### `registry` -Default: https://registry.npmjs.org/ +* Default: "https://registry.npmjs.org/" +* Type: URL -The base URL of the npm package registry. If `scope` is also specified, -this registry will only be used for packages with that scope. `scope` defaults -to the scope of the project directory you're currently in, if any. See [`scope`](/using-npm/scope). +The base URL of the npm registry. -#### scope +#### `scope` -Default: none +* Default: the scope of the current project, if any, or "" +* Type: String -If specified, the user and login credentials given will be associated -with the specified scope. See [`scope`](/using-npm/scope). You can use both at the same time, -e.g. +Associate an operation with a scope for a scoped registry. -```bash -npm adduser --registry=http://myregistry.example.com --scope=@myco +Useful when logging in to or out of a private registry: + +``` +# log in, linking the scope to the custom registry +npm login --scope=@mycorp --registry=https://registry.mycorp.com + +# log out, removing the link and the auth token +npm logout --scope=@mycorp ``` -This will set a registry for the given scope and login or create a user for -that registry at the same time. +This will cause `@mycorp` to be mapped to the registry for future +installation of packages specified according to the pattern +`@mycorp/package`. -#### auth-type +This will also cause `npm init` to create a scoped package. + +``` +# accept all defaults, and create a package named "@foo/whatever", +# instead of just named "whatever" +npm init --scope=@foo --yes +``` -* Default: `'legacy'` -* Type: `'legacy'`, `'sso'`, `'saml'`, `'oauth'` -What authentication strategy to use with `adduser`/`login`. Some npm registries -(for example, npmE) might support alternative auth strategies besides classic -username/password entry in legacy npm. + ### See Also @@ -74,3 +83,5 @@ username/password entry in legacy npm. * [npmrc](/configuring-npm/npmrc) * [npm owner](/commands/npm-owner) * [npm whoami](/commands/npm-whoami) +* [npm token](/commands/npm-token) +* [npm profile](/commands/npm-profile) diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md index 7ad950a6ba99e..27c4d972597a8 100644 --- a/docs/content/commands/npm-audit.md +++ b/docs/content/commands/npm-audit.md @@ -187,6 +187,92 @@ Fail an audit only if the results include a vulnerability with a level of modera $ npm audit --audit-level=moderate ``` +### Configuration + + + +#### `audit-level` + +* Default: null +* Type: null, "info", "low", "moderate", "high", "critical", or "none" + +The minimum level of vulnerability for `npm audit` to exit with a non-zero +exit code. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + +#### `force` + +* Default: false +* Type: Boolean + +Removes various protections against unfortunate side effects, common +mistakes, unnecessary performance degradation, and malicious input. + +* Allow clobbering non-npm files in global installs. +* Allow the `npm version` command to work on an unclean git repository. +* Allow deleting the cache folder with `npm cache clean`. +* Allow installing packages that have an `engines` declaration requiring a + different version of npm. +* Allow installing packages that have an `engines` declaration requiring a + different version of `node`, even if `--engine-strict` is enabled. +* Allow `npm audit fix` to install modules outside your stated dependency + range (including SemVer-major changes). +* Allow unpublishing all versions of a published package. +* Allow conflicting peerDependencies to be installed in the root project. +* Implicitly set `--yes` during `npm init`. + +If you don't have a clear idea of what you want to do, it is strongly +recommended that you do not use this option! + +#### `json` + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + +#### `package-lock-only` + +* Default: false +* Type: Boolean + +If set to true, it will update only the `package-lock.json`, instead of +checking `node_modules` and downloading dependencies. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + ### See Also * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md index c835784f675a0..12984da1d1db7 100644 --- a/docs/content/commands/npm-bin.md +++ b/docs/content/commands/npm-bin.md @@ -16,6 +16,26 @@ Note: This command is unaware of workspaces. Print the folder where npm will install executables. +### Configuration + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + + ### See Also * [npm prefix](/commands/npm-prefix) diff --git a/docs/content/commands/npm-bugs.md b/docs/content/commands/npm-bugs.md index 714db4440cdf2..b8778324b8e4a 100644 --- a/docs/content/commands/npm-bugs.md +++ b/docs/content/commands/npm-bugs.md @@ -21,24 +21,28 @@ will search for a `package.json` in the current folder and use the `name` proper ### Configuration -#### browser + + +#### `browser` * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: String or Boolean +* Type: null, Boolean, or String -The browser that is called by the `npm bugs` command to open websites. +The browser that is called by npm commands to open websites. Set to `false` to suppress browser behavior and instead print urls to terminal. Set to `true` to use default system URL opener. -#### registry +#### `registry` -* Default: https://registry.npmjs.org/ -* Type: url +* Default: "https://registry.npmjs.org/" +* Type: URL -The base URL of the npm package registry. +The base URL of the npm registry. + + ### See Also diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md index 0bbb2756a40fe..e371f196d7c42 100644 --- a/docs/content/commands/npm-cache.md +++ b/docs/content/commands/npm-cache.md @@ -75,11 +75,17 @@ verify`. ### Configuration -#### cache + + +#### `cache` -Default: `~/.npm` on Posix, or `%AppData%/npm-cache` on Windows. +* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm` +* Type: Path -The root cache folder. +The location of npm's cache directory. See [`npm +cache`](/commands/npm-cache) + + ### See Also diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md index 937553631ace5..9645bae7e2f43 100644 --- a/docs/content/commands/npm-ci.md +++ b/docs/content/commands/npm-ci.md @@ -65,6 +65,32 @@ cache: - "$HOME/.npm" ``` +### Configuration + + + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `script-shell` + +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows +* Type: null or String + +The shell to use for scripts run with the `npm exec`, `npm run` and `npm +init ` commands. + + + ### See Also * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md index 31629a6b7d7a2..f2868cb8909a9 100644 --- a/docs/content/commands/npm-config.md +++ b/docs/content/commands/npm-config.md @@ -93,6 +93,50 @@ npm config edit Opens the config file in an editor. Use the `--global` flag to edit the global config. +### Configuration + + + +#### `json` + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + +#### `editor` + +* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on + Windows, or 'vim' on Unix systems +* Type: String + +The command to run for `npm edit` and `npm config edit`. + +#### `long` + +* Default: false +* Type: Boolean + +Show extended information in `ls`, `search`, and `help-search`. + + + ### See Also * [npm folders](/configuring-npm/folders) diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md index f9bfd9e01532e..e870ad269815d 100644 --- a/docs/content/commands/npm-dedupe.md +++ b/docs/content/commands/npm-dedupe.md @@ -72,6 +72,138 @@ result in new modules being installed. Using `npm find-dupes` will run the command in `--dry-run` mode. +### Configuration + + + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + +#### `package-lock` + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +When package package-locks are disabled, automatic pruning of extraneous +modules will also be disabled. To remove extraneous modules with +package-locks disabled use `npm prune`. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `audit` + +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside `npm install` runs to the default +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + + + ### See Also * [npm find-dupes](/commands/npm-find-dupes) diff --git a/docs/content/commands/npm-deprecate.md b/docs/content/commands/npm-deprecate.md index 73d88b3717bd1..b5c0e67144aef 100644 --- a/docs/content/commands/npm-deprecate.md +++ b/docs/content/commands/npm-deprecate.md @@ -40,6 +40,30 @@ To un-deprecate a package, specify an empty string (`""`) for the `message` argument. Note that you must use double quotes with no space between them to format an empty string. +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + + + ### See Also * [npm publish](/commands/npm-publish) diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md index 0fe6a68fa2f0f..57d20727a7533 100644 --- a/docs/content/commands/npm-diff.md +++ b/docs/content/commands/npm-diff.md @@ -153,82 +153,96 @@ located within the folder `./lib/` and changed lines of code within the ### Configuration -#### diff + + +#### `diff` -* Type: Array -* Default: null +* Default: +* Type: String (can be set multiple times) -Defines npm package specifiers to compare using the `npm diff` command. +Define arguments to compare in `npm diff`. -This can be specified up to 2 times. +#### `diff-name-only` -#### diff-name-only - -* Type: Boolean * Default: false +* Type: Boolean -When set to `true` running `npm diff` only returns the names of the files that -have any difference. +Prints only filenames when using `npm diff`. -#### diff-unified +#### `diff-unified` +* Default: 3 * Type: Number -* Default: `3` -The number of lines of context to print in the unified diff format output. +The number of lines of context to print in `npm diff`. -#### diff-ignore-all-space +#### `diff-ignore-all-space` -* Type: Boolean * Default: false +* Type: Boolean -Ignore whitespace when comparing lines. This ignores differences even if one -line has whitespace where the other line has none. +Ignore whitespace when comparing lines in `npm diff`. -#### diff-no-prefix +#### `diff-no-prefix` -* Type: Boolean * Default: false +* Type: Boolean + +Do not show any source or destination prefix in `npm diff` output. -Do not show any source or destination prefix. +Note: this causes `npm diff` to ignore the `--diff-src-prefix` and +`--diff-dst-prefix` configs. -#### diff-src-prefix +#### `diff-src-prefix` +* Default: "a/" * Type: String -* Default: `"a/"` -Show the given source prefix in diff patches headers instead of using "a/". +Source prefix to be used in `npm diff` output. -#### diff-dst-prefix +#### `diff-dst-prefix` +* Default: "b/" * Type: String -* Default: `"b/"` -Show the given source prefix in diff patches headers instead of using "b/". +Destination prefix to be used in `npm diff` output. -#### diff-text +#### `diff-text` -* Type: Boolean * Default: false +* Type: Boolean -Treat all files as text. +Treat all files as text in `npm diff`. -#### global +#### `global` * Default: false * Type: Boolean -Uses packages from the global space as a source for comparison. +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` -#### tag +#### `tag` +* Default: "latest" * Type: String -* Default: `"latest"` -The tag used to fetch the tarball that will be compared with the local file -system files when running npm diff with no arguments. +If you ask npm to install a package and don't tell it a specific version, +then it will install the specified tag. + +Also the tag that is added to the package@version specified by the `npm tag` +command, if no explicit tag is given. +When used by the `npm diff` command, this is the tag used to fetch the +tarball that will be compared with the local files by default. + ## See Also * [npm outdated](/commands/npm-outdated) diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md index 158c3417e7cba..0e4e0ce56c69d 100644 --- a/docs/content/commands/npm-dist-tag.md +++ b/docs/content/commands/npm-dist-tag.md @@ -90,15 +90,41 @@ not begin with a number or the letter `v`. ### Configuration -#### workspaces + + +#### `workspace` -Only supported by `ls`. Enables listing dist-tags of all workspace -contexts defined in the current `package.json`. +* Default: +* Type: String (can be set multiple times) -#### workspace +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. -Only supported by `ls`. Enables listing dist-tags of workspace contexts -limiting results to only those specified by this config item. +Valid values for the `workspace` config are either: + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + ### See Also diff --git a/docs/content/commands/npm-docs.md b/docs/content/commands/npm-docs.md index d0971efa2e762..7f4c860837035 100644 --- a/docs/content/commands/npm-docs.md +++ b/docs/content/commands/npm-docs.md @@ -22,37 +22,60 @@ the `name` property. ### Configuration -#### browser + + +#### `browser` * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: String or Boolean +* Type: null, Boolean, or String -The browser that is called by the `npm docs` command to open websites. +The browser that is called by npm commands to open websites. Set to `false` to suppress browser behavior and instead print urls to terminal. Set to `true` to use default system URL opener. -#### registry +#### `registry` -* Default: https://registry.npmjs.org/ -* Type: url +* Default: "https://registry.npmjs.org/" +* Type: URL -The base URL of the npm package registry. +The base URL of the npm registry. -#### workspaces +#### `workspace` -Enables workspaces context while searching the `package.json` in the -current folder. Documentation urls for the packages named in each -workspace will be opened. +* Default: +* Type: String (can be set multiple times) -#### workspace +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. -Enables workspaces context and limits results to only those specified by -this config item. Only the documentation urls for the packages named in -the workspaces given here will be opened. +Valid values for the `workspace` config are either: +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + ### See Also diff --git a/docs/content/commands/npm-doctor.md b/docs/content/commands/npm-doctor.md index 9416818a40aaf..839f4261bbbc2 100644 --- a/docs/content/commands/npm-doctor.md +++ b/docs/content/commands/npm-doctor.md @@ -102,6 +102,19 @@ located with `npm config get cache`). In the event that there are corrupt packages in your cache, you should probably run `npm cache clean -f` and reset the cache. +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + + + ### See Also * [npm bugs](/commands/npm-bugs) diff --git a/docs/content/commands/npm-edit.md b/docs/content/commands/npm-edit.md index 20788aafb6d6a..6930844bcae2c 100644 --- a/docs/content/commands/npm-edit.md +++ b/docs/content/commands/npm-edit.md @@ -27,13 +27,17 @@ changes to your locally installed copy. ### Configuration -#### editor + + +#### `editor` -* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, - or `"notepad"` on Windows. -* Type: path +* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on + Windows, or 'vim' on Unix systems +* Type: String -The command to run for `npm edit` or `npm config edit`. +The command to run for `npm edit` and `npm config edit`. + + ### See Also diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md index 2364da32c76de..d4ea94371a85c 100644 --- a/docs/content/commands/npm-exec.md +++ b/docs/content/commands/npm-exec.md @@ -120,6 +120,64 @@ thus be equivalent to the `npx` command above: $ npm exec -- foo@latest bar --package=@npmcli/foo ``` +### Configuration + + + +#### `package` + +* Default: +* Type: String (can be set multiple times) + +The package to install for [`npm exec`](/commands/npm-exec) + +#### `call` + +* Default: "" +* Type: String + +Optional companion option for `npm exec`, `npx` that allows for specifying a +custom command to be run along with the installed packages. + +```bash +npm exec --package yo --package generator-node --call "yo node" +``` + + +#### `workspace` + +* Default: +* Type: String (can be set multiple times) + +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. + +Valid values for the `workspace` config are either: + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + + ### Examples Run the version of `tap` in the local dependencies, with the provided @@ -260,18 +318,21 @@ an error. #### workspace -* Alias: `-w` -* Type: Array -* Default: `[]` +* Default: +* Type: String (can be set multiple times) -Enable running scripts in the context of workspaces while also filtering by -the provided names or paths provided. +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. Valid values for the `workspace` config are either: -- Workspace names -- Path to a workspace directory -- Path to a parent workspace directory (will result to selecting all of the -children workspaces) + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +This value is not exported to the environment for child processes. #### workspaces diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md index ec63ec34f26d8..d4f828377a1ac 100644 --- a/docs/content/commands/npm-explain.md +++ b/docs/content/commands/npm-explain.md @@ -54,13 +54,18 @@ node_modules/nyc/node_modules/find-up ``` ### Configuration - -#### json + + +#### `json` * Default: false * Type: Boolean -Show information in JSON format. +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + + ### See Also diff --git a/docs/content/commands/npm-explore.md b/docs/content/commands/npm-explore.md index 8bad293052ead..c4a40cf7229f7 100644 --- a/docs/content/commands/npm-explore.md +++ b/docs/content/commands/npm-explore.md @@ -31,14 +31,18 @@ sure to use `npm rebuild ` if you make any changes. ### Configuration -#### shell + + +#### `shell` -* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on +* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe" on Windows -* Type: path +* Type: String The shell to run for the `npm explore` command. + + ### See Also * [npm folders](/configuring-npm/folders) diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md index 6557a071c82c0..933c76e2fe231 100644 --- a/docs/content/commands/npm-find-dupes.md +++ b/docs/content/commands/npm-find-dupes.md @@ -15,6 +15,125 @@ npm find-dupes Runs `npm dedupe` in `--dry-run` mode, making npm only output the duplications, without actually changing the package tree. +### Configuration + + + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + +#### `package-lock` + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +When package package-locks are disabled, automatic pruning of extraneous +modules will also be disabled. To remove extraneous modules with +package-locks disabled use `npm prune`. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `audit` + +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside `npm install` runs to the default +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + + + ### See Also * [npm dedupe](/commands/npm-dedupe) diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md index 45c5dfaac2afc..3dc5292b490a1 100644 --- a/docs/content/commands/npm-fund.md +++ b/docs/content/commands/npm-fund.md @@ -64,27 +64,37 @@ test-workspaces-fund@1.0.0 ### Configuration -#### browser + + +#### `json` -* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: String +* Default: false +* Type: Boolean -The browser that is called by the `npm fund` command to open websites. +Whether or not to output JSON data, rather than the normal output. -#### json +Not supported by all npm commands. -* Type: Boolean -* Default: false +#### `browser` + +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` +* Type: null, Boolean, or String + +The browser that is called by npm commands to open websites. + +Set to `false` to suppress browser behavior and instead print urls to +terminal. -Show information in JSON format. +Set to `true` to use default system URL opener. -#### unicode +#### `unicode` +* Default: false on windows, true on mac/unix systems with a unicode locale, + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables. * Type: Boolean -* Default: true -Whether to represent the tree structure using unicode characters. -Set it to `false` in order to use all-ansi output. +When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters instead of unicode glyphs. #### `workspace` @@ -96,20 +106,27 @@ current project while filtering by running only the workspaces defined by this configuration option. Valid values for the `workspace` config are either: + * Workspace names * Path to a workspace directory * Path to a parent workspace directory (will result to selecting all of the -nested workspaces) + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. This value is not exported to the environment for child processes. -#### which +#### `which` -* Type: Number -* Default: undefined +* Default: null +* Type: null or Number If there are multiple funding sources, which 1-indexed source URL to open. + + ## See Also * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-help-search.md b/docs/content/commands/npm-help-search.md index 51c7b43fb54f1..70f4f182d17e3 100644 --- a/docs/content/commands/npm-help-search.md +++ b/docs/content/commands/npm-help-search.md @@ -25,15 +25,16 @@ directly. ### Configuration -#### long + + +#### `long` -* Type: Boolean * Default: false +* Type: Boolean -If true, the "long" flag will cause help-search to output context around -where the terms were found in the documentation. +Show extended information in `ls`, `search`, and `help-search`. -If false, then help-search will just list out the help topics found. + ### See Also diff --git a/docs/content/commands/npm-help.md b/docs/content/commands/npm-help.md index 57c5efc8ed5eb..81f55db332eda 100644 --- a/docs/content/commands/npm-help.md +++ b/docs/content/commands/npm-help.md @@ -23,15 +23,19 @@ topic, so unique matches are equivalent to specifying a topic name. ### Configuration -#### viewer + + +#### `viewer` * Default: "man" on Posix, "browser" on Windows -* Type: path +* Type: String The program to use to view help content. Set to `"browser"` to view html help content in the default web browser. + + ### See Also * [npm](/commands/npm) diff --git a/docs/content/commands/npm-hook.md b/docs/content/commands/npm-hook.md index 6effc9b7d223b..2917375ea38cd 100644 --- a/docs/content/commands/npm-hook.md +++ b/docs/content/commands/npm-hook.md @@ -83,6 +83,30 @@ Remove a hook: $ npm hook rm id-deadbeef ``` +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + + + ### See Also * ["Introducing Hooks" blog post](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm) diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md index 8288034a3f19a..23e8e70d9e913 100644 --- a/docs/content/commands/npm-init.md +++ b/docs/content/commands/npm-init.md @@ -7,7 +7,7 @@ description: Create a package.json file ### Synopsis ```bash -npm init [--force|-f|--yes|-y|--scope] +npm init [--yes|-y|--scope] npm init <@scope> (same as `npm exec <@scope>/create`) npm init [<@scope>/] (same as `npm exec [<@scope>/]create-`) npm init [-w ] [args...] @@ -143,54 +143,75 @@ dot to represent the current directory in that context, e.g: `react-app .`: `-- ... ``` -### A note on caching +### Configuration -The npm cli utilizes its internal package cache when using the package -name specified. You can use the following to change how and when the -cli uses this cache. See [`npm cache`](/commands/npm-cache) for more on -how the cache works. + + +#### `yes` -#### prefer-online +* Default: null +* Type: null or Boolean -Forces staleness checks for packages, making the cli look for updates -immediately even if the package is already in the cache. +Automatically answer "yes" to any prompts that npm might print on the +command line. -#### prefer-offline +#### `force` -Bypasses staleness checks for packages. Missing data will still be -requested from the server. To force full offline mode, use `offline`. +* Default: false +* Type: Boolean -#### offline +Removes various protections against unfortunate side effects, common +mistakes, unnecessary performance degradation, and malicious input. -Forces full offline mode. Any packages not locally cached will result in -an error. +* Allow clobbering non-npm files in global installs. +* Allow the `npm version` command to work on an unclean git repository. +* Allow deleting the cache folder with `npm cache clean`. +* Allow installing packages that have an `engines` declaration requiring a + different version of npm. +* Allow installing packages that have an `engines` declaration requiring a + different version of `node`, even if `--engine-strict` is enabled. +* Allow `npm audit fix` to install modules outside your stated dependency + range (including SemVer-major changes). +* Allow unpublishing all versions of a published package. +* Allow conflicting peerDependencies to be installed in the root project. +* Implicitly set `--yes` during `npm init`. -#### workspace +If you don't have a clear idea of what you want to do, it is strongly +recommended that you do not use this option! -* Alias: `-w` -* Type: Array -* Default: `[]` +#### `workspace` -Enable running `npm init` in the context of workspaces, creating any missing -folders, generating files and adding/updating the `"workspaces"` property of -the project `package.json`. +* Default: +* Type: String (can be set multiple times) -the provided names or paths provided. +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. Valid values for the `workspace` config are either: -- Workspace names -- Path to a workspace directory -- Path to a parent workspace directory (will result to selecting all of the -children workspaces) -#### workspaces +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. -* Alias: `-ws` +#### `workspaces` + +* Default: false * Type: Boolean -* Default: `false` -Run `npm init` in the context of all configured workspaces for the -current project. +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + ### See Also diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md index 568d174cf44c5..c337905a0566e 100644 --- a/docs/content/commands/npm-install-ci-test.md +++ b/docs/content/commands/npm-install-ci-test.md @@ -16,6 +16,32 @@ alias: npm cit This command runs `npm ci` followed immediately by `npm test`. +### Configuration + + + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `script-shell` + +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows +* Type: null or String + +The shell to use for scripts run with the `npm exec`, `npm run` and `npm +init ` commands. + + + ### See Also * [npm install-test](/commands/npm-install-test) diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md index 6350c5d01ad70..1adf6490f9327 100644 --- a/docs/content/commands/npm-install-test.md +++ b/docs/content/commands/npm-install-test.md @@ -25,6 +25,170 @@ common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run] This command runs an `npm install` followed immediately by an `npm test`. It takes exactly the same arguments as `npm install`. +### Configuration + + + +#### `save` + +* Default: true +* Type: Boolean + +Save installed packages to a package.json file as dependencies. + +When used with the `npm rm` command, removes the dependency from +package.json. + +#### `save-exact` + +* Default: false +* Type: Boolean + +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + +#### `package-lock` + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +When package package-locks are disabled, automatic pruning of extraneous +modules will also be disabled. To remove extraneous modules with +package-locks disabled use `npm prune`. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `audit` + +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside `npm install` runs to the default +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + + + ### See Also * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md index f81a8a2463989..9e61cf7268bd6 100644 --- a/docs/content/commands/npm-install.md +++ b/docs/content/commands/npm-install.md @@ -411,89 +411,167 @@ does. These are some of the most common options related to installation. -#### Configuration Options Affecting Dependency Resolution And Tree Design + + +#### `save` -* `-g` or `--global`: install the package globally rather than locally. - See [folders](/configuring-npm/folders). +* Default: true +* Type: Boolean -* `--global-style`: install the package into your local `node_modules` - folder with the same layout it uses with the global `node_modules` - folder. Only your direct dependencies will show in `node_modules` and - everything they depend on will be flattened in their `node_modules` - folders. This obviously will eliminate some deduping. +Save installed packages to a package.json file as dependencies. -* `--legacy-bundling`: install the package in the style of versions of npm - prior to 1.4, where dependencies are not automatically deduped up to the - shallowest level in the tree possible. This is extremely - disk-inefficient. +When used with the `npm rm` command, removes the dependency from +package.json. -* `--legacy-peer-deps`: ignore all `peerDependencies` when installing, in - the style of npm version 4 through version 6. +#### `save-exact` -* `--strict-peer-deps`: fail and abort the install process for any - conflicting peerDependencies when encountered. By default, npm will only - crash for peerDependencies conflicts caused by the direct dependencies of - the root project. +* Default: false +* Type: Boolean -* `--no-package-lock` (alias: `--no-shrinkwrap`): do not read the - lockfile (`package-lock.json` or `npm-shrinkwrap.json`) for the intended - package tree, and do not save the resulting package tree back to a - lockfile. +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. -#### Omitting Dependency Types +#### `global` -You may omit certain types of dependencies by using the `--omit=` -config option. This may be specified multiple types on the command line. -To enter `omit` options in `.npmrc` files, use the following syntax: +* Default: false +* Type: Boolean -```ini -omit[] = dev -omit[] = optional -; etc... -``` +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + +#### `package-lock` + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +When package package-locks are disabled, automatic pruning of extraneous +modules will also be disabled. To remove extraneous modules with +package-locks disabled use `npm prune`. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. -The dependency types that may be omitted or included are: +#### `audit` -* `peer`: any `peerDependencies`, including those with a - `peerDependenciesMeta` entry specifying `optional: true` -* `optional`: dependencies listed in `optionalDependencies` -* `dev`: dependencies listed in `devDependencies` +* Default: true +* Type: Boolean -To re-include dependency, use the `--include` option, which may also be -specified multiple times. +When "true" submit audit reports alongside `npm install` runs to the default +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. -Legacy shorthands for `omit` settings are: +#### `bin-links` -* `--no-optional`: prevent optionalDependencies from being installed. Note - that their presence is still entered in the `package-lock.json` file, and - the tree is designed such that they _can_ be installed in the future. +* Default: true +* Type: Boolean -* `--prod`: prevent devDependencies from being installed. +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. -* `--only=prod`: omit `devDependencies` +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. -* `--also=dev`: include `devDependencies` +#### `fund` -#### Configuration Options Affecting Build Process +* Default: true +* Type: Boolean -* `--ignore-scripts`: do not execute any scripts defined in the - package.json. See [`scripts`](/using-npm/scripts). +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. -* `--no-audit`: disable sending audit reports to the configured registries. - See [`npm-audit`](npm-audit) for details on what is sent. +#### `dry-run` -* `--no-bin-links`: prevent npm from creating symlinks for any binaries the - package might contain. +* Default: false +* Type: Boolean -* `--no-fund`: suppress the message displayed at the end of each install - that acknowledges the number of dependencies looking for funding. See - [`npm-fund`](/commands/npm-fund) +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. -* `--dry-run`: Do not actually install anything into the `node_modules` - folder. Just build the intended tree in memory, and report on it. +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. -* `--no-save`: Do not save installed dependencies to `package.json` or - `package-lock.json`. + ### Algorithm diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md index 1a835001fc64f..e48be396ade1b 100644 --- a/docs/content/commands/npm-link.md +++ b/docs/content/commands/npm-link.md @@ -99,6 +99,170 @@ relevant metadata by running `npm install --package-lock-only`. If you _want_ to save the `file:` reference in your `package.json` and `package-lock.json` files, you can use `npm link --save` to do so. +### Configuration + + + +#### `save` + +* Default: true +* Type: Boolean + +Save installed packages to a package.json file as dependencies. + +When used with the `npm rm` command, removes the dependency from +package.json. + +#### `save-exact` + +* Default: false +* Type: Boolean + +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + +#### `package-lock` + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +When package package-locks are disabled, automatic pruning of extraneous +modules will also be disabled. To remove extraneous modules with +package-locks disabled use `npm prune`. + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `audit` + +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside `npm install` runs to the default +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + + + ### See Also * [npm developers](/using-npm/developers) diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md index 1172a3f0f560a..000b1006e8b35 100644 --- a/docs/content/commands/npm-logout.md +++ b/docs/content/commands/npm-logout.md @@ -27,23 +27,47 @@ connected to that scope, if set. ### Configuration -#### registry + + +#### `registry` -Default: https://registry.npmjs.org/ +* Default: "https://registry.npmjs.org/" +* Type: URL -The base URL of the npm package registry. If `scope` is also specified, -it takes precedence. +The base URL of the npm registry. -#### scope +#### `scope` -Default: The scope of your current project, if any, otherwise none. +* Default: the scope of the current project, if any, or "" +* Type: String -If specified, you will be logged out of the specified scope. See [`scope`](/using-npm/scope). +Associate an operation with a scope for a scoped registry. -```bash -npm logout --scope=@myco +Useful when logging in to or out of a private registry: + +``` +# log in, linking the scope to the custom registry +npm login --scope=@mycorp --registry=https://registry.mycorp.com + +# log out, removing the link and the auth token +npm logout --scope=@mycorp ``` +This will cause `@mycorp` to be mapped to the registry for future +installation of packages specified according to the pattern +`@mycorp/package`. + +This will also cause `npm init` to create a scoped package. + +``` +# accept all defaults, and create a package named "@foo/whatever", +# instead of just named "whatever" +npm init --scope=@foo --yes +``` + + + + ### See Also * [npm adduser](/commands/npm-adduser) diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md index 7abdbf82a5712..505dfd9c4316c 100644 --- a/docs/content/commands/npm-ls.md +++ b/docs/content/commands/npm-ls.md @@ -73,86 +73,111 @@ least the default human-readable `npm ls` output in npm v8. ### Configuration -#### all + + +#### `all` -* Default: `false` +* Default: false * Type: Boolean When running `npm outdated` and `npm ls`, setting `--all` will show all outdated or installed packages, rather than only those directly depended upon by the current project. -#### json +#### `json` * Default: false * Type: Boolean -Show information in JSON format. +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. -#### long +#### `long` * Default: false * Type: Boolean -Show extended information. +Show extended information in `ls`, `search`, and `help-search`. -#### parseable +#### `parseable` * Default: false * Type: Boolean -Show parseable output instead of tree view. +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. -#### global +#### `global` * Default: false * Type: Boolean -List packages in the global install prefix instead of in the current -project. +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. -#### depth +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` -* Type: Int +#### `depth` -Max display depth of the dependency tree. +* Default: `Infinity` if `--all` is set, otherwise `1` +* Type: null or Number -#### prod / production +The depth to go when recursing packages for `npm ls`. -* Type: Boolean -* Default: false +If not set, `npm ls` will show only the immediate dependencies of the root +project. If `--all` is set, then npm will show all dependencies by default. -Display only the dependency tree for packages in `dependencies`. +#### `omit` -#### dev / development +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) -* Type: Boolean -* Default: false +Dependency types to omit from the installation tree on disk. -Display only the dependency tree for packages in `devDependencies`. +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. -#### only +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. -* Type: String +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. -When "dev" or "development", is an alias to `dev`. +#### `link` -When "prod" or "production", is an alias to `production`. +* Default: false +* Type: Boolean -#### link +If true, then local installs will link if there is a suitable globally +installed package. -* Type: Boolean -* Default: false +Note that this means that local installs can cause things to be installed +into the global space at the same time. The link is only done if one of the +two conditions are met: + +* The package is not already installed globally, or +* the globally installed version is identical to the version that is being + installed locally. -Display only dependencies which are linked +When used with `npm ls`, only show packages that are linked. -#### unicode +#### `unicode` +* Default: false on windows, true on mac/unix systems with a unicode locale, + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables. * Type: Boolean -* Default: true -Whether to represent the tree structure using unicode characters. -Set it to false in order to use all-ansi output. +When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters instead of unicode glyphs. + + ### See Also diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md index 384f5b99fd42e..e6df560acfba3 100644 --- a/docs/content/commands/npm-org.md +++ b/docs/content/commands/npm-org.md @@ -58,6 +58,47 @@ You can use the `npm org` commands to manage and view users of an organization. It supports adding and removing users, changing their roles, listing them, and finding specific ones and their roles. +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + +#### `json` + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + +#### `parseable` + +* Default: false +* Type: Boolean + +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. + + + ### See Also * [using orgs](/using-npm/orgs) diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md index ee1157f332de0..cf43de7bbd553 100644 --- a/docs/content/commands/npm-outdated.md +++ b/docs/content/commands/npm-outdated.md @@ -85,41 +85,56 @@ A few things to note: ### Configuration -#### json + + +#### `all` * Default: false * Type: Boolean -Show information in JSON format. +When running `npm outdated` and `npm ls`, setting `--all` will show all +outdated or installed packages, rather than only those directly depended +upon by the current project. -#### long +#### `json` * Default: false * Type: Boolean -Show extended information. +Whether or not to output JSON data, rather than the normal output. -#### parseable +Not supported by all npm commands. + +#### `long` * Default: false * Type: Boolean -Show parseable output instead of tree view. +Show extended information in `ls`, `search`, and `help-search`. -#### global +#### `parseable` * Default: false * Type: Boolean -Check packages in the global install prefix instead of in the current -project. +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. -#### all +#### `global` * Default: false * Type: Boolean -Display all outdated dependencies on the tree. +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + ### See Also diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md index b30bbc8dc68ef..da22e899c2ebb 100644 --- a/docs/content/commands/npm-owner.md +++ b/docs/content/commands/npm-owner.md @@ -35,6 +35,30 @@ If you have two-factor authentication enabled with `auth-and-writes` (see [`npm-profile`](/commands/npm-profile)) then you'll need to include an otp on the command line when changing ownership with `--otp`. +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + + + ### See Also * [npm profile](/commands/npm-profile) diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md index de3eeb731a9e3..8652cba6852f7 100644 --- a/docs/content/commands/npm-pack.md +++ b/docs/content/commands/npm-pack.md @@ -12,22 +12,54 @@ npm pack [[<@scope>/]...] [--dry-run] ### Configuration -#### dry-run + + +#### `dry-run` -Do everything that pack usually does without actually packing anything. -That is, report on what would have gone into the tarball, but nothing -else. +* Default: false +* Type: Boolean -#### workspaces +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. -Enables workspaces context while creating tarballs. Tarballs for each -workspaces will be generated. +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. -#### workspace +#### `workspace` -Enables workspaces context and limits results to only those specified by -this config item. Tarballs will only be generated for the packages -named in the workspaces given here. +* Default: +* Type: String (can be set multiple times) + +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. + +Valid values for the `workspace` config are either: + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + ### Description diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md index f640bf060c750..7c7b66b181b4a 100644 --- a/docs/content/commands/npm-ping.md +++ b/docs/content/commands/npm-ping.md @@ -25,6 +25,19 @@ otherwise you will get: Ping error: {*Detail about error} ``` +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + + + ### See Also * [npm doctor](/commands/npm-doctor) diff --git a/docs/content/commands/npm-prefix.md b/docs/content/commands/npm-prefix.md index 4e3edf1902301..0523c9e19513d 100644 --- a/docs/content/commands/npm-prefix.md +++ b/docs/content/commands/npm-prefix.md @@ -33,6 +33,26 @@ npm prefix -g /usr/local ``` +### Configuration + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + + ### See Also * [npm root](/commands/npm-root) diff --git a/docs/content/commands/npm-profile.md b/docs/content/commands/npm-profile.md index b4e2fdaee6cb1..63aa46540d32d 100644 --- a/docs/content/commands/npm-profile.md +++ b/docs/content/commands/npm-profile.md @@ -71,12 +71,55 @@ support this interface. ### Details -All of the `npm profile` subcommands accept `--json` and `--parseable` and -will tailor their output based on those. Some of these commands may not be -available on non npmjs.com registries. +Some of these commands may not be available on non npmjs.com registries. + +### Configuration + + + +#### `registry` + +* Default: "https://registry.npmjs.org/" +* Type: URL + +The base URL of the npm registry. + +#### `json` + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + +#### `parseable` + +* Default: false +* Type: Boolean + +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + + ### See Also * [npm adduser](/commands/npm-adduser) -* [npm logout](/commands/npm-logout) +* [npm registry](/using-npm/registry) * [npm config](/commands/npm-config) +* [npmrc](/configuring-npm/npmrc) +* [npm owner](/commands/npm-owner) +* [npm whoami](/commands/npm-whoami) +* [npm token](/commands/npm-token) diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md index 088c1c3470faf..28890193295f2 100644 --- a/docs/content/commands/npm-prune.md +++ b/docs/content/commands/npm-prune.md @@ -33,6 +33,52 @@ only need this command with the `--production` flag. However, in the real world, operation is not always "normal". When crashes or mistakes happen, this command can help clean up any resulting garbage. +### Configuration + + + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + +#### `json` + +* Default: false +* Type: Boolean + +Whether or not to output JSON data, rather than the normal output. + +Not supported by all npm commands. + + + ### See Also * [npm uninstall](/commands/npm-uninstall) diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md index 10e65f895ec5b..0d25d7d29da8d 100644 --- a/docs/content/commands/npm-publish.md +++ b/docs/content/commands/npm-publish.md @@ -104,6 +104,92 @@ See [`developers`](/using-npm/developers) for full details on what's included in the published package, as well as details on how the package is built. +### Configuration + + + +#### `tag` + +* Default: "latest" +* Type: String + +If you ask npm to install a package and don't tell it a specific version, +then it will install the specified tag. + +Also the tag that is added to the package@version specified by the `npm tag` +command, if no explicit tag is given. + +When used by the `npm diff` command, this is the tag used to fetch the +tarball that will be compared with the local files by default. + +#### `access` + +* Default: 'restricted' for scoped packages, 'public' for unscoped packages +* Type: null, "restricted", or "public" + +When publishing scoped packages, the access level defaults to `restricted`. +If you want your scoped package to be publicly viewable (and installable) +set `--access=public`. The only valid values for `access` are `public` and +`restricted`. Unscoped packages _always_ have an access level of `public`. + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + +#### `otp` + +* Default: null +* Type: null or String + +This is a one-time password from a two-factor authenticator. It's needed +when publishing or changing package permissions with `npm access`. + +If not set, and a registry response fails with a challenge for a one-time +password, npm will prompt on the command line for one. + +#### `workspace` + +* Default: +* Type: String (can be set multiple times) + +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. + +Valid values for the `workspace` config are either: + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + + ### See Also * [npm-packlist package](http://npm.im/npm-packlist) diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md index 0a7ade6b165b4..144dd7b09cd3a 100644 --- a/docs/content/commands/npm-rebuild.md +++ b/docs/content/commands/npm-rebuild.md @@ -24,6 +24,50 @@ If one or more package names (and optionally version ranges) are provided, then only packages with a name and version matching one of the specifiers will be rebuilt. +### Configuration + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + + + ### See Also * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md index c3d0da3fdcf15..ade08e7d938e7 100644 --- a/docs/content/commands/npm-repo.md +++ b/docs/content/commands/npm-repo.md @@ -19,30 +19,53 @@ in the current folder and use the `repository` property. ### Configuration -#### browser + + +#### `browser` * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` -* Type: String or Boolean +* Type: null, Boolean, or String -The browser that is called by the `npm repo` command to open websites. +The browser that is called by npm commands to open websites. Set to `false` to suppress browser behavior and instead print urls to terminal. Set to `true` to use default system URL opener. -#### workspaces +#### `workspace` -Enables workspaces context while searching the `package.json` in the -current folder. Repo urls for the packages named in each workspace will -be opened. +* Default: +* Type: String (can be set multiple times) -#### workspace +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. -Enables workspaces context and limits results to only those specified by -this config item. Only the repo urls for the packages named in the -workspaces given here will be opened. +Valid values for the `workspace` config are either: +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. + +This value is not exported to the environment for child processes. + +#### `workspaces` + +* Default: false +* Type: Boolean + +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + + ### See Also diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md index 097c9fee7c9c3..4b905c2670695 100644 --- a/docs/content/commands/npm-restart.md +++ b/docs/content/commands/npm-restart.md @@ -34,6 +34,32 @@ If it does _not_ have a `"restart"` script specified, but it does have 8. poststart 9. postrestart +### Configuration + + + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + +#### `script-shell` + +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows +* Type: null or String + +The shell to use for scripts run with the `npm exec`, `npm run` and `npm +init ` commands. + + + ### See Also * [npm run-script](/commands/npm-run-script) diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md index 0d694ac876e92..2d072c16dec00 100644 --- a/docs/content/commands/npm-root.md +++ b/docs/content/commands/npm-root.md @@ -23,6 +23,26 @@ global_node_modules="$(npm root --global)" echo "Global packages installed in: ${global_node_modules}" ``` +### Configuration + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + + ### See Also * [npm prefix](/commands/npm-prefix) diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md index 6786312e0bf84..1d11a74faa244 100644 --- a/docs/content/commands/npm-run-script.md +++ b/docs/content/commands/npm-run-script.md @@ -33,7 +33,7 @@ For example: npm run test -- --grep="pattern" ``` -The arguments will only be passed to the script specified after ```npm run``` +The arguments will only be passed to the script specified after `npm run` and not to any `pre` or `post` script. The `env` script is a special built-in command that can be used to list @@ -141,60 +141,73 @@ packages. ### Configuration -#### if-present + + +#### `workspace` -* Type: Boolean -* Default: false +* Default: +* Type: String (can be set multiple times) -You can use the `--if-present` flag to avoid exiting with a non-zero exit code -when the script is undefined. This lets you run potentially undefined scripts -without breaking the execution chain. +Enable running a command in the context of the configured workspaces of the +current project while filtering by running only the workspaces defined by +this configuration option. -#### ignore-scripts +Valid values for the `workspace` config are either: -* Type: Boolean -* Default: false +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) -Skips running `pre` and `post` scripts. +When set for the `npm init` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. -#### script-shell +This value is not exported to the environment for child processes. -* Type: String -* Default: `null` +#### `workspaces` -Optional custom script to use to execute the command. If not defined defaults -to `/bin/sh` on Unix, defaults to `env.comspec` or `cmd.exe` on Windows. +* Default: false +* Type: Boolean -#### silent +Enable running a command in the context of **all** the configured +workspaces. + +This value is not exported to the environment for child processes. + +#### `if-present` -* Type: Boolean * Default: false +* Type: Boolean + +If true, npm will not exit with an error code when `run-script` is invoked +for a script that isn't defined in the `scripts` section of `package.json`. +This option can be used when it's desirable to optionally run a script when +it's present and fail if the script fails. This is useful, for example, when +running scripts that may only apply for some builds in an otherwise generic +CI setup. -You can use the `--silent` flag to prevent showing `npm ERR!` output on error. +#### `ignore-scripts` -#### workspace +* Default: false +* Type: Boolean -* Alias: `-w` -* Type: Array -* Default: `[]` +If true, npm does not run scripts specified in package.json files. -Enable running scripts in the context of workspaces while also filtering by -the provided names or paths provided. +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. -Valid values for the `workspace` config are either: -- Workspace names -- Path to a workspace directory -- Path to a parent workspace directory (will result to selecting all of the -children workspaces) +#### `script-shell` -#### workspaces +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows +* Type: null or String -* Alias: `--ws` -* Type: Boolean -* Default: `false` +The shell to use for scripts run with the `npm exec`, `npm run` and `npm +init ` commands. -Run scripts in the context of all configured workspaces for the current -project. + ### See Also diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md index 046c9334ff062..08c955e64b555 100644 --- a/docs/content/commands/npm-search.md +++ b/docs/content/commands/npm-search.md @@ -39,91 +39,94 @@ expression characters in most shells.) ### Configuration -All of the following can be defined in a `.npmrc` file, or passed as -parameters to the cli prefixed with `--` (e.g. `--json`) + + +#### `long` -#### description - -* Default: true +* Default: false * Type: Boolean -#### color - - * Default: true - * Type: Boolean - -Used as `--no-color`, disables color highlighting of matches in the -results. +Show extended information in `ls`, `search`, and `help-search`. -#### json +#### `json` * Default: false * Type: Boolean -Output search results as a JSON array. +Whether or not to output JSON data, rather than the normal output. -#### parseable +Not supported by all npm commands. + +#### `color` + +* Default: true unless the NO_COLOR environ is set to something other than '0' +* Type: "always" or Boolean + +If false, never shows colors. If `"always"` then always shows colors. If +true, then only prints color codes for tty file descriptors. + +#### `parseable` * Default: false * Type: Boolean -Output search results as lines with tab-separated columns. +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. -#### long +#### `description` -* Default: false +* Default: true * Type: Boolean -Display full package descriptions and other long text across multiple -lines. When disabled (which is the default) the output will -truncate search results to fit neatly on a single line. Modules with -extremely long names will fall on multiple lines. +Show the description in `npm search` -#### searchopts +#### `searchopts` * Default: "" * Type: String Space-separated options that are always passed to search. -#### searchexclude +#### `searchexclude` * Default: "" * Type: String Space-separated options that limit the results from search. -#### registry +#### `registry` - * Default: https://registry.npmjs.org/ - * Type: url +* Default: "https://registry.npmjs.org/" +* Type: URL -Search the specified registry for modules. If you have configured npm to -point to a different default registry (such as your internal private -module repository), `npm search` will also default to that registry when -searching. +The base URL of the npm registry. -### A note on caching +#### `prefer-online` -The npm cli caches search results with the same terms and options -locally in its cache. You can use the following to change how and when -the cli uses this cache. See [`npm cache`](/commands/npm-cache) for more -on how the cache works. +* Default: false +* Type: Boolean -#### prefer-online +If true, staleness checks for cached data will be forced, making the CLI +look for updates immediately even for fresh package data. -Forces staleness checks for cached searches, making the cli look for -updates immediately even for fresh search results. +#### `prefer-offline` -#### prefer-offline +* Default: false +* Type: Boolean -Bypasses staleness checks for cached searches. Missing data will still -be requested from the server. To force full offline mode, use `offline`. +If true, staleness checks for cached data will be bypassed, but missing data +will be requested from the server. To force full offline mode, use +`--offline`. + +#### `offline` + +* Default: false +* Type: Boolean -#### offline +Force offline mode: no network requests will be done during install. To +allow the CLI to fill in missing cache data, see `--prefer-offline`. -Forces full offline mode. Any searches not locally cached will result in -an error. + ### See Also diff --git a/docs/content/commands/npm-set-script.md b/docs/content/commands/npm-set-script.md index 73e61883c505b..c5d5df53203b1 100644 --- a/docs/content/commands/npm-set-script.md +++ b/docs/content/commands/npm-set-script.md @@ -28,16 +28,41 @@ npm set-script [