diff options
| -rw-r--r-- | Makefile | 7 | ||||
| -rw-r--r-- | docs/content/using-npm/config.md | 1378 | ||||
| -rw-r--r-- | scripts/config-doc.js | 50 |
3 files changed, 801 insertions, 634 deletions
@@ -47,7 +47,7 @@ docs-clean: ## build-time dependencies for the documentation dev-deps: - node bin/npm-cli.js install --only=dev --no-audit --ignore-scripts + node bin/npm-cli.js install --no-audit --ignore-scripts ## targets for man files, these are encouraged to be only built by running `make docs` or `make mandocs` man/man1/%.1: docs/content/commands/%.md scripts/docs-build.js @@ -68,6 +68,11 @@ man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js @[ -d man/man7 ] || mkdir -p man/man7 node scripts/docs-build.js $< $@ +# Any time the config definitions description changes, automatically +# update the documentation to account for it +docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js + node scripts/config-doc.js + test: dev-deps node bin/npm-cli.js test diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md index 1032adafb..435f9cee2 100644 --- a/docs/content/using-npm/config.md +++ b/docs/content/using-npm/config.md @@ -59,30 +59,46 @@ internal to npm, and are defaults if nothing else is specified. The following shorthands are parsed on the command-line: -* `-v`: `--version` -* `-h`, `-?`, `--help`, `-H`: `--usage` -* `-s`, `--silent`: `--loglevel silent` -* `-q`, `--quiet`: `--loglevel warn` -* `-d`: `--loglevel info` -* `-dd`, `--verbose`: `--loglevel verbose` -* `-ddd`: `--loglevel silly` +<!-- AUTOGENERATED CONFIG SHORTHANDS START --> +<!-- automatically generated, do not edit manually --> +* `-a`: `--all` +* `--enjoy-by`: `--before` +* `-c`: `--call` +* `--desc`: `--description` +* `-f`: `--force` * `-g`: `--global` -* `-C`: `--prefix` +* `-d`: `--loglevel info` +* `-s`: `--loglevel silent` +* `--silent`: `--loglevel silent` +* `--ddd`: `--loglevel silly` +* `--dd`: `--loglevel verbose` +* `--verbose`: `--loglevel verbose` +* `-q`: `--loglevel warn` +* `--quiet`: `--loglevel warn` * `-l`: `--long` * `-m`: `--message` -* `-p`, `--porcelain`: `--parseable` -* `-reg`: `--registry` -* `-f`: `--force` -* `-desc`: `--description` +* `--local`: `--no-global` +* `-n`: `--no-yes` +* `--no`: `--no-yes` +* `-p`: `--parseable` +* `--porcelain`: `--parseable` +* `-C`: `--prefix` +* `--readonly`: `--read-only` +* `--reg`: `--registry` * `-S`: `--save` -* `-P`: `--save-prod` -* `-D`: `--save-dev` -* `-O`: `--save-optional` * `-B`: `--save-bundle` +* `-D`: `--save-dev` * `-E`: `--save-exact` +* `-O`: `--save-optional` +* `-P`: `--save-prod` +* `-?`: `--usage` +* `-h`: `--usage` +* `-H`: `--usage` +* `--help`: `--usage` +* `-v`: `--version` * `-y`: `--yes` -* `-n`: `--yes false` -* `ll` and `la` commands: `ls --long` + +<!-- AUTOGENERATED CONFIG SHORTHANDS END --> If the specified configuration param resolves unambiguously to a known configuration parameter, then it is expanded to that configuration @@ -107,26 +123,39 @@ npm ls --global --parseable --long --loglevel info ### Config Settings -#### access +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +#### `_auth` + +* Default: null +* Type: null or String + +A basic-auth string to use when authenticating against the npm registry. + +Warning: This should generally not be set via a command-line option. It is +safer to use a registry-provided authentication bearer token stored in the +~/.npmrc file by running `npm login`. -* Default: `restricted` -* Type: Access +#### `access` -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 +* 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`. -#### 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. -#### allow-same-version +#### `allow-same-version` * Default: false * Type: Boolean @@ -134,78 +163,62 @@ upon by the current project. Prevents throwing an error when `npm version` is used to set the new version to the same value as the current version. -#### always-auth +#### `always-auth` * Default: false * Type: Boolean -Force npm to always require authentication when accessing the registry, -even for `GET` requests. - -#### also - -* Default: null -* Type: String +Force npm to always require authentication when accessing the registry, even +for `GET` requests. -When "dev" or "development" and running local `npm shrinkwrap`, -`npm outdated`, or `npm update`, is an alias for `--dev`. - -#### audit +#### `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. - -#### audit-level - -* Default: `"low"` -* Type: `'low'`, `'moderate'`, `'high'`, `'critical'` +registry and all registries configured for scopes. See the documentation for +[`npm audit`](/commands/npm-audit) for details on what is submitted. -The minimum level of vulnerability for `npm audit` to exit with -a non-zero exit code. +#### `audit-level` -#### auth-type - -* Default: `'legacy'` -* Type: `'legacy'`, `'sso'`, `'saml'`, `'oauth'` +* Default: null +* Type: "low", "moderate", "high", "critical", "none", or null -What authentication strategy to use with `adduser`/`login`. +The minimum level of vulnerability for `npm audit` to exit with a non-zero +exit code. -#### before +#### `before` -* Alias: enjoy-by * Default: null -* Type: Date +* Type: null or Date -If passed to `npm install`, will rebuild the npm tree such that only versions -that were available **on or before** the `--before` time get installed. -If there's no versions available for the current set of direct dependencies, the -command will error. +If passed to `npm install`, will rebuild the npm tree such that only +versions that were available **on or before** the `--before` time get +installed. If there's no versions available for the current set of direct +dependencies, the command will error. If the requested version is a `dist-tag` and the given tag does not pass the -`--before` filter, the most recent version less than or equal to that tag will -be used. For example, `foo@latest` might install `foo@1.2` even though `latest` -is `2.0`. +`--before` filter, the most recent version less than or equal to that tag +will be used. For example, `foo@latest` might install `foo@1.2` even though +`latest` is `2.0`. -#### bin-links +#### `bin-links` -* Default: `true` +* 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. +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. -#### 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 npm commands to open websites. @@ -214,87 +227,50 @@ terminal. Set to `true` to use default system URL opener. -#### ca +#### `ca` -* Default: The npm CA certificate -* Type: String, Array or null +* Default: null +* Type: null or String (can be set multiple times) The Certificate Authority signing certificate that is trusted for SSL -connections to the registry. Values should be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines -replaced by the string "\n". For example: +connections to the registry. Values should be in PEM format (Windows calls +it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string +"\n". For example: -```bash +```ini ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----" ``` -Set to `null` to only allow "known" registrars, or to a specific CA cert -to trust only that specific signing authority. +Set to `null` to only allow "known" registrars, or to a specific CA cert to +trust only that specific signing authority. Multiple CAs can be trusted by specifying an array of certificates: -```bash +```ini ca[]="..." ca[]="..." ``` See also the `strict-ssl` config. -#### cafile - -* Default: `null` -* Type: path - -A path to a file containing one or multiple Certificate Authority signing -certificates. Similar to the `ca` setting, but allows for multiple CA's, as -well as for the CA information to be stored in a file on disk. - -#### cache - -* Default: Windows: `%AppData%\npm-cache`, Posix: `~/.npm` -* Type: path - -The location of npm's cache directory. See [`npm cache`](/commands/npm-cache) +#### `cache` -#### cache-lock-stale +* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm` +* Type: Path -* Default: 60000 (1 minute) -* Type: Number - -The number of ms before cache folder lockfiles are considered stale. +The location of npm's cache directory. See [`npm +cache`](/commands/npm-cache) -#### cache-lock-retries - -* Default: 10 -* Type: Number +#### `cafile` -Number of times to retry to acquire a lock on cache folder lockfiles. - -#### cache-lock-wait - -* Default: 10000 (10 seconds) -* Type: Number - -Number of ms to wait for cache lock files to expire. - -#### cache-max - -* Default: Infinity -* Type: Number - -**DEPRECATED**: This option has been deprecated in favor of `--prefer-online`. - -`--cache-max=0` is an alias for `--prefer-online`. - -#### cache-min - -* Default: 10 -* Type: Number - -**DEPRECATED**: This option has been deprecated in favor of `--prefer-offline`. +* Default: null +* Type: Path -`--cache-min=9999 (or bigger)` is an alias for `--prefer-offline`. +A path to a file containing one or multiple Certificate Authority signing +certificates. Similar to the `ca` setting, but allows for multiple CA's, as +well as for the CA information to be stored in a file on disk. -#### call +#### `call` * Default: "" * Type: String @@ -306,154 +282,206 @@ custom command to be run along with the installed packages. npm exec --package yo --package generator-node --call "yo node" ``` -#### cert -* Default: `null` -* Type: String +#### `cert` -A client certificate to pass when accessing the registry. Values should be in -PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string "\n". For example: +* Default: null +* Type: null or String -```bash +A client certificate to pass when accessing the registry. Values should be +in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with +newlines replaced by the string "\n". For example: + +```ini cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----" ``` -It is _not_ the path to a certificate file (and there is no "certfile" option). +It is _not_ the path to a certificate file (and there is no "certfile" +option). -#### cidr +#### `ci-name` -* Default: `null` -* Type: String, Array, null +* Default: The name of the current CI system, or `null` when not on a known CI + platform. +* Type: null or String -This is a list of CIDR address to be used when configuring limited access tokens with the `npm token create` command. +The name of a continuous integration system. If not set explicitly, npm will +detect the current CI environment using the +[`@npmcli/ci-detect`](http://npm.im/@npmcli/ci-detect) module. -#### commit-hooks +#### `cidr` -* Default: `true` -* Type: Boolean +* Default: null +* Type: null or String (can be set multiple times) -Run git commit hooks when using the `npm version` command. +This is a list of CIDR address to be used when configuring limited access +tokens with the `npm token create` command. -#### color +#### `color` -* Default: true -* Type: Boolean or `"always"` +* 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. -If false, never shows colors. If `"always"` then always shows colors. -If true, then only prints color codes for tty file descriptors. +#### `commit-hooks` -This option can also be changed using the environment: colors are -disabled when the environment variable `NO_COLOR` is set to any value. +* Default: true +* Type: Boolean + +Run git commit hooks when using the `npm version` command. -#### depth +#### `depth` -* Default: null +* Default: `Infinity` if `--all` is set, otherwise `1` * Type: null or Number The depth to go when recursing packages for `npm ls`. -To make this default to `Infinity` instead of `null`, set `--all`. +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. -#### description +#### `description` * Default: true * Type: Boolean Show the description in `npm search` -#### dev +#### `diff` + +* Default: +* Type: String (can be set multiple times) + +Define arguments to compare in `npm diff`. + +#### `diff-dst-prefix` + +* Default: "b/" +* Type: String + +Destination prefix to be used in `npm diff` output. + +#### `diff-ignore-all-space` * Default: false * Type: Boolean -\[Deprecated\] Install `dev-dependencies` along with packages. +Ignore whitespace when comparing lines in `npm diff`. -#### dry-run +#### `diff-name-only` * 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`. This is NOT currently honored by some network related -commands, eg `dist-tags`, `owner`, etc. +Prints only filenames when using `npm diff`. -#### diff +#### `diff-no-prefix` -* Default: null -* Type: String, Array, null +* Default: false +* Type: Boolean -Define arguments to compare in `npm diff`. +Do not show any source or destination prefix in `npm diff` output. + +Note: this causes `npm diff` to ignore the `--diff-src-prefix` and +`--diff-dst-prefix` configs. + +#### `diff-src-prefix` -#### diff-name-only +* Default: "a/" +* Type: String + +Source prefix to be used in `npm diff` output. + +#### `diff-text` * Default: false * Type: Boolean -Prints only filenames when using `npm diff`. +Treat all files as text in `npm diff`. -#### diff-unified +#### `diff-unified` -* Type: number -* Default: `3` +* Default: 3 +* Type: Number The number of lines of context to print in `npm diff`. -#### diff-ignore-all-space +#### `dry-run` -* Type: Boolean * Default: false +* Type: Boolean -Ignore whitespace when comparing lines in `npm diff. +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`. -#### diff-no-prefix +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + +#### `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`. + +#### `engine-strict` -* Type: Boolean * Default: false +* Type: Boolean -Do not show any source or destination prefix in `npm diff` output. +If set to true, then npm will stubbornly refuse to install (or even consider +installing) any package that claims to not be compatible with the current +Node.js version. -#### diff-src-prefix +This can be overridden by setting the `--force` flag. -* Type: String -* Default: `"a/"` +#### `fetch-retries` -Source prefix to be used in `npm diff` output. +* Default: 2 +* Type: Number -#### diff-dst-prefix +The "retries" config for the `retry` module to use when fetching packages +from the registry. -* Type: String -* Default: `"b/"` +npm will retry idempotent read requests to the registry in the case of +network failures or 5xx HTTP errors. -Destination prefix to be used in `npm diff` output. +#### `fetch-retry-factor` -#### diff-text +* Default: 10 +* Type: Number -* Alias: `-a` -* Type: Boolean -* Default: false +The "factor" config for the `retry` module to use when fetching packages. -Treat all files as text in `npm diff`. +#### `fetch-retry-maxtimeout` -#### editor +* Default: 60000 (1 minute) +* Type: Number + +The "maxTimeout" config for the `retry` module to use when fetching +packages. + +#### `fetch-retry-mintimeout` -* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, - or `"notepad"` on Windows. -* Type: path +* Default: 10000 (10 seconds) +* Type: Number -The command to run for `npm edit` or `npm config edit`. +The "minTimeout" config for the `retry` module to use when fetching +packages. -#### engine-strict +#### `fetch-timeout` -* Default: false -* Type: Boolean +* Default: 300000 (5 minutes) +* Type: Number -If set to true, then npm will stubbornly refuse to install (or even -consider installing) any package that claims to not be compatible with -the current Node.js version. +The maximum amount of time to wait for HTTP requests to complete. -#### force +#### `force` * Default: false * Type: Boolean @@ -467,17 +495,16 @@ mistakes, unnecessary performance degradation, and malicious input. * 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 `--engines-strict` is enabled. + 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 a module to be installed as a direct dependency of itself. * Allow unpublishing all versions of a published package. * Allow conflicting peerDependencies to be installed in the root project. 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! -#### foreground-scripts +#### `foreground-scripts` * Default: false * Type: Boolean @@ -486,249 +513,217 @@ Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process. -Note that this will generally make installs run slower, and be much -noisier, but can be useful for debugging. +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. -#### format-package-lock +#### `format-package-lock` * Default: true * Type: Boolean -Format `package-lock.json` or `npm-shrinkwrap.json` as a human readable file. +Format `package-lock.json` or `npm-shrinkwrap.json` as a human readable +file. -#### fund +#### `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. - -#### fetch-retries - -* Default: 2 -* Type: Number - -The "retries" config for the `retry` module to use when fetching -packages from the registry. - -#### fetch-retry-factor - -* Default: 10 -* Type: Number - -The "factor" config for the `retry` module to use when fetching -packages. - -#### fetch-retry-mintimeout - -* Default: 10000 (10 seconds) -* Type: Number - -The "minTimeout" config for the `retry` module to use when fetching -packages. - -#### fetch-retry-maxtimeout - -* Default: 60000 (1 minute) -* Type: Number - -The "maxTimeout" config for the `retry` module to use when fetching -packages. - -#### fetch-timeout - -* Default: 300000 (5 minutes) -* Type: Number - -The maximum amount of time to wait for HTTP requests to complete. +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. -#### git +#### `git` -* Default: `"git"` +* Default: "git" * Type: String -The command to use for git commands. If git is installed on the -computer, but is not in the `PATH`, then set this to the full path to -the git binary. +The command to use for git commands. If git is installed on the computer, +but is not in the `PATH`, then set this to the full path to the git binary. -#### git-tag-version +#### `git-tag-version` -* Default: `true` +* Default: true * Type: Boolean Tag the commit when using the `npm version` command. -#### global +#### `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 +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. +* 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` -#### globalconfig - -* Default: {prefix}/etc/npmrc -* Type: path - -The config file to read for global config options. - -#### global-style +#### `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 +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. +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. + +#### `globalconfig` + +* Default: The global --prefix setting plus 'etc/npmrc'. For example, + '/usr/local/etc/npmrc' +* Type: Path -#### heading +The config file to read for global config options. + +#### `heading` -* Default: `"npm"` +* Default: "npm" * Type: String The string that starts all the debugging log output. -#### https-proxy +#### `https-proxy` * Default: null -* Type: url +* Type: null or URL A proxy to use for outgoing https requests. If the `HTTPS_PROXY` or `https_proxy` or `HTTP_PROXY` or `http_proxy` environment variables are set, -proxy settings will be honored by the underlying `request` library. +proxy settings will be honored by the underlying `make-fetch-happen` +library. -#### if-present +#### `if-present` * 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. +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. -#### ignore-prepublish +#### `ignore-scripts` * Default: false * Type: Boolean -If true, npm will not run `prepublish` scripts. +If true, npm does not run scripts specified in package.json files. -#### ignore-scripts +#### `include` -* Default: false -* Type: Boolean +* Default: +* Type: "prod", "dev", "optional", or "peer" (can be set multiple times) -If true, npm does not run scripts specified in package.json files. +Option that allows for defining which types of dependencies to install. -#### include +This is the inverse of `--omit=<type>`. -* Default: `[prod|dev|optional|peer]` -* Type: Array +Dependency types specified in `--include` will not be omitted, regardless of +the order in which omit/include are specified on the command-line. -Option that allows for defining which types of dependencies to install. +#### `include-staged` -#### init-module +* Default: false +* Type: Boolean -* Alias: `init.module` -* Default: ~/.npm-init.js -* Type: path +Allow installing "staged" published packages, as defined by [npm RFC PR +#92](https://github.com/npm/rfcs/pull/92). -A module that will be loaded by the `npm init` command. See the -documentation for the -[init-package-json](https://github.com/npm/init-package-json) module -for more information, or [npm init](/commands/npm-init). +This is experimental, and not implemented by the npm public registry. -#### init-author-name +#### `init-author-email` -* Alias: `init.author.name` * Default: "" * Type: String -The value `npm init` should use by default for the package author's name. +The value `npm init` should use by default for the package author's email. -#### init-author-email +#### `init-author-name` -* Alias: `init.author.email` * Default: "" * Type: String -The value `npm init` should use by default for the package author's email. +The value `npm init` should use by default for the package author's name. -#### init-author-url +#### `init-author-url` -* Alias: `init.author.url` * Default: "" -* Type: String +* Type: "" or URL -The value `npm init` should use by default for the package author's homepage. +The value `npm init` should use by default for the package author's +homepage. -#### init-license +#### `init-license` -* Alias: `init.license` * Default: "ISC" * Type: String The value `npm init` should use by default for the package license. -#### init-version +#### `init-module` + +* Default: "~/.npm-init.js" +* Type: Path + +A module that will be loaded by the `npm init` command. See the +documentation for the +[init-package-json](https://github.com/npm/init-package-json) module for +more information, or [npm init](/commands/npm-init). + +#### `init-version` -* Alias: `init.version` * Default: "1.0.0" -* Type: semver +* Type: SemVer string -The value that `npm init` should use by default for the package -version number, if not already set in package.json. +The value that `npm init` should use by default for the package version +number, if not already set in package.json. -#### json +#### `json` * Default: false * Type: Boolean Whether or not to output JSON data, rather than the normal output. -This feature is currently experimental, and the output data structures for many -commands is either not implemented in JSON yet, or subject to change. Only the -output from `npm ls --json` and `npm search --json` are currently valid. +This feature is currently experimental, and the output data structures for +many commands is either not implemented in JSON yet, or subject to change. +Only the output from `npm ls --json` and `npm search --json` are currently +valid. -#### key +#### `key` -* Default: `null` -* Type: String +* Default: null +* Type: null or String -A client key to pass when accessing the registry. Values should be in PEM +A client key to pass when accessing the registry. Values should be in PEM format with newlines replaced by the string "\n". For example: -```json +```ini key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----" ``` It is _not_ the path to a key file (and there is no "keyfile" option). -#### legacy-bundling +#### `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 +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. -#### legacy-peer-deps +#### `legacy-peer-deps` * Default: false * Type: Boolean @@ -736,9 +731,8 @@ will be preferred. Causes npm to completely ignore `peerDependencies` when building a package tree, as in npm versions 3 through 6. -If a package cannot be installed because of overly strict -`peerDependencies` that collide, it provides a way to move forward -resolving the situation. +If a package cannot be installed because of overly strict `peerDependencies` +that collide, it provides a way to move forward resolving the situation. This differs from `--omit=peer`, in that `--omit=peer` will avoid unpacking `peerDependencies` on disk, but will still design a tree such that @@ -747,7 +741,7 @@ This differs from `--omit=peer`, in that `--omit=peer` will avoid unpacking Use of `legacy-peer-deps` is not recommended, as it will not enforce the `peerDependencies` contract that meta-dependencies may rely on. -#### link +#### `link` * Default: false * Type: Boolean @@ -755,57 +749,57 @@ Use of `legacy-peer-deps` is not recommended, as it will not enforce the If true, then local installs will link if there is a suitable globally installed package. -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: +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. +* the globally installed version is identical to the version that is being + installed locally. -#### local-address +#### `local-address` -* Default: undefined +* Default: null * Type: IP Address -The IP address of the local interface to use when making connections -to the npm registry. Must be IPv4 in versions of Node prior to 0.12. +The IP address of the local interface to use when making connections to the +npm registry. Must be IPv4 in versions of Node prior to 0.12. -#### loglevel +#### `loglevel` * Default: "notice" -* Type: String -* Values: "silent", "error", "warn", "notice", "http", "timing", "info", - "verbose", "silly" +* Type: "silent", "error", "warn", "notice", "http", "timing", "info", + "verbose", or "silly" -What level of logs to report. On failure, *all* logs are written to +What level of logs to report. On failure, *all* logs are written to `npm-debug.log` in the current working directory. -Any logs of a higher level than the setting are shown. The default is "notice". +Any logs of a higher level than the setting are shown. The default is +"notice". -#### logs-max +#### `logs-max` * Default: 10 * Type: Number The maximum number of log files to store. -#### long +#### `long` * Default: false * Type: Boolean Show extended information in `npm ls` and `npm search`. -#### maxsockets +#### `maxsockets` -* Default: 50 +* Default: Infinity * Type: Number The maximum number of connections to use per origin (protocol/host/port -combination). Passed to the `http` `Agent` used to make the request. +combination). -#### message +#### `message` * Default: "%s" * Type: String @@ -814,73 +808,83 @@ Commit message which is used by `npm version` when creating version commit. Any "%s" in the message will be replaced with the version number. -#### node-options +#### `node-options` * Default: null -* Type: String +* Type: null or String Options to pass through to Node.js via the `NODE_OPTIONS` environment -variable. This does not impact how npm itself is executed but it does -impact how lifecycle scripts are called. +variable. This does not impact how npm itself is executed but it does impact +how lifecycle scripts are called. -#### node-version +#### `node-version` -* Default: process.version -* Type: semver or false +* Default: Node.js `process.version` value +* Type: SemVer string -The node version to use when checking a package's `engines` map. +The node version to use when checking a package's `engines` setting. -#### noproxy +#### `noproxy` -* Default: null -* Type: String or Array +* Default: The value of the NO_PROXY environment variable +* Type: String (can be set multiple times) -A comma-separated string or an array of domain extensions that a proxy should not be used for. +Domain extensions that should bypass any proxies. -#### offline +Also accepts a comma-delimited string. -* Default: false -* Type: Boolean +#### `npm-version` -Force offline mode: no network requests will be done during install. To allow -the CLI to fill in missing cache data, see `--prefer-offline`. +* Default: Output of `npm --version` +* Type: SemVer string -#### only +The npm version to use when checking a package's `engines` setting. -* Default: null -* Type: String +#### `offline` + +* Default: false +* Type: Boolean -When "dev" or "development" and running local `npm install` without any -arguments, only devDependencies (and their dependencies) are installed. +Force offline mode: no network requests will be done during install. To +allow the CLI to fill in missing cache data, see `--prefer-offline`. -When "dev" or "development" and running local `npm ls`, `npm outdated`, or -`npm update`, is an alias for `--dev`. +#### `omit` -When "prod" or "production" and running local `npm install` without any -arguments, only non-devDependencies (and their dependencies) are -installed. +* Default: 'dev' if the NODE_ENV environment variable is set to 'production', + otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) -When "prod" or "production" and running local `npm ls`, `npm outdated`, or -`npm update`, is an alias for `--production`. +Dependency types to omit from the installation tree on disk. -#### optional +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. -* Default: true -* Type: Boolean +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. -Attempt to install packages in the `optionalDependencies` object. Note -that if these packages fail to install, the overall installation -process is not aborted. +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. -#### otp +#### `otp` * Default: null -* Type: Number +* Type: null or String -This is a one-time password from a two-factor authenticator. It's needed +This is a one-time password from a two-factor authenticator. It's needed when publishing or changing package permissions with `npm access`. -#### package-lock +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. + +#### `package` + +* Default: +* Type: String (can be set multiple times) + +The package to install for [`npm exec`](/commands/npm-exec) + +#### `package-lock` * Default: true * Type: Boolean @@ -889,75 +893,63 @@ 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 +modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. -This option is an alias for `--shrinkwrap`. - -#### package-lock-only +#### `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. +If set to true, it will update only the `package-lock.json`, instead of +checking `node_modules` and downloading dependencies. -#### parseable +#### `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. +Output parseable results from commands that write to standard output. For +`npm search`, this will be tab-separated table format. -#### prefer-offline +#### `prefer-offline` * Default: false * Type: Boolean 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`. +will be requested from the server. To force full offline mode, use +`--offline`. -This option is effectively equivalent to `--cache-min=9999999`. - -#### prefer-online +#### `prefer-online` * Default: false * Type: Boolean -If true, staleness checks for cached data will be forced, making the CLI look -for updates immediately even for fresh package data. +If true, staleness checks for cached data will be forced, making the CLI +look for updates immediately even for fresh package data. -#### prefix +#### `prefix` -* Default: see [folders](/configuring-npm/folders) -* Type: path +* Default: In global mode, the folder where the node executable is installed. + In local mode, the nearest parent folder containing either a package.json + file or a node_modules folder. +* Type: Path -The location to install global items. If set on the command line, then -it forces non-global commands to run in the specified folder. +The location to install global items. If set on the command line, then it +forces non-global commands to run in the specified folder. -#### preid +#### `preid` * Default: "" * Type: String -The "prerelease identifier" to use as a prefix for the "prerelease" part of a -semver. Like the `rc` in `1.2.0-rc.8`. - -#### production - -* Default: false -* Type: Boolean - -Set to true to run in "production" mode. +The "prerelease identifier" to use as a prefix for the "prerelease" part of +a semver. Like the `rc` in `1.2.0-rc.8`. -1. devDependencies are not installed at the topmost level when running - local `npm install` without any arguments. -2. Set the NODE_ENV="production" for lifecycle scripts. +#### `progress` -#### progress - -* Default: true, unless TRAVIS or CI env vars set. +* Default: `true` unless running in a known CI system * Type: Boolean When set to `true`, npm will display a progress bar during time intensive @@ -965,56 +957,48 @@ operations, if `process.stderr` is a TTY. Set to `false` to suppress the progress bar. -#### proxy +#### `proxy` * Default: null -* Type: url +* Type: null, false, or URL A proxy to use for outgoing http requests. If the `HTTP_PROXY` or -`http_proxy` environment variables are set, proxy settings will be -honored by the underlying `request` library. +`http_proxy` environment variables are set, proxy settings will be honored +by the underlying `request` library. -#### read-only +#### `read-only` * Default: false * Type: Boolean -This is used to mark a token as unable to publish when configuring limited access tokens with the `npm token create` command. +This is used to mark a token as unable to publish when configuring limited +access tokens with the `npm token create` command. -#### rebuild-bundle +#### `rebuild-bundle` * Default: true * Type: Boolean Rebuild bundled dependencies after installation. -#### registry - -* Default: https://registry.npmjs.org/ -* Type: url - -The base URL of the npm package registry. +#### `registry` -#### rollback - -* Default: true -* Type: Boolean +* Default: "https://registry.npmjs.org/" +* Type: URL -Remove failed installs. +The base URL of the npm registry. -#### save +#### `save` * Default: true * Type: Boolean Save installed packages to a package.json file as dependencies. -When used with the `npm rm` command, it removes it from the `dependencies` -object. +When used with the `npm rm` command, removes the dependency from +package.json. -Only works if there is already a package.json file present. - -#### save-bundle +#### `save-bundle` * Default: false * Type: Boolean @@ -1023,120 +1007,94 @@ If a package would be saved at install time by the use of `--save`, `--save-dev`, or `--save-optional`, then also put it in the `bundleDependencies` list. -When used with the `npm rm` command, it removes it from the -bundledDependencies list. +Ignore if `--save-peer` is set, since peerDependencies cannot be bundled. -#### save-prod +#### `save-dev` * Default: false * Type: Boolean -Makes sure that a package will be saved into `dependencies` specifically. This -is useful if a package already exists in `devDependencies` or -`optionalDependencies`, but you want to move it to be a production dep. This is -also the default behavior if `--save` is true, and neither `--save-dev` or -`--save-optional` are true. +Save installed packages to a package.json file as `devDependencies`. -#### save-dev +#### `save-exact` * Default: false * Type: Boolean -Save installed packages to a package.json file as `devDependencies`. - -When used with the `npm rm` command, it removes it from the -`devDependencies` object. - -Only works if there is already a package.json file present. +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. -#### save-exact +#### `save-optional` * Default: false * Type: Boolean -Dependencies saved to package.json using `--save`, `--save-dev` or -`--save-optional` will be configured with an exact version rather than -using npm's default semver range operator. +Save installed packages to a package.json file as `optionalDependencies`. -#### save-optional +#### `save-peer` * Default: false * Type: Boolean -Save installed packages to a package.json file as -optionalDependencies. - -When used with the `npm rm` command, it removes it from the -`devDependencies` object. +Save installed packages. to a package.json file as `peerDependencies` -Only works if there is already a package.json file present. +#### `save-prefix` -#### save-prefix - -* Default: '^' +* Default: "^" * Type: String Configure how versions of packages installed to a package.json file via `--save` or `--save-dev` get prefixed. -For example if a package has version `1.2.3`, by default its version is -set to `^1.2.3` which allows minor upgrades for that package, but after -`npm config set save-prefix='~'` it would be set to `~1.2.3` which only allows +For example if a package has version `1.2.3`, by default its version is set +to `^1.2.3` which allows minor upgrades for that package, but after `npm +config set save-prefix='~'` it would be set to `~1.2.3` which only allows patch upgrades. -#### scope - -* Default: the scope of the current project, if any, or "" -* Type: String - -Associate an operation with a scope for a scoped registry. Useful when logging -in to a private registry for the first time: -`npm login --scope=@organization --registry=registry.organization.com`, which -will cause `@organization` to be mapped to the registry for future installation -of packages specified according to the pattern `@organization/package`. +#### `save-prod` -#### script-shell +* Default: false +* Type: Boolean -* Default: `null` -* Type: path +Save installed packages into `dependencies` specifically. This is useful if +a package already exists in `devDependencies` or `optionalDependencies`, but +you want to move it to be a non-optional production dependency. -The shell to use for scripts run with the `npm run` command. +This is the default behavior if `--save` is true, and neither `--save-dev` +or `--save-optional` are true. -#### scripts-prepend-node-path +#### `scope` -* Default: "warn-only" -* Type: Boolean, `"auto"` or `"warn-only"` +* Default: the scope of the current project, if any, or "" +* Type: String -If set to `true`, add the directory in which the current `node` executable -resides to the `PATH` environment variable when running scripts, -even if that means that `npm` will invoke a different `node` executable than -the one which it is running. +Associate an operation with a scope for a scoped registry. -If set to `false`, never modify `PATH` with that. +Useful when logging in to a private registry for the first time: -If set to `"warn-only"`, never modify `PATH` but print a warning if `npm` thinks -that you may want to run it with `true`, e.g. because the `node` executable -in the `PATH` is not the one `npm` was invoked with. +```bash +npm login --scope=@mycorp --registry=https://registry.mycorp.com +``` -If set to `auto`, only add that directory to the `PATH` environment variable -if the `node` executable with which `npm` was invoked and the one that is found -first on the `PATH` are different. +This will cause `@mycorp` to be mapped to the registry for future +installation of packages specified according to the pattern +`@mycorp/package`. -#### searchexclude +#### `script-shell` -* Default: "" -* Type: String +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows +* Type: null or String -Space-separated options that limit the results from search. +The shell to use for scripts run with the `npm run` command. -#### searchopts +#### `searchexclude` * Default: "" * Type: String -Space-separated options that are always passed to search. +Space-separated options that limit the results from search. -#### searchlimit +#### `searchlimit` * Default: 20 * Type: Number @@ -1144,33 +1102,30 @@ Space-separated options that are always passed to search. Number of items to limit search results to. Will not apply at all to legacy searches. -#### searchstaleness +#### `searchopts` -* Default: 900 (15 minutes) +* Default: "" +* Type: String + +Space-separated options that are always passed to search. + +#### `searchstaleness` + +* Default: 900 * Type: Number The age of the cache, in seconds, before another registry request is made if using legacy search endpoint. -#### 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. -#### shrinkwrap - -* Default: true -* Type: Boolean - -If set to false, then ignore `npm-shrinkwrap.json` files when installing. This -will also prevent _writing_ `npm-shrinkwrap.json` if `save` is true. - -This option is an alias for `--package-lock`. - -#### sign-git-commit +#### `sign-git-commit` * Default: false * Type: Boolean @@ -1178,36 +1133,21 @@ This option is an alias for `--package-lock`. If set to true, then the `npm version` command will commit the new package version using `-S` to add a signature. -Note that git requires you to have set up GPG keys in your git configs -for this to work properly. +Note that git requires you to have set up GPG keys in your git configs for +this to work properly. -#### sign-git-tag +#### `sign-git-tag` * Default: false * Type: Boolean -If set to true, then the `npm version` command will tag the version -using `-s` to add a signature. - -Note that git requires you to have set up GPG keys in your git configs -for this to work properly. - -#### sso-poll-frequency - -* Default: 500 -* Type: Number - -When used with SSO-enabled `auth-type`s, configures how regularly the registry -should be polled while the user is completing authentication. - -#### sso-type - -* Default: 'oauth' -* Type: 'oauth', 'saml', or null +If set to true, then the `npm version` command will tag the version using +`-s` to add a signature. -If `--auth-type=sso`, the type of SSO type to use. +Note that git requires you to have set up GPG keys in your git configs for +this to work properly. -#### strict-peer-deps +#### `strict-peer-deps` * Default: false * Type: Boolean @@ -1217,145 +1157,317 @@ 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` 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 the warning is -treated as a failure. +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. -#### strict-ssl +#### `strict-ssl` * Default: true * Type: Boolean -Whether or not to do SSL key validation when making requests to the -registry via https. +Whether or not to do SSL key validation when making requests to the registry +via https. See also the `ca` config. -#### tag +#### `tag` -* Default: latest +* 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. +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. +Also the tag that is added to the package@version specified by the `npm tag` +command, if no explicit tag is given. -#### tag-version-prefix +#### `tag-version-prefix` -* Default: `"v"` +* Default: "v" * Type: String If set, alters the prefix used when tagging a new version when performing a -version increment using `npm-version`. To remove the prefix altogether, set it -to the empty string: `""`. +version increment using `npm-version`. To remove the prefix altogether, set +it to the empty string: `""`. -Because other tools may rely on the convention that npm version tags look like -`v1.0.0`, _only use this property if it is absolutely necessary_. In +Because other tools may rely on the convention that npm version tags look +like `v1.0.0`, _only use this property if it is absolutely necessary_. In particular, use care when overriding this setting for public packages. -#### timing +#### `timing` -* Default: `false` +* Default: false * Type: Boolean If true, writes an `npm-debug` log to `_logs` and timing information to -`_timing.json`, both in your cache. `_timing.json` is a newline delimited -list of JSON objects. You can quickly view it with this -[json](https://www.npmjs.com/package/json) command line: -`json -g < ~/.npm/_timing.json`. +`_timing.json`, both in your cache, even if the command completes +successfully. `_timing.json` is a newline delimited list of JSON objects. -#### tmp +You can quickly view it with this [json](https://npm.im/json) command line: +`npm exec -- json -g < ~/.npm/_timing.json`. -* Default: TMPDIR environment variable, or "/tmp" -* Type: path +#### `umask` -Where to store temporary files and folders. All temp files are deleted -on success, but left behind on failure for forensic purposes. +* Default: 0 +* Type: Octal numeric string in range 0000..0777 (0..511) + +The "umask" value to use when setting the file creation mode on files and +folders. + +Folders and executables are given a mode which is `0o777` masked against +this value. Other files are given a mode which is `0o666` masked against +this value. -#### unicode +Note that the underlying system will _also_ apply its own umask value to +files and folders that are created, and npm does not circumvent this, but +rather adds the `--umask` config to it. -* Default: false on windows, true on mac/unix systems with a unicode locale +Thus, the effective default umask value on most POSIX systems is 0o22, +meaning that folders and executables are created with a mode of 0o755 and +other files are created with a mode of 0o644. + +#### `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 -When set to true, npm uses unicode characters in the tree output. When -false, it uses ascii characters to draw trees. +When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters instead of unicode glyphs. -#### update-notifier +#### `update-notifier` * Default: true * Type: Boolean -Set to false to suppress the update notification when using an older -version of npm than the latest. +Set to false to suppress the update notification when using an older version +of npm than the latest. -#### usage +#### `usage` * Default: false * Type: Boolean -Set to show short usage output (like the -H output) -instead of complete help when doing [`npm help`](/commands/npm-help). - -#### userconfig +Show short usage output about the command specified. -* Default: ~/.npmrc -* Type: path +#### `user-agent` -The location of user-level configuration settings. - -#### umask +* Default: "npm/{npm-version} node/{node-version} {platform} {arch} {ci}" +* Type: String -* Default: 022 -* Type: Octal numeric string in range 0000..0777 (0..511) +Sets the User-Agent request header. The following fields are replaced with +their actual counterparts: -The "umask" value to use when setting the file creation mode on files -and folders. +* `{npm-version}` - The npm version in use +* `{node-version}` - The Node.js version in use +* `{platform}` - The value of `process.platform` +* `{arch}` - The value of `process.arch` +* `{ci}` - The value of the `ci-name` config, if set, prefixed with `ci/`, or + an empty string if `ci-name` is empty. -Folders and executables are given a mode which is `0777` masked against -this value. Other files are given a mode which is `0666` masked against -this value. Thus, the defaults are `0755` and `0644` respectively. +#### `userconfig` -#### user-agent +* Default: "~/.npmrc" +* Type: Path -* Default: node/{process.version} {process.platform} {process.arch} -* Type: String +The location of user-level configuration settings. -Sets a User-Agent to the request header +This may be overridden by the `npm_config_userconfig` environment variable +or the `--userconfig` command line option, but may _not_ be overridden by +settings in the `globalconfig` file. -#### version +#### `version` * Default: false -* Type: boolean +* Type: Boolean If true, output the npm version and exit successfully. Only relevant when specified explicitly on the command line. -#### versions +#### `versions` * Default: false -* Type: boolean +* Type: Boolean -If true, output the npm version as well as node's `process.versions` map, and -exit successfully. +If true, output the npm version as well as node's `process.versions` map and +the version in the current working directory's `package.json` file if one +exists, and exit successfully. Only relevant when specified explicitly on the command line. -#### 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. +#### `yes` + +* Default: false +* Type: Boolean + +Automatically answer "yes" to any prompts that npm might print on the +command line. + +#### `also` + +* Default: null +* Type: null, "dev", or "development" +* DEPRECATED: Please use --include=dev instead. + +When set to `dev` or `development`, this is an alias for `--include=dev`. + +#### `auth-type` + +* Default: "legacy" +* Type: "legacy", "sso", "saml", or "oauth" +* DEPRECATED: This method of SSO/SAML/OAuth is deprecated and will be removed + in a future version of npm in favor of web-based login. + +What authentication strategy to use with `adduser`/`login`. + +#### `cache-max` + +* Default: Infinity +* Type: Number +* DEPRECATED: This option has been deprecated in favor of `--prefer-online` + +`--cache-max=0` is an alias for `--prefer-online` + +#### `cache-min` + +* Default: 0 +* Type: Number +* DEPRECATED: This option has been deprecated in favor of `--prefer-offline`. + +`--cache-min=9999 (or bigger)` is an alias for `--prefer-offline`. + +#### `init.author.email` + +* Default: "" +* Type: String +* DEPRECATED: Use `--init-author-email` instead. + +Alias for `--init-author-email` + +#### `init.author.name` + +* Default: "" +* Type: String +* DEPRECATED: Use `--init-author-name` instead. + +Alias for `--init-author-name` + +#### `init.author.url` + +* Default: "" +* Type: "" or URL +* DEPRECATED: Use `--init-author-url` instead. + +Alias for `--init-author-url` + +#### `init.license` + +* Default: "ISC" +* Type: String +* DEPRECATED: Use `--init-license` instead. + +Alias for `--init-license` + +#### `init.module` + +* Default: "~/.npm-init.js" +* Type: Path +* DEPRECATED: Use `--init-module` instead. + +Alias for `--init-module` + +#### `init.version` + +* Default: "1.0.0" +* Type: SemVer string +* DEPRECATED: Use `--init-version` instead. + +Alias for `--init-version` + +#### `only` + +* Default: null +* Type: null, "prod", or "production" +* DEPRECATED: Use `--omit=dev` to omit dev dependencies from the install. + +When set to `prod` or `production`, this is an alias for `--omit=dev`. + +#### `optional` + +* Default: null +* Type: null or Boolean +* DEPRECATED: Use `--omit=optional` to exclude optional dependencies, or + `--include=optional` to include them. + +Default value does install optional deps unless otherwise omitted. + +Alias for --include=optional or --omit=optional + +#### `production` + +* Default: false +* Type: Boolean +* DEPRECATED: Use `--omit=dev` instead. + +Alias for `--omit=dev` + +#### `shrinkwrap` + +* Default: true +* Type: Boolean +* DEPRECATED: Use the --package-lock setting instead. + +Alias for --package-lock + +#### `sso-poll-frequency` + +* Default: 500 +* Type: Number +* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a + future version of npm in favor of web-based login. + +When used with SSO-enabled `auth-type`s, configures how regularly the +registry should be polled while the user is completing authentication. + +#### `sso-type` + +* Default: "oauth" +* Type: null, "oauth", or "saml" +* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a + future version of npm in favor of web-based login. + +If `--auth-type=sso`, the type of SSO type to use. + +#### `tmp` + +* Default: The value returned by the Node.js `os.tmpdir()` method + <https://nodejs.org/api/os.html#os_os_tmpdir> +* Type: Path +* DEPRECATED: This setting is no longer used. npm stores temporary files in a + special location in the cache, and they are managed by + [`cacache`](http://npm.im/cacache). + +Historically, the location where temporary files were stored. No longer +relevant. + +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END --> + ### See also * [npm config](/commands/npm-config) diff --git a/scripts/config-doc.js b/scripts/config-doc.js new file mode 100644 index 000000000..9bb462889 --- /dev/null +++ b/scripts/config-doc.js @@ -0,0 +1,50 @@ +const { shorthands, describeAll } = require('../lib/utils/config/index.js') +const { writeFileSync, readFileSync } = require('fs') +const { resolve } = require('path') +const configDoc = resolve(__dirname, '../docs/content/using-npm/config.md') + +const addBetweenTags = (doc, startTag, endTag, body) => { + const startSplit = doc.split(startTag) + if (startSplit.length !== 2) + throw new Error('Did not find exactly one start tag') + + const endSplit = startSplit[1].split(endTag) + if (endSplit.length !== 2) + throw new Error('Did not find exactly one end tag') + + return [ + startSplit[0], + startTag, + '\n<!-- automatically generated, do not edit manually -->\n', + body, + '\n\n', + endTag, + endSplit[1], + ].join('') +} + +const addDescriptions = doc => { + const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->' + const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->' + return addBetweenTags(doc, startTag, endTag, describeAll()) +} + +const addShorthands = doc => { + const startTag = '<!-- AUTOGENERATED CONFIG SHORTHANDS START -->' + const endTag = '<!-- AUTOGENERATED CONFIG SHORTHANDS END -->' + const body = Object.entries(shorthands) + .sort(([shorta, expansiona], [shortb, expansionb]) => { + // sort by what they're short FOR + return expansiona.join(' ').localeCompare(expansionb.join(' ')) || + shorta.localeCompare(shortb) + }) + .map(([short, expansion]) => { + const dash = short.length === 1 ? '-' : '--' + return `* \`${dash}${short}\`: \`${expansion.join(' ')}\`` + }).join('\n') + return addBetweenTags(doc, startTag, endTag, body) +} + +const doc = readFileSync(configDoc, 'utf8') +writeFileSync(configDoc, addDescriptions(addShorthands(doc))) +console.log(`updated docs/content/using-npm/config.md`) |