OSSForks/node
1
0
Fork 0
mirror of https://github.com/zebrajr/node.git synced 2025-12-06 00:20:08 +01:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

deps: upgrade npm to 11.6.2

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/60168
Reviewed-By: Jordan Harband <ljharb@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
npm CLI robot 2025-10-11 14:22:44 -07:00 committed by GitHub
parent aef3fc37eb
commit 1b22f6049a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
370 changed files with 8501 additions and 11075 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
deps/npm/README.md vendored
View File

@ -36,13 +36,12 @@ npm <command>
* [**RFCs**](https://github.com/npm/rfcs) - Contribute ideas & specifications for the API/design of the npm CLI
* [**Service Status**](https://status.npmjs.org/) - Monitor the current status & see incident reports for the website & registry
* [**Project Status**](https://npm.github.io/statusboard/) - See the health of all our maintained OSS projects in one view
* [**Events Calendar**](https://calendar.google.com/calendar/u/0/embed?src=npmjs.com_oonluqt8oftrt0vmgrfbg6q6go@group.calendar.google.com) - Keep track of our Open RFC calls, releases, meetups, conferences & more
* [**Support**](https://www.npmjs.com/support) - Experiencing problems with the **npm** [website](https://npmjs.com) or [registry](https://registry.npmjs.org)? File a ticket [here](https://www.npmjs.com/support)
* [**Support**](https://www.npmjs.com/support) - Experiencing problems with the **npm** [website](https://npmjs.com) or [registry](https://registry.npmjs.org)? [File a ticket](https://www.npmjs.com/support)
### Acknowledgments
* `npm` is configured to use the **npm Public Registry** at [https://registry.npmjs.org](https://registry.npmjs.org) by default; Usage of this registry is subject to **Terms of Use** available at [https://npmjs.com/policies/terms](https://npmjs.com/policies/terms)
* You can configure `npm` to use any other compatible registry you prefer. You can read more about configuring third-party registries [here](https://docs.npmjs.com/cli/v7/using-npm/registry)
* You can configure `npm` to use any other compatible registry you prefer. You can read more about [configuring third-party registries](https://docs.npmjs.com/cli/v7/using-npm/registry)
### FAQ on Branding

57
deps/npm/docs/content/commands/npm-access.md vendored
View File

@ -22,56 +22,28 @@ Note: This command is unaware of workspaces.
Used to set access controls on private packages.
For all of the subcommands, `npm access` will perform actions on the packages
in the current working directory if no package name is passed to the
subcommand.
For all of the subcommands, `npm access` will perform actions on the packages in the current working directory if no package name is passed to the subcommand.
* public / restricted (deprecated):
Set a package to be either publicly accessible or restricted.
* grant / revoke (deprecated):
Add or remove the ability of users and teams to have read-only or read-write
access to a package.
* 2fa-required / 2fa-not-required (deprecated):
Configure whether a package requires that anyone publishing it have two-factor
authentication enabled on their account.
* ls-packages (deprecated):
Show all of the packages a user or a team is able to access, along with the
access level, except for read-only public packages (it won't print the whole
registry listing)
* ls-collaborators (deprecated):
Show all of the access privileges for a package. Will only show permissions
for packages to which you have at least read access. If `<user>` is passed in,
the list is filtered only to teams _that_ user happens to belong to.
* edit (not implemented)
* grant / revoke:
Add or remove the ability of users and teams to have read-only or read-write access to a package.
### Details
`npm access` always operates directly on the current registry, configurable
from the command line using `--registry=<registry url>`.
`npm access` always operates directly on the current registry, configurable from the command line using `--registry=<registry url>`.
Unscoped packages are *always public*.
Scoped packages *default to restricted*, but you can either publish them as
public using `npm publish --access=public`, or set their access as public using
`npm access public` after the initial publish.
Scoped packages *default to restricted*, but you can either publish them as public using `npm publish --access=public`, or set their access as public using `npm access set status=public` after the initial publish.
You must have privileges to set the access of a package:
* You are an owner of an unscoped or scoped package.
* You are a member of the team that owns a scope.
* You have been given read-write privileges for a package, either as a member
of a team or directly as an owner.
* You have been given read-write privileges for a package, either as a member of a team or directly as an owner.
If you have two-factor authentication enabled then you'll be prompted to provide a second factor, or may use the `--otp=...` option to specify it on
the command line.
If you have two-factor authentication enabled then you'll be prompted to provide a second factor, or may use the `--otp=...` option to specify it on the command line.
If your account is not paid, then attempts to publish scoped packages will
fail with an HTTP 402 status code (logically enough), unless you use
If your account is not paid, then attempts to publish scoped packages will fail with an HTTP 402 status code (logically enough), unless you use
`--access=public`.
Management of teams and team memberships is done with the `npm team` command.
@ -85,8 +57,8 @@ Management of teams and team memberships is done with the `npm team` command.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -97,11 +69,12 @@ Not supported by all npm commands.
* 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`.
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.
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.

15
deps/npm/docs/content/commands/npm-adduser.md vendored
View File

@ -16,14 +16,13 @@ Note: This command is unaware of workspaces.
### Description
Create a new user in the specified registry, and save the credentials to
the `.npmrc` file. If no registry is specified, the default registry
will be used (see [`registry`](/using-npm/registry)).
Create a new user in the specified registry, and save the credentials to the `.npmrc` file.
If no registry is specified, the default registry will be used (see [`registry`](/using-npm/registry)).
When you run `npm adduser`, the CLI automatically generates a legacy token of `publish` type. For more information, see [About legacy tokens](/about-access-tokens#about-legacy-tokens).
When you run `npm adduser`, the CLI automatically generates a legacy token of `publish` type.
For more information, see [About legacy tokens](/about-access-tokens#about-legacy-tokens).
When using `legacy` for your `auth-type`, the username, password, and
email are read in from prompts.
When using `legacy` for your `auth-type`, the username, password, and email are read in from prompts.
### Configuration
@ -72,8 +71,8 @@ npm init --scope=@foo --yes
* Default: "web"
* Type: "legacy" or "web"
What authentication strategy to use with `login`. Note that if an `otp`
config is given, this value will always be set to `legacy`.
What authentication strategy to use with `login`. Note that if an
`otp` config is given, this value will always be set to `legacy`.

267
deps/npm/docs/content/commands/npm-audit.md vendored
View File

@ -12,32 +12,23 @@ npm audit [fix|signatures]
### Description
The audit command submits a description of the dependencies configured in
your project to your default registry and asks for a report of known
vulnerabilities. If any vulnerabilities are found, then the impact and
appropriate remediation will be calculated. If the `fix` argument is
provided, then remediations will be applied to the package tree.
The audit command submits a description of the dependencies configured in your project to your default registry and asks for a report of known vulnerabilities.
If any vulnerabilities are found, then the impact and appropriate remediation will be calculated.
If the `fix` argument is provided, then remediations will be applied to the package tree.
The command will exit with a 0 exit code if no vulnerabilities were found.
Note that some vulnerabilities cannot be fixed automatically and will
require manual intervention or review. Also note that since `npm audit
fix` runs a full-fledged `npm install` under the hood, all configs that
apply to the installer will also apply to `npm install` -- so things like
`npm audit fix --package-lock-only` will work as expected.
Note that some vulnerabilities cannot be fixed automatically and will require manual intervention or review.
Also note that since `npm audit fix` runs a full-fledged `npm install` under the hood, all configs that apply to the installer will also apply to `npm install` -- so things like `npm audit fix --package-lock-only` will work as expected.
By default, the audit command will exit with a non-zero code if any
vulnerability is found. It may be useful in CI environments to include the
`--audit-level` parameter to specify the minimum vulnerability level that
will cause the command to fail. This option does not filter the report
output, it simply changes the command's failure threshold.
By default, the audit command will exit with a non-zero code if any vulnerability is found.
It may be useful in CI environments to include the `--audit-level` parameter to specify the minimum vulnerability level that will cause the command to fail.
This option does not filter the report output, it simply changes the command's failure threshold.
### Package lock
By default npm requires a package-lock or shrinkwrap in order to run the
audit. You can bypass the package lock with `--no-package-lock` but be
aware the results may be different with every run, since npm will
re-build the dependency tree each time.
By default npm requires a package-lock or shrinkwrap in order to run the audit.
You can bypass the package lock with `--no-package-lock` but be aware the results may be different with every run, since npm will re-build the dependency tree each time.
### Audit Signatures
@ -49,12 +40,9 @@ Registry signatures can be verified using the following `audit` command:
$ npm audit signatures
```
The `audit signatures` command will also verify the provenance attestations of
downloaded packages. Because provenance attestations are such a new feature,
security features may be added to (or changed in) the attestation format over
time. To ensure that you're always able to verify attestation signatures check
that you're running the latest version of the npm CLI. Please note this often
means updating npm beyond the version that ships with Node.js.
The `audit signatures` command will also verify the provenance attestations of downloaded packages.
Because provenance attestations are such a new feature, security features may be added to (or changed in) the attestation format over time.
To ensure that you're always able to verify attestation signatures check that you're running the latest version of the npm CLI. Please note this often means updating npm beyond the version that ships with Node.js.
The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
@ -91,7 +79,7 @@ The `sig` is generated using the following template: `${package.name}@${package.
Keys response:
- `expires`: null or a simplified extended [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDTHH:mm:ss.sssZ`
- `keydid`: sha256 fingerprint of the public key
- `keyid`: sha256 fingerprint of the public key
- `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
- `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
- `key`: base64 encoded public key
@ -100,42 +88,29 @@ See this [example key's response from the public npm registry](https://registry.
### Audit Endpoints
There are two audit endpoints that npm may use to fetch vulnerability
information: the `Bulk Advisory` endpoint and the `Quick Audit` endpoint.
There are two audit endpoints that npm may use to fetch vulnerability information: the `Bulk Advisory` endpoint and the `Quick Audit` endpoint.
#### Bulk Advisory Endpoint
As of version 7, npm uses the much faster `Bulk Advisory` endpoint to
optimize the speed of calculating audit results.
As of version 7, npm uses the much faster `Bulk Advisory` endpoint to optimize the speed of calculating audit results.
npm will generate a JSON payload with the name and list of versions of each
package in the tree, and POST it to the default configured registry at
the path `/-/npm/v1/security/advisories/bulk`.
npm will generate a JSON payload with the name and list of versions of each package in the tree, and POST it to the default configured registry at the path `/-/npm/v1/security/advisories/bulk`.
Any packages in the tree that do not have a `version` field in their
package.json file will be ignored. If any `--omit` options are specified
(either via the [`--omit` config](/using-npm/config#omit), or one of the
shorthands such as `--production`, `--only=dev`, and so on), then packages will
be omitted from the submitted payload as appropriate.
Any packages in the tree that do not have a `version` field in their package.json file will be ignored.
If any `--omit` options are specified (either via the [`--omit` config](/using-npm/config#omit), or one of the shorthands such as `--production`, `--only=dev`, and so on), then packages will be omitted from the submitted payload as appropriate.
If the registry responds with an error, or with an invalid response, then
npm will attempt to load advisory data from the `Quick Audit` endpoint.
If the registry responds with an error, or with an invalid response, then npm will attempt to load advisory data from the `Quick Audit` endpoint.
The expected result will contain a set of advisory objects for each
dependency that matches the advisory range. Each advisory object contains
a `name`, `url`, `id`, `severity`, `vulnerable_versions`, and `title`.
The expected result will contain a set of advisory objects for each dependency that matches the advisory range.
Each advisory object contains a `name`, `url`, `id`, `severity`, `vulnerable_versions`, and `title`.
npm then uses these advisory objects to calculate vulnerabilities and
meta-vulnerabilities of the dependencies within the tree.
npm then uses these advisory objects to calculate vulnerabilities and meta-vulnerabilities of the dependencies within the tree.
#### Quick Audit Endpoint
If the `Bulk Advisory` endpoint returns an error, or invalid data, npm will
attempt to load advisory data from the `Quick Audit` endpoint, which is
considerably slower in most cases.
If the `Bulk Advisory` endpoint returns an error, or invalid data, npm will attempt to load advisory data from the `Quick Audit` endpoint, which is considerably slower in most cases.
The full package tree as found in `package-lock.json` is submitted, along
with the following pieces of additional metadata:
The full package tree as found in `package-lock.json` is submitted, along with the following pieces of additional metadata:
* `npm_version`
* `node_version`
@ -148,64 +123,41 @@ Omitted dependency types are skipped when generating the report.
#### Scrubbing
Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
packages from the submitted report if their name contained a `/` character,
so as to avoid leaking the names of potentially private packages or git
URLs.
Out of an abundance of caution, npm versions 5 and 6 would "scrub" any packages from the submitted report if their name contained a `/` character, so as to avoid leaking the names of potentially private packages or git URLs.
However, in practice, this resulted in audits often failing to properly
detect meta-vulnerabilities, because the tree would appear to be invalid
due to missing dependencies, and prevented the detection of vulnerabilities
in package trees that used git dependencies or private modules.
However, in practice, this resulted in audits often failing to properly detect meta-vulnerabilities, because the tree would appear to be invalid due to missing dependencies, and prevented the detection of vulnerabilities in package trees that used git dependencies or private modules.
This scrubbing has been removed from npm as of version 7.
#### Calculating Meta-Vulnerabilities and Remediations
npm uses the
[`@npmcli/metavuln-calculator`](http://npm.im/@npmcli/metavuln-calculator)
module to turn a set of security advisories into a set of "vulnerability"
objects. A "meta-vulnerability" is a dependency that is vulnerable by
virtue of dependence on vulnerable versions of a vulnerable package.
npm uses the [`@npmcli/metavuln-calculator`](http://npm.im/@npmcli/metavuln-calculator) module to turn a set of security advisories into a set of "vulnerability" objects.
A "meta-vulnerability" is a dependency that is vulnerable by virtue of dependence on vulnerable versions of a vulnerable package.
For example, if the package `foo` is vulnerable in the range `>=1.0.2
<2.0.0`, and the package `bar` depends on `foo@^1.1.0`, then that version
of `bar` can only be installed by installing a vulnerable version of `foo`.
For example, if the package `foo` is vulnerable in the range `>=1.0.2 <2.0.0`, and the package `bar` depends on `foo@^1.1.0`, then that version of `bar` can only be installed by installing a vulnerable version of `foo`.
In this case, `bar` is a "metavulnerability".
Once metavulnerabilities for a given package are calculated, they are
cached in the `~/.npm` folder and only re-evaluated if the advisory range
changes, or a new version of the package is published (in which case, the
new version is checked for metavulnerable status as well).
Once metavulnerabilities for a given package are calculated, they are cached in the `~/.npm` folder and only re-evaluated if the advisory range changes, or a new version of the package is published (in which case, the new version is checked for metavulnerable status as well).
If the chain of metavulnerabilities extends all the way to the root
project, and it cannot be updated without changing its dependency ranges,
then `npm audit fix` will require the `--force` option to apply the
remediation. If remediations do not require changes to the dependency
ranges, then all vulnerable packages will be updated to a version that does
not have an advisory or metavulnerability posted against it.
If the chain of metavulnerabilities extends all the way to the root project, and it cannot be updated without changing its dependency ranges, then `npm audit fix` will require the `--force` option to apply the remediation.
If remediations do not require changes to the dependency ranges, then all vulnerable packages will be updated to a version that does not have an advisory or metavulnerability posted against it.
### Exit Code
The `npm audit` command will exit with a 0 exit code if no vulnerabilities
were found. The `npm audit fix` command will exit with 0 exit code if no
vulnerabilities are found _or_ if the remediation is able to successfully
fix all vulnerabilities.
The `npm audit` command will exit with a 0 exit code if no vulnerabilities were found.
The `npm audit fix` command will exit with 0 exit code if no vulnerabilities are found _or_ if the remediation is able to successfully fix all vulnerabilities.
If vulnerabilities were found the exit code will depend on the
[`audit-level` config](/using-npm/config#audit-level).
If vulnerabilities were found the exit code will depend on the [`audit-level` config](/using-npm/config#audit-level).
### Examples
Scan your project for vulnerabilities and automatically install any compatible
updates to vulnerable dependencies:
Scan your project for vulnerabilities and automatically install any compatible updates to vulnerable dependencies:
```bash
$ npm audit fix
```
Run `audit fix` without modifying `node_modules`, but still updating the
pkglock:
Run `audit fix` without modifying `node_modules`, but still updating the pkglock:
```bash
$ npm audit fix --package-lock-only
@ -217,22 +169,19 @@ Skip updating `devDependencies`:
$ npm audit fix --only=prod
```
Have `audit fix` install SemVer-major updates to toplevel dependencies, not
just SemVer-compatible ones:
Have `audit fix` install SemVer-major updates to toplevel dependencies, not just SemVer-compatible ones:
```bash
$ npm audit fix --force
```
Do a dry run to get an idea of what `audit fix` will do, and _also_ output
install information in JSON format:
Do a dry run to get an idea of what `audit fix` will do, and _also_ output install information in JSON format:
```bash
$ npm audit fix --dry-run --json
```
Scan your project for vulnerabilities and just show the details, without
fixing anything:
Scan your project for vulnerabilities and just show the details, without fixing anything:
```bash
$ npm audit
@ -257,8 +206,8 @@ $ npm audit --audit-level=moderate
* 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.
The minimum level of vulnerability for `npm audit` to exit with a
non-zero exit code.
@ -267,13 +216,14 @@ exit code.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -288,14 +238,16 @@ 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 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.
* Allow conflicting peerDependencies to be installed in the root
project.
* Implicitly set `--yes` during `npm init`.
* Allow clobbering existing values in `npm pkg`
* Allow unpublishing of entire packages (not just a single version).
@ -312,8 +264,8 @@ recommended that you do not use this option!
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -324,14 +276,15 @@ Not supported by all npm commands.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
@ -340,15 +293,16 @@ For `list` this means the output will be based on the tree described by the
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -357,40 +311,45 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -401,10 +360,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -413,9 +372,9 @@ run any pre- or post-scripts.
* 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.
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:
@ -424,9 +383,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -438,13 +397,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -455,9 +415,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -466,9 +427,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

39
deps/npm/docs/content/commands/npm-bugs.md vendored
View File

@ -14,11 +14,8 @@ alias: issues
### Description
This command tries to guess at the likely location of a package's bug
tracker URL or the `mailto` URL of the support email, and then tries to
open it using the [`--browser` config](/using-npm/config#browser) param. If no
package name is provided, it will search for a `package.json` in the current
folder and use the `name` property.
This command tries to guess at the likely location of a package's bug tracker URL or the `mailto` URL of the support email, and then tries to open it using the [`--browser` config](/using-npm/config#browser) param.
If no package name is provided, it will search for a `package.json` in the current folder and use the `name` property.
### Configuration
@ -50,9 +47,9 @@ The base URL of the npm registry.
* 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.
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:
@ -61,9 +58,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -75,13 +72,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -92,9 +90,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.

24
deps/npm/docs/content/commands/npm-cache.md vendored
View File

@ -26,10 +26,12 @@ Also used to view info about entries in the `npm exec` (aka `npx`) cache folder.
#### `npm cache`
* add:
Add the specified packages to the local cache. This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly.
Add the specified packages to the local cache.
This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly.
* clean:
Delete a single entry or all entries out of the cache folder. Note that this is typically unnecessary, as npm's cache is self-healing and resistant to data corruption issues.
Delete a single entry or all entries out of the cache folder.
Note that this is typically unnecessary, as npm's cache is self-healing and resistant to data corruption issues.
* ls:
List given entries or all entries in the local cache.
@ -50,20 +52,26 @@ Also used to view info about entries in the `npm exec` (aka `npx`) cache folder.
### Details
npm stores cache data in an opaque directory within the configured `cache`, named `_cacache`. This directory is a [`cacache`](http://npm.im/cacache)-based content-addressable cache that stores all http request data as well as other package-related data. This directory is primarily accessed through `pacote`, the library responsible for all package fetching as of npm@5.
npm stores cache data in an opaque directory within the configured `cache`, named `_cacache`.
This directory is a [`cacache`](http://npm.im/cacache)-based content-addressable cache that stores all http request data as well as other package-related data.
This directory is primarily accessed through `pacote`, the library responsible for all package fetching as of npm@5.
All data that passes through the cache is fully verified for integrity on both insertion and extraction. Cache corruption will either trigger an error, or signal to `pacote` that the data must be refetched, which it will do automatically. For this reason, it should never be necessary to clear the cache for any reason other than reclaiming disk space, thus why `clean` now requires `--force` to run.
All data that passes through the cache is fully verified for integrity on both insertion and extraction.
Cache corruption will either trigger an error, or signal to `pacote` that the data must be refetched, which it will do automatically.
For this reason, it should never be necessary to clear the cache for any reason other than reclaiming disk space, thus why `clean` now requires `--force` to run.
There is currently no method exposed through npm to inspect or directly manage the contents of this cache. In order to access it, `cacache` must be used directly.
There is currently no method exposed through npm to inspect or directly manage the contents of this cache.
In order to access it, `cacache` must be used directly.
npm will not remove data by itself: the cache will grow as new packages are installed.
### A note about the cache's design
The npm cache is strictly a cache: it should not be relied upon as a persistent and reliable data store for package data. npm makes no guarantee that a previously-cached piece of data will be available later, and will automatically delete corrupted contents. The primary guarantee that the cache makes is that, if it does return data, that data will be exactly the data that was inserted.
The npm cache is strictly a cache: it should not be relied upon as a persistent and reliable data store for package data.
npm makes no guarantee that a previously-cached piece of data will be available later, and will automatically delete corrupted contents.
The primary guarantee that the cache makes is that, if it does return data, that data will be exactly the data that was inserted.
To run an offline verification of existing cache contents, use `npm cache
verify`.
To run an offline verification of existing cache contents, use `npm cache verify`.
### Configuration

177
deps/npm/docs/content/commands/npm-ci.md vendored
View File

@ -14,10 +14,7 @@ aliases: clean-install, ic, install-clean, isntall-clean
### Description
This command is similar to [`npm install`](/commands/npm-install), except
it's meant to be used in automated environments such as test platforms,
continuous integration, and deployment -- or any situation where you want
to make sure you're doing a clean install of your dependencies.
This command is similar to [`npm install`](/commands/npm-install), except it's meant to be used in automated environments such as test platforms, continuous integration, and deployment -- or any situation where you want to make sure you're doing a clean install of your dependencies.
The main differences between using `npm install` and `npm ci` are:
@ -25,18 +22,14 @@ The main differences between using `npm install` and `npm ci` are:
`npm-shrinkwrap.json`.
* If dependencies in the package lock do not match those in `package.json`,
`npm ci` will exit with an error, instead of updating the package lock.
* `npm ci` can only install entire projects at a time: individual
dependencies cannot be added with this command.
* If a `node_modules` is already present, it will be automatically removed
before `npm ci` begins its install.
* `npm ci` can only install entire projects at a time: individual dependencies cannot be added with this command.
* If a `node_modules` is already present, it will be automatically removed before `npm ci` begins its install.
* It will never write to `package.json` or any of the package-locks:
installs are essentially frozen.
NOTE: If you create your `package-lock.json` file by running `npm install`
with flags that can affect the shape of your dependency tree, such as
`--legacy-peer-deps` or `--install-links`, you _must_ provide the same
flags to `npm ci` or you are likely to encounter errors. An easy way to do
this is to run, for example,
NOTE: If you create your `package-lock.json` file by running `npm install` with flags that can affect the shape of your dependency tree, such as
`--legacy-peer-deps` or `--install-links`, you _must_ provide the same flags to `npm ci` or you are likely to encounter errors.
An easy way to do this is to run, for example,
`npm config set legacy-peer-deps=true --location=project` and commit the
`.npmrc` file to your repo.
@ -78,11 +71,12 @@ cache:
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -93,10 +87,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -107,15 +101,15 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -124,25 +118,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -152,33 +150,35 @@ the order in which omit/include are specified on the command-line.
* 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.
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.
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 an 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.
When such an 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.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -189,10 +189,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -201,10 +201,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -216,9 +216,9 @@ submitted.
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.
@ -228,8 +228,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -238,13 +238,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -253,9 +254,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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.
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:
@ -264,9 +265,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -278,13 +279,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -295,9 +297,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -306,9 +309,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

13
deps/npm/docs/content/commands/npm-completion.md vendored
View File

@ -16,24 +16,19 @@ Note: This command is unaware of workspaces.
Enables tab-completion in all npm commands.
The synopsis above
loads the completions into your current shell. Adding it to
your ~/.bashrc or ~/.zshrc will make the completions available
everywhere:
The synopsis above loads the completions into your current shell.
Adding it to your ~/.bashrc or ~/.zshrc will make the completions available everywhere:
```bash
npm completion >> ~/.bashrc
npm completion >> ~/.zshrc
```
You may of course also pipe the output of `npm completion` to a file
such as `/usr/local/etc/bash_completion.d/npm` or
You may of course also pipe the output of `npm completion` to a file such as `/usr/local/etc/bash_completion.d/npm` or
`/etc/bash_completion.d/npm` if you have a system that will read
that file for you.
When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the
environment, `npm completion` acts in "plumbing mode", and outputs
completions based on the arguments.
When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the environment, `npm completion` acts in "plumbing mode", and outputs completions based on the arguments.
### See Also

70
deps/npm/docs/content/commands/npm-config.md vendored
View File

@ -21,17 +21,13 @@ Note: This command is unaware of workspaces.
### Description
npm gets its config settings from the command line, environment
variables, `npmrc` files, and in some cases, the `package.json` file.
npm gets its config settings from the command line, environment variables, `npmrc` files, and in some cases, the `package.json` file.
See [npmrc](/configuring-npm/npmrc) for more information about the npmrc
files.
See [npmrc](/configuring-npm/npmrc) for more information about the npmrc files.
See [config](/using-npm/config) for a more thorough explanation of the
mechanisms involved, and a full list of config options available.
See [config](/using-npm/config) for a more thorough explanation of the mechanisms involved, and a full list of config options available.
The `npm config` command can be used to update and edit the contents
of the user and global npmrc files.
The `npm config` command can be used to update and edit the contents of the user and global npmrc files.
### Sub-commands
@ -44,13 +40,12 @@ npm config set key=value [key=value...]
npm set key=value [key=value...]
```
Sets each of the config keys to the value provided. Modifies the user configuration
file unless [`location`](/commands/npm-config#location) is passed.
Sets each of the config keys to the value provided.
Modifies the user configuration file unless [`location`](/commands/npm-config#location) is passed.
If value is omitted, the key will be removed from your config file entirely.
Note: for backwards compatibility, `npm config set key value` is supported
as an alias for `npm config set key=value`.
Note: for backwards compatibility, `npm config set key value` is supported as an alias for `npm config set key=value`.
#### get
@ -61,11 +56,9 @@ npm get [key ...]
Echo the config value(s) to stdout.
If multiple keys are provided, then the values will be prefixed with the
key names.
If multiple keys are provided, then the values will be prefixed with the key names.
If no keys are provided, then this command behaves the same as `npm config
list`.
If no keys are provided, then this command behaves the same as `npm config list`.
#### list
@ -73,8 +66,9 @@ list`.
npm config list
```
Show all the config settings. Use `-l` to also show defaults. Use `--json`
to show the settings in json format.
Show all the config settings.
Use `-l` to also show defaults.
Use `--json` to show the settings in json format.
#### delete
@ -90,8 +84,8 @@ Deletes the specified keys from all configuration files.
npm config edit
```
Opens the config file in an editor. Use the `--global` flag to edit the
global config.
Opens the config file in an editor.
Use the `--global` flag to edit the global config.
#### fix
@ -99,9 +93,9 @@ global config.
npm config fix
```
Attempts to repair invalid configuration items. Usually this means
attaching authentication config (i.e. `_auth`, `_authToken`) to the
configured `registry`.
Attempts to repair invalid configuration items.
Usually this means attaching authentication config (i.e.
`_auth`, `_authToken`) to the configured `registry`.
### Configuration
@ -112,8 +106,8 @@ configured `registry`.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -124,12 +118,13 @@ Not supported by all npm commands.
* 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.
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`
@ -147,18 +142,19 @@ The command to run for `npm edit` and `npm config edit`.
#### `location`
* Default: "user" unless `--global` is passed, which will also set this value
to "global"
* Default: "user" unless `--global` is passed, which will also set this
value to "global"
* Type: "global", "user", or "project"
When passed to `npm config` this refers to which config file to use.
When set to "global" mode, 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.
When set to "global" mode, 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`

180
deps/npm/docs/content/commands/npm-dedupe.md vendored
View File

@ -14,9 +14,7 @@ alias: ddp
### Description
Searches the local package tree and attempts to simplify the overall
structure by moving dependencies further up the tree, where they can
be more effectively shared by multiple dependent packages.
Searches the local package tree and attempts to simplify the overall structure by moving dependencies further up the tree, where they can be more effectively shared by multiple dependent packages.
For example, consider this dependency graph:
@ -37,9 +35,7 @@ a
`-- c@1.0.10
```
Because of the hierarchical nature of node's module lookup, b and d
will both get their dependency met by the single c package at the root
level of the tree.
Because of the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree.
In some cases, you may have a dependency graph like this:
@ -51,29 +47,21 @@ a
`-- c@1.9.9
```
During the installation process, the `c@1.0.3` dependency for `b` was
placed in the root of the tree. Though `d`'s dependency on `c@1.x` could
have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used,
because npm favors updates by default, even when doing so causes
duplication.
During the installation process, the `c@1.0.3` dependency for `b` was placed in the root of the tree.
Though `d`'s dependency on `c@1.x` could have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used, because npm favors updates by default, even when doing so causes duplication.
Running `npm dedupe` will cause npm to note the duplication and
re-evaluate, deleting the nested `c` module, because the one in the root is
sufficient.
Running `npm dedupe` will cause npm to note the duplication and re-evaluate, deleting the nested `c` module, because the one in the root is sufficient.
To prefer deduplication over novelty during the installation process, run
`npm install --prefer-dedupe` or `npm config set prefer-dedupe true`.
To prefer deduplication over novelty during the installation process, run `npm install --prefer-dedupe` or `npm config set prefer-dedupe true`.
Arguments are ignored. Dedupe always acts on the entire tree.
Arguments are ignored.
Dedupe always acts on the entire tree.
Note that this operation transforms the dependency tree, but will never
result in new modules being installed.
Note that this operation transforms the dependency tree, but will never result in new modules being installed.
Using `npm find-dupes` will run the command in `--dry-run` mode.
Note: `npm dedupe` will never update the semver values of direct
dependencies in your project `package.json`, if you want to update
values in `package.json` you can run: `npm update --save` instead.
Note: `npm dedupe` will never update the semver values of direct dependencies in your project `package.json`, if you want to update values in `package.json` you can run: `npm update --save` instead.
### Configuration
@ -83,11 +71,12 @@ values in `package.json` you can run: `npm update --save` instead.
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -98,10 +87,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -112,8 +101,8 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
@ -123,18 +112,19 @@ on deeper dependencies. Sets `--install-strategy=shallow`.
* 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.
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.
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 an 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.
When such an 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.
@ -143,15 +133,16 @@ this warning is treated as a failure.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -160,25 +151,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -189,10 +184,10 @@ the order in which omit/include are specified on the command-line.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -201,10 +196,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -216,9 +211,9 @@ submitted.
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.
@ -228,8 +223,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -238,13 +233,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -253,9 +249,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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.
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:
@ -264,9 +260,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -278,13 +274,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -295,9 +292,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -306,9 +304,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

41
deps/npm/docs/content/commands/npm-deprecate.md vendored
View File

@ -14,18 +14,16 @@ Note: This command is unaware of workspaces.
### Description
This command will update the npm registry entry for a package, providing a
deprecation warning to all who attempt to install it.
This command will update the npm registry entry for a package, providing a deprecation warning to all who attempt to install it.
It works on [version ranges](https://semver.npmjs.com/) as well as specific
versions, so you can do something like this:
It works on [version ranges](https://semver.npmjs.com/) as well as specific versions, so you can do something like this:
```bash
npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"
```
SemVer ranges passed to this command are interpreted such that they *do*
include prerelease versions. For example:
SemVer ranges passed to this command are interpreted such that they *do* include prerelease versions.
For example:
```bash
npm deprecate my-thing@1.x "1.x is no longer supported"
@ -33,12 +31,11 @@ npm deprecate my-thing@1.x "1.x is no longer supported"
In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated.
You must be the package owner to deprecate something. See the `owner` and
`adduser` help topics.
You must be the package owner to deprecate something.
See the `owner` and `adduser` help topics.
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.
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
@ -56,11 +53,12 @@ The base URL of the npm registry.
* 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`.
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.
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.
@ -69,13 +67,14 @@ password, npm will prompt on the command line for one.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.

138
deps/npm/docs/content/commands/npm-diff.md vendored
View File

@ -12,22 +12,16 @@ npm diff [...<paths>]
### Description
Similar to its `git diff` counterpart, this command will print diff patches
of files for packages published to the npm registry.
Similar to its `git diff` counterpart, this command will print diff patches of files for packages published to the npm registry.
* `npm diff --diff=<spec-a> --diff=<spec-b>`
Compares two package versions using their registry specifiers, e.g:
`npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`. It's also possible to
compare across forks of any package,
e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`.
Compares two package versions using their registry specifiers, e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`.
It's also possible to compare across forks of any package, e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`.
Any valid spec can be used, so that it's also possible to compare
directories or git repositories,
e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg`
Any valid spec can be used, so that it's also possible to compare directories or git repositories, e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg`
Here's an example comparing two different versions of a package named
`abbrev` from the registry:
Here's an example comparing two different versions of a package named `abbrev` from the registry:
```bash
npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1
@ -50,39 +44,24 @@ of files for packages published to the npm registry.
"main": "abbrev.js",
```
Given the flexible nature of npm specs, you can also target local
directories or git repos just like when using `npm install`:
Given the flexible nature of npm specs, you can also target local directories or git repos just like when using `npm install`:
```bash
npm diff --diff=https://github.com/npm/libnpmdiff --diff=./local-path
```
In the example above we can compare the contents from the package installed
from the git repo at `github.com/npm/libnpmdiff` with the contents of the
`./local-path` that contains a valid package, such as a modified copy of
the original.
In the example above we can compare the contents from the package installed from the git repo at `github.com/npm/libnpmdiff` with the contents of the `./local-path` that contains a valid package, such as a modified copy of the original.
* `npm diff` (in a package directory, no arguments):
If the package is published to the registry, `npm diff` will fetch the
tarball version tagged as `latest` (this value can be configured using the
`tag` option) and proceed to compare the contents of files present in that
tarball, with the current files in your local file system.
If the package is published to the registry, `npm diff` will fetch the tarball version tagged as `latest` (this value can be configured using the `tag` option) and proceed to compare the contents of files present in that tarball, with the current files in your local file system.
This workflow provides a handy way for package authors to see what
package-tracked files have been changed in comparison with the latest
published version of that package.
This workflow provides a handy way for package authors to see what package-tracked files have been changed in comparison with the latest published version of that package.
* `npm diff --diff=<pkg-name>` (in a package directory):
When using a single package name (with no version or tag specifier) as an
argument, `npm diff` will work in a similar way to
[`npm-outdated`](npm-outdated) and reach for the registry to figure out
what current published version of the package named `<pkg-name>`
will satisfy its dependent declared semver-range. Once that specific
version is known `npm diff` will print diff patches comparing the
current version of `<pkg-name>` found in the local file system with
that specific version returned by the registry.
When using a single package name (with no version or tag specifier) as an argument, `npm diff` will work in a similar way to [`npm-outdated`](npm-outdated) and reach for the registry to figure out what current published version of the package named `<pkg-name>` will satisfy its dependent declared semver-range.
Once that specific version is known `npm diff` will print diff patches comparing the current version of `<pkg-name>` found in the local file system with that specific version returned by the registry.
Given a package named `abbrev` that is currently installed:
@ -90,19 +69,13 @@ of files for packages published to the npm registry.
npm diff --diff=abbrev
```
That will request from the registry its most up to date version and
will print a diff output comparing the currently installed version to this
newer one if the version numbers are not the same.
That will request from the registry its most up to date version and will print a diff output comparing the currently installed version to this newer one if the version numbers are not the same.
* `npm diff --diff=<spec-a>` (in a package directory):
Similar to using only a single package name, it's also possible to declare
a full registry specifier version if you wish to compare the local version
of an installed package with the specific version/tag/semver-range provided
in `<spec-a>`.
Similar to using only a single package name, it's also possible to declare a full registry specifier version if you wish to compare the local version of an installed package with the specific version/tag/semver-range provided in `<spec-a>`.
An example: assuming `pkg@1.0.0` is installed in the current `node_modules`
folder, running:
An example: assuming `pkg@1.0.0` is installed in the current `node_modules` folder, running:
```bash
npm diff --diff=pkg@2.0.0
@ -113,39 +86,29 @@ of files for packages published to the npm registry.
* `npm diff --diff=<semver-a> [--diff=<semver-b>]` (in a package directory):
Using `npm diff` along with semver-valid version numbers is a shorthand
to compare different versions of the current package.
Using `npm diff` along with semver-valid version numbers is a shorthand to compare different versions of the current package.
It needs to be run from a package directory, such that for a package named
`pkg` running `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running
`npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`.
It needs to be run from a package directory, such that for a package named `pkg` running `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running `npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`.
If only a single argument `<version-a>` is provided, then the current local
file system is going to be compared against that version.
If only a single argument `<version-a>` is provided, then the current local file system is going to be compared against that version.
Here's an example comparing two specific versions (published to the
configured registry) of the current project directory:
Here's an example comparing two specific versions (published to the configured registry) of the current project directory:
```bash
npm diff --diff=1.0.0 --diff=1.1.0
```
Note that tag names are not valid `--diff` argument values, if you wish to
compare to a published tag, you must use the `pkg@tagname` syntax.
Note that tag names are not valid `--diff` argument values, if you wish to compare to a published tag, you must use the `pkg@tagname` syntax.
#### Filtering files
It's possible to also specify positional arguments using file names or globs
pattern matching in order to limit the result of diff patches to only a subset
of files for a given package, e.g:
It's possible to also specify positional arguments using file names or globs pattern matching in order to limit the result of diff patches to only a subset of files for a given package, e.g:
```bash
npm diff --diff=pkg@2 ./lib/ CHANGELOG.md
```
In the example above the diff output is only going to print contents of files
located within the folder `./lib/` and changed lines of code within the
`CHANGELOG.md` file.
In the example above the diff output is only going to print contents of files located within the folder `./lib/` and changed lines of code within the `CHANGELOG.md` file.
### Configuration
@ -229,12 +192,13 @@ Treat all files as text in `npm diff`.
* 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.
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`
@ -245,17 +209,17 @@ folder instead of the current working directory. See
* 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.
It is the tag added to the package@version specified in the `npm dist-tag
add` command, if no explicit tag is given.
It is the tag added to the package@version specified in the `npm
dist-tag add` 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.
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.
If used in the `npm publish` command, this is the tag that will be added to
the package submitted to the registry.
If used in the `npm publish` command, this is the tag that will be
added to the package submitted to the registry.
@ -264,9 +228,9 @@ the package submitted to the registry.
* 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.
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:
@ -275,9 +239,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -289,13 +253,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -306,9 +271,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
## See Also

88
deps/npm/docs/content/commands/npm-dist-tag.md vendored
View File

@ -18,22 +18,16 @@ alias: dist-tags
Add, remove, and enumerate distribution tags on a package:
* add: Tags the specified version of the package with the specified tag,
or the [`--tag` config](/using-npm/config#tag) if not specified. If you have
two-factor authentication on auth-and-writes then you’ll need to include a
one-time password on the command line with
`--otp <one-time password>`, or go through a second factor flow based on your `authtype`.
* add: Tags the specified version of the package with the specified tag, or the [`--tag` config](/using-npm/config#tag) if not specified.
If you have two-factor authentication on auth-and-writes then you’ll need to include a one-time password on the command line with `--otp <one-time password>`, or go through a second factor flow based on your `authtype`.
* rm: Clear a tag that is no longer in use from the package. If you have
two-factor authentication on auth-and-writes then you’ll need to include
a one-time password on the command line with `--otp <one-time password>`,
or go through a second factor flow based on your `authtype`
* rm: Clear a tag that is no longer in use from the package.
If you have two-factor authentication on auth-and-writes then you’ll need to include a one-time password on the command line with `--otp <one-time password>`, or go through a second factor flow based on your `authtype`
* ls: Show all of the dist-tags for a package, defaulting to the package in
the current prefix. This is the default action if none is specified.
* ls: Show all of the dist-tags for a package, defaulting to the package in the current prefix.
This is the default action if none is specified.
A tag can be used when installing packages as a reference to a version instead
of using a specific version number:
A tag can be used when installing packages as a reference to a version instead of using a specific version number:
```bash
npm install <name>@<tag>
@ -45,28 +39,22 @@ When installing dependencies, a preferred tagged version may be specified:
npm install --tag <tag>
```
(This also applies to any other commands that resolve and install
dependencies, such as `npm dedupe`, `npm update`, and `npm audit fix`.)
(This also applies to any other commands that resolve and install dependencies, such as `npm dedupe`, `npm update`, and `npm audit fix`.)
Publishing a package sets the `latest` tag to the published version unless the
`--tag` option is used. For example, `npm publish --tag=beta`.
Publishing a package sets the `latest` tag to the published version unless the `--tag` option is used.
For example, `npm publish --tag=beta`.
By default, `npm install <pkg>` (without any `@<version>` or `@<tag>`
specifier) installs the `latest` tag.
By default, `npm install <pkg>` (without any `@<version>` or `@<tag>` specifier) installs the `latest` tag.
### Purpose
Tags can be used to provide an alias instead of version numbers.
For example, a project might choose to have multiple streams of development
and use a different tag for each stream, e.g., `stable`, `beta`, `dev`,
For example, a project might choose to have multiple streams of development and use a different tag for each stream, e.g., `stable`, `beta`, `dev`,
`canary`.
By default, the `latest` tag is used by npm to identify the current version
of a package, and `npm install <pkg>` (without any `@<version>` or `@<tag>`
specifier) installs the `latest` tag. Typically, projects only use the
`latest` tag for stable release versions, and use other tags for unstable
versions such as prereleases.
By default, the `latest` tag is used by npm to identify the current version of a package, and `npm install <pkg>` (without any `@<version>` or `@<tag>` specifier) installs the `latest` tag.
Typically, projects only use the `latest` tag for stable release versions, and use other tags for unstable versions such as prereleases.
The `next` tag is used by some projects to identify the upcoming version.
@ -74,19 +62,15 @@ Other than `latest`, no tag has any special significance to npm itself.
### Caveats
This command used to be known as `npm tag`, which only created new tags,
and so had a different syntax.
This command used to be known as `npm tag`, which only created new tags, and so had a different syntax.
Tags must share a namespace with version numbers, because they are
specified in the same slot: `npm install <pkg>@<version>` vs
`npm install <pkg>@<tag>`.
Tags must share a namespace with version numbers, because they are specified in the same slot: `npm install <pkg>@<version>` vs `npm install <pkg>@<tag>`.
Tags that can be interpreted as valid semver ranges will be rejected. For
example, `v1.4` cannot be used as a tag, because it is interpreted by
semver as `>=1.4.0 <1.5.0`. See <https://github.com/npm/npm/issues/6082>.
Tags that can be interpreted as valid semver ranges will be rejected.
For example, `v1.4` cannot be used as a tag, because it is interpreted by semver as `>=1.4.0 <1.5.0`.
See <https://github.com/npm/npm/issues/6082>.
The simplest way to avoid semver problems with tags is to use tags that do
not begin with a number or the letter `v`.
The simplest way to avoid semver problems with tags is to use tags that do not begin with a number or the letter `v`.
### Configuration
@ -95,9 +79,9 @@ not begin with a number or the letter `v`.
* 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.
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:
@ -106,9 +90,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -120,13 +104,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -137,9 +122,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.

40
deps/npm/docs/content/commands/npm-docs.md vendored
View File

@ -14,11 +14,9 @@ alias: home
### Description
This command tries to guess at the likely location of a package's
documentation URL, and then tries to open it using the
[`--browser` config](/using-npm/config#browser) param. You can pass multiple
package names at once. If no package name is provided, it will search for a
`package.json` in the current folder and use the `name` property.
This command tries to guess at the likely location of a package's documentation URL, and then tries to open it using the [`--browser` config](/using-npm/config#browser) param.
You can pass multiple package names at once.
If no package name is provided, it will search for a `package.json` in the current folder and use the `name` property.
### Configuration
@ -50,9 +48,9 @@ The base URL of the npm registry.
* 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.
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:
@ -61,9 +59,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -75,13 +73,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -92,9 +91,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.

91
deps/npm/docs/content/commands/npm-doctor.md vendored
View File

@ -14,96 +14,71 @@ Note: This command is unaware of workspaces.
### Description
`npm doctor` runs a set of checks to ensure that your npm installation has
what it needs to manage your JavaScript packages. npm is mostly a
standalone tool, but it does have some basic requirements that must be met:
`npm doctor` runs a set of checks to ensure that your npm installation has what it needs to manage your JavaScript packages.
npm is mostly a standalone tool, but it does have some basic requirements that must be met:
+ Node.js and git must be executable by npm.
+ The primary npm registry, `registry.npmjs.com`, or another service that
uses the registry API, is available.
+ The directories that npm uses, `node_modules` (both locally and
globally), exist and can be written by the current user.
+ The primary npm registry, `registry.npmjs.com`, or another service that uses the registry API, is available.
+ The directories that npm uses, `node_modules` (both locally and globally), exist and can be written by the current user.
+ The npm cache exists, and the package tarballs within it aren't corrupt.
Without all of these working properly, npm may not work properly. Many
issues are often attributable to things that are outside npm's code base,
so `npm doctor` confirms that the npm installation is in a good state.
Without all of these working properly, npm may not work properly.
Many issues are often attributable to things that are outside npm's code base, so `npm doctor` confirms that the npm installation is in a good state.
Also, in addition to this, there are also very many issue reports due to
using old versions of npm. Since npm is constantly improving, running
`npm@latest` is better than an old version.
Also, in addition to this, there are also very many issue reports due to using old versions of npm.
Since npm is constantly improving, running `npm@latest` is better than an old version.
`npm doctor` verifies the following items in your environment, and if
there are any recommended changes, it will display them. By default npm
runs all of these checks. You can limit what checks are ran by
specifying them as extra arguments.
`npm doctor` verifies the following items in your environment, and if there are any recommended changes, it will display them.
By default npm runs all of these checks.
You can limit what checks are ran by specifying them as extra arguments.
#### `Connecting to the registry`
By default, npm installs from the primary npm registry,
`registry.npmjs.org`. `npm doctor` hits a special connection testing
endpoint within the registry. This can also be checked with `npm ping`.
If this check fails, you may be using a proxy that needs to be
configured, or may need to talk to your IT staff to get access over
HTTPS to `registry.npmjs.org`.
`registry.npmjs.org`.
`npm doctor` hits a special connection testing endpoint within the registry.
This can also be checked with `npm ping`.
If this check fails, you may be using a proxy that needs to be configured, or may need to talk to your IT staff to get access over HTTPS to `registry.npmjs.org`.
This check is done against whichever registry you've configured (you can
see what that is by running `npm config get registry`), and if you're using
a private registry that doesn't support the `/whoami` endpoint supported by
the primary registry, this check may fail.
This check is done against whichever registry you've configured (you can see what that is by running `npm config get registry`), and if you're using a private registry that doesn't support the `/whoami` endpoint supported by the primary registry, this check may fail.
#### `Checking npm version`
While Node.js may come bundled with a particular version of npm, it's the
policy of the CLI team that we recommend all users run `npm@latest` if they
can. As the CLI is maintained by a small team of contributors, there are
only resources for a single line of development, so npm's own long-term
support releases typically only receive critical security and regression
fixes. The team believes that the latest tested version of npm is almost
always likely to be the most functional and defect-free version of npm.
While Node.js may come bundled with a particular version of npm, it's the policy of the CLI team that we recommend all users run `npm@latest` if they can.
As the CLI is maintained by a small team of contributors, there are only resources for a single line of development, so npm's own long-term support releases typically only receive critical security and regression fixes.
The team believes that the latest tested version of npm is almost always likely to be the most functional and defect-free version of npm.
#### `Checking node version`
For most users, in most circumstances, the best version of Node will be the
latest long-term support (LTS) release. Those of you who want access to new
ECMAscript features or bleeding-edge changes to Node's standard library may
be running a newer version, and some may be required to run an older
version of Node because of enterprise change control policies. That's OK!
For most users, in most circumstances, the best version of Node will be the latest long-term support (LTS) release.
Those of you who want access to new ECMAscript features or bleeding-edge changes to Node's standard library may be running a newer version, and some may be required to run an older version of Node because of enterprise change control policies.
That's OK!
But in general, the npm team recommends that most users run Node.js LTS.
#### `Checking configured npm registry`
You may be installing from private package registries for your project or
company. That's great! Others may be following tutorials or StackOverflow
questions in an effort to troubleshoot problems you may be having.
Sometimes, this may entail changing the registry you're pointing at. This
part of `npm doctor` just lets you, and maybe whoever's helping you with
support, know that you're not using the default registry.
You may be installing from private package registries for your project or company.
That's great! Others may be following tutorials or StackOverflow questions in an effort to troubleshoot problems you may be having.
Sometimes, this may entail changing the registry you're pointing at.
This part of `npm doctor` just lets you, and maybe whoever's helping you with support, know that you're not using the default registry.
#### `Checking for git executable in PATH`
While it's documented in the README, it may not be obvious that npm needs
Git installed to do many of the things that it does. Also, in some cases
– especially on Windows – you may have Git set up in such a way that it's
not accessible via your `PATH` so that npm can find it. This check ensures
that Git is available.
While it's documented in the README, it may not be obvious that npm needs Git installed to do many of the things that it does.
Also, in some cases – especially on Windows – you may have Git set up in such a way that it's not accessible via your `PATH` so that npm can find it.
This check ensures that Git is available.
#### Permissions checks
* Your cache must be readable and writable by the user running npm.
* Global package binaries must be writable by the user running npm.
* Your local `node_modules` path, if you're running `npm doctor` with a
project directory, must be readable and writable by the user running npm.
* Your local `node_modules` path, if you're running `npm doctor` with a project directory, must be readable and writable by the user running npm.
#### Validate the checksums of cached packages
When an npm package is published, the publishing process generates a
checksum that npm uses at install time to verify that the package didn't
get corrupted in transit. `npm doctor` uses these checksums to validate the
package tarballs in your local cache (you can see where that cache is
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.
When an npm package is published, the publishing process generates a checksum that npm uses at install time to verify that the package didn't get corrupted in transit.
`npm doctor` uses these checksums to validate the package tarballs in your local cache (you can see where that cache is 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

11
deps/npm/docs/content/commands/npm-edit.md vendored
View File

@ -14,16 +14,11 @@ Note: This command is unaware of workspaces.
### Description
Selects a dependency in the current project and opens the package folder in
the default editor (or whatever you've configured as the npm `editor`
config -- see [`npm-config`](npm-config).)
Selects a dependency in the current project and opens the package folder in the default editor (or whatever you've configured as the npm `editor` config -- see [`npm-config`](npm-config).)
After it has been edited, the package is rebuilt so as to pick up any
changes in compiled packages.
After it has been edited, the package is rebuilt so as to pick up any changes in compiled packages.
For instance, you can do `npm install connect` to install connect
into your package, and then `npm edit connect` to make a few
changes to your locally installed copy.
For instance, you can do `npm install connect` to install connect into your package, and then `npm edit connect` to make a few changes to your locally installed copy.
### Configuration

208
deps/npm/docs/content/commands/npm-exec.md vendored
View File

@ -17,58 +17,34 @@ alias: x
### Description
This command allows you to run an arbitrary command from an npm package
(either one installed locally, or fetched remotely), in a similar context
as running it via `npm run`.
This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via `npm run`.
Run without positional arguments or `--call`, this allows you to
interactively run commands in the same sort of shell environment that
`package.json` scripts are run. Interactive mode is not supported in CI
environments when standard input is a TTY, to prevent hangs.
Run without positional arguments or `--call`, this allows you to interactively run commands in the same sort of shell environment that `package.json` scripts are run.
Interactive mode is not supported in CI environments when standard input is a TTY, to prevent hangs.
Whatever packages are specified by the `--package` option will be
provided in the `PATH` of the executed command, along with any locally
installed package executables. The `--package` option may be
specified multiple times, to execute the supplied command in an environment
where all specified packages are available.
Whatever packages are specified by the `--package` option will be provided in the `PATH` of the executed command, along with any locally installed package executables.
The `--package` option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.
If any requested packages are not present in the local project
dependencies, then a prompt is printed, which can be suppressed by
providing either `--yes` or `--no`. When standard input is not a TTY or a
CI environment is detected, `--yes` is assumed. The requested packages are
installed to a folder in the npm cache, which is added to the `PATH`
environment variable in the executed process.
If any requested packages are not present in the local project dependencies, then a prompt is printed, which can be suppressed by providing either `--yes` or `--no`.
When standard input is not a TTY or a CI environment is detected, `--yes` is assumed.
The requested packages are installed to a folder in the npm cache, which is added to the `PATH` environment variable in the executed process.
Package names provided without a specifier will be matched with whatever
version exists in the local project. Package names with a specifier will
only be considered a match if they have the exact same name and version as
the local dependency.
Package names provided without a specifier will be matched with whatever version exists in the local project.
Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.
If no `-c` or `--call` option is provided, then the positional arguments
are used to generate the command string. If no `--package` options
are provided, then npm will attempt to determine the executable name from
the package specifier provided as the first positional argument according
to the following heuristic:
If no `-c` or `--call` option is provided, then the positional arguments are used to generate the command string.
If no `--package` options are provided, then npm will attempt to determine the executable name from the package specifier provided as the first positional argument according to the following heuristic:
- If the package has a single entry in its `bin` field in `package.json`,
or if all entries are aliases of the same command, then that command
will be used.
- If the package has multiple `bin` entries, and one of them matches the
unscoped portion of the `name` field, then that command will be used.
- If this does not result in exactly one option (either because there are
no bin entries, or none of them match the `name` of the package), then
`npm exec` exits with an error.
- If the package has a single entry in its `bin` field in `package.json`, or if all entries are aliases of the same command, then that command will be used.
- If the package has multiple `bin` entries, and one of them matches the unscoped portion of the `name` field, then that command will be used.
- If this does not result in exactly one option (either because there are no bin entries, or none of them match the `name` of the package), then `npm exec` exits with an error.
To run a binary _other than_ the named binary, specify one or more
`--package` options, which will prevent npm from inferring the package from
the first command argument.
To run a binary _other than_ the named binary, specify one or more `--package` options, which will prevent npm from inferring the package from the first command argument.
### `npx` vs `npm exec`
When run via the `npx` binary, all flags and options *must* be set prior to
any positional arguments. When run via `npm exec`, a double-hyphen `--`
flag can be used to suppress npm's parsing of switches and options that
should be sent to the executed command.
When run via the `npx` binary, all flags and options *must* be set prior to any positional arguments.
When run via `npm exec`, a double-hyphen `--` flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command.
For example:
@ -76,34 +52,29 @@ For example:
$ npx foo@latest bar --package=@npmcli/foo
```
In this case, npm will resolve the `foo` package name, and run the
following command:
In this case, npm will resolve the `foo` package name, and run the following command:
```
$ foo bar --package=@npmcli/foo
```
Since the `--package` option comes _after_ the positional arguments, it is
treated as an argument to the executed command.
Since the `--package` option comes _after_ the positional arguments, it is treated as an argument to the executed command.
In contrast, due to npm's argument parsing logic, running this command is
different:
In contrast, due to npm's argument parsing logic, running this command is different:
```
$ npm exec foo@latest bar --package=@npmcli/foo
```
In this case, npm will parse the `--package` option first, resolving the
`@npmcli/foo` package. Then, it will execute the following command in that
context:
In this case, npm will parse the `--package` option first, resolving the `@npmcli/foo` package.
Then, it will execute the following command in that context:
```
$ foo@latest bar
```
The double-hyphen character is recommended to explicitly tell npm to stop
parsing command line options and switches. The following command would
thus be equivalent to the `npx` command above:
The double-hyphen character is recommended to explicitly tell npm to stop parsing command line options and switches.
The following command would thus be equivalent to the `npx` command above:
```
$ npm exec -- foo@latest bar --package=@npmcli/foo
@ -116,7 +87,8 @@ $ npm exec -- foo@latest bar --package=@npmcli/foo
* Default:
* Type: String (can be set multiple times)
The package or packages to install for [`npm exec`](/commands/npm-exec)
The package or packages to install for [`npm
exec`](/commands/npm-exec)
@ -125,8 +97,9 @@ The package or packages to install for [`npm exec`](/commands/npm-exec)
* 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.
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"
@ -139,9 +112,9 @@ npm exec --package yo --package generator-node --call "yo node"
* 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.
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:
@ -150,9 +123,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -164,13 +137,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -181,24 +155,23 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
### Examples
Run the version of `tap` in the local dependencies, with the provided
arguments:
Run the version of `tap` in the local dependencies, with the provided arguments:
```
$ npm exec -- tap --bail test/foo.js
$ npx tap --bail test/foo.js
```
Run a command _other than_ the command whose name matches the package name
by specifying a `--package` option:
Run a command _other than_ the command whose name matches the package name by specifying a `--package` option:
```
$ npm exec --package=foo -- bar --bar-argument
@ -215,13 +188,8 @@ $ npx -c 'eslint && say "hooray, lint passed"'
### Workspaces support
You may use the [`workspace`](/using-npm/config#workspace) or
[`workspaces`](/using-npm/config#workspaces) configs in order to run an
arbitrary command from an npm package (either one installed locally, or fetched
remotely) in the context of the specified workspaces.
If no positional argument or `--call` option is provided, it will open an
interactive subshell in the context of each of these configured workspaces one
at a time.
You may use the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) configs in order to run an arbitrary command from an npm package (either one installed locally, or fetched remotely) in the context of the specified workspaces.
If no positional argument or `--call` option is provided, it will open an interactive subshell in the context of each of these configured workspaces one at a time.
Given a project with configured workspaces, e.g:
@ -237,8 +205,8 @@ Given a project with configured workspaces, e.g:
`-- package.json
```
Assuming the workspace configuration is properly set up at the root level
`package.json` file. e.g:
Assuming the workspace configuration is properly set up at the root level `package.json` file.
e.g:
```
{
@ -246,10 +214,7 @@ Assuming the workspace configuration is properly set up at the root level
}
```
You can execute an arbitrary command from a package in the context of each of
the configured workspaces when using the
[`workspaces` config options](/using-npm/config#workspace), in this example
we're using **eslint** to lint any js file found within each workspace folder:
You can execute an arbitrary command from a package in the context of each of the configured workspaces when using the [`workspaces` config options](/using-npm/config#workspace), in this example we're using **eslint** to lint any js file found within each workspace folder:
```
npm exec --ws -- eslint ./*.js
@ -257,17 +222,14 @@ npm exec --ws -- eslint ./*.js
#### Filtering workspaces
It's also possible to execute a command in a single workspace using the
`workspace` config along with a name or directory path:
It's also possible to execute a command in a single workspace using the `workspace` config along with a name or directory path:
```
npm exec --workspace=a -- eslint ./*.js
```
The `workspace` config can also be specified multiple times in order to run a
specific script in the context of multiple workspaces. When defining values for
the `workspace` config in the command line, it also possible to use `-w` as a
shorthand, e.g:
The `workspace` config can also be specified multiple times in order to run a specific script in the context of multiple workspaces.
When defining values for the `workspace` config in the command line, it also possible to use `-w` as a shorthand, e.g:
```
npm exec -w a -w b -- eslint ./*.js
@ -278,69 +240,60 @@ This last command will run the `eslint` command in both `./packages/a` and
### Compatibility with Older npx Versions
The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx`
package deprecated at that time. `npx` uses the `npm exec`
command instead of a separate argument parser and install process, with
some affordances to maintain backwards compatibility with the arguments it
accepted in previous versions.
The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` package deprecated at that time.
`npx` uses the `npm exec` command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions.
This resulted in some shifts in its functionality:
- Any `npm` config value may be provided.
- To prevent security and user-experience problems from mistyping package
names, `npx` prompts before installing anything. Suppress this
prompt with the `-y` or `--yes` option.
names, `npx` prompts before installing anything.
Suppress this prompt with the `-y` or `--yes` option.
- The `--no-install` option is deprecated, and will be converted to `--no`.
- Shell fallback functionality is removed, as it is not advisable.
- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand
for `--package` in npx. This is maintained, but only for the `npx`
executable.
- The `--ignore-existing` option is removed. Locally installed bins are
always present in the executed process `PATH`.
- The `--npm` option is removed. `npx` will always use the `npm` it ships
with.
- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand for `--package` in npx.
This is maintained, but only for the `npx` executable.
- The `--ignore-existing` option is removed.
Locally installed bins are always present in the executed process `PATH`.
- The `--npm` option is removed.
`npx` will always use the `npm` it ships with.
- The `--node-arg` and `-n` options are removed.
- The `--always-spawn` option is redundant, and thus removed.
- The `--shell` option is replaced with `--script-shell`, but maintained
in the `npx` executable for backwards compatibility.
- The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility.
### A note on caching
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.
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.
#### prefer-online
Forces staleness checks for packages, making the cli look for updates
immediately even if the package is already in the cache.
Forces staleness checks for packages, making the cli look for updates immediately even if the package is already in the cache.
#### prefer-offline
Bypasses staleness checks for packages. Missing data will still be
requested from the server. To force full offline mode, use `offline`.
Bypasses staleness checks for packages.
Missing data will still be requested from the server.
To force full offline mode, use `offline`.
#### offline
Forces full offline mode. Any packages not locally cached will result in
an error.
Forces full offline mode.
Any packages not locally cached will result in an error.
#### 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.
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)
* 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.
@ -350,8 +303,7 @@ This value is not exported to the environment for child processes.
* Type: Boolean
* Default: `false`
Run scripts in the context of all configured workspaces for the current
project.
Run scripts in the context of all configured workspaces for the current project.
### See Also

28
deps/npm/docs/content/commands/npm-explain.md vendored
View File

@ -14,11 +14,9 @@ alias: why
### Description
This command will print the chain of dependencies causing a given package
to be installed in the current project.
This command will print the chain of dependencies causing a given package to be installed in the current project.
If one or more package specs are provided, then only packages matching
one of the specifiers will have their relationships explained.
If one or more package specs are provided, then only packages matching one of the specifiers will have their relationships explained.
The package spec can also refer to a folder within `./node_modules`
@ -38,10 +36,8 @@ node_modules/tacks/node_modules/glob
dev tacks@"^1.3.0" from the root project
```
To explain just the package residing at a specific folder, pass that as the
argument to the command. This can be useful when trying to figure out
exactly why a given dependency is being duplicated to satisfy conflicting
version requirements within the project.
To explain just the package residing at a specific folder, pass that as the argument to the command.
This can be useful when trying to figure out exactly why a given dependency is being duplicated to satisfy conflicting version requirements within the project.
```bash
$ npm explain node_modules/nyc/node_modules/find-up
@ -62,8 +58,8 @@ node_modules/nyc/node_modules/find-up
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -74,9 +70,9 @@ Not supported by all npm commands.
* 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.
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:
@ -85,9 +81,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.

13
deps/npm/docs/content/commands/npm-explore.md vendored
View File

@ -16,25 +16,22 @@ Note: This command is unaware of workspaces.
Spawn a subshell in the directory of the installed package specified.
If a command is specified, then it is run in the subshell, which then
immediately terminates.
If a command is specified, then it is run in the subshell, which then immediately terminates.
This is particularly handy in the case of git submodules in the
`node_modules` folder:
This is particularly handy in the case of git submodules in the `node_modules` folder:
```bash
npm explore some-dependency -- git pull origin master
```
Note that the package is *not* automatically rebuilt afterwards, so be
sure to use `npm rebuild <pkg>` if you make any changes.
Note that the package is *not* automatically rebuilt afterwards, so be sure to use `npm rebuild <pkg>` if you make any changes.
### Configuration
#### `shell`
* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe" on
Windows
* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe"
on Windows
* Type: String
The shell to run for the `npm explore` command.

138
deps/npm/docs/content/commands/npm-find-dupes.md vendored
View File

@ -12,8 +12,7 @@ npm find-dupes
### Description
Runs `npm dedupe` in `--dry-run` mode, making npm only output the
duplications, without actually changing the package tree.
Runs `npm dedupe` in `--dry-run` mode, making npm only output the duplications, without actually changing the package tree.
### Configuration
@ -23,11 +22,12 @@ duplications, without actually changing the package tree.
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -38,10 +38,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -52,8 +52,8 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
@ -63,18 +63,19 @@ on deeper dependencies. Sets `--install-strategy=shallow`.
* 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.
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.
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 an 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.
When such an 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.
@ -83,15 +84,16 @@ this warning is treated as a failure.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -100,25 +102,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -129,10 +135,10 @@ the order in which omit/include are specified on the command-line.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -141,10 +147,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -156,9 +162,9 @@ submitted.
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.
@ -168,8 +174,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -178,9 +184,9 @@ fund`](/commands/npm-fund) for details.
* 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.
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:
@ -189,9 +195,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -203,13 +209,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -220,9 +227,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -231,9 +239,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

53
deps/npm/docs/content/commands/npm-fund.md vendored
View File

@ -12,31 +12,23 @@ npm fund [<package-spec>]
### Description
This command retrieves information on how to fund the dependencies of a
given project. If no package name is provided, it will list all
dependencies that are looking for funding in a tree structure, listing
the type of funding and the url to visit. If a package name is provided
then it tries to open its funding url using the
[`--browser` config](/using-npm/config#browser) param; if there are multiple
funding sources for the package, the user will be instructed to pass the
This command retrieves information on how to fund the dependencies of a given project.
If no package name is provided, it will list all dependencies that are looking for funding in a tree structure, listing the type of funding and the url to visit.
If a package name is provided then it tries to open its funding url using the [`--browser` config](/using-npm/config#browser) param; if there are multiple funding sources for the package, the user will be instructed to pass the
`--which` option to disambiguate.
The list will avoid duplicated entries and will stack all packages that
share the same url as a single entry. Thus, the list does not have the
same shape of the output from `npm ls`.
The list will avoid duplicated entries and will stack all packages that share the same url as a single entry.
Thus, the list does not have the same shape of the output from `npm ls`.
#### Example
### Workspaces support
It's possible to filter the results to only include a single workspace
and its dependencies using the
[`workspace` config](/using-npm/config#workspace) option.
It's possible to filter the results to only include a single workspace and its dependencies using the [`workspace` config](/using-npm/config#workspace) option.
#### Example:
Here's an example running `npm fund` in a project with a configured
workspace `a`:
Here's an example running `npm fund` in a project with a configured workspace `a`:
```bash
$ npm fund
@ -51,8 +43,7 @@ test-workspaces-fund@1.0.0
`-- bar@2.0.0
```
And here is an example of the expected result when filtering only by a
specific workspace `a` in the same project:
And here is an example of the expected result when filtering only by a specific workspace `a` in the same project:
```bash
$ npm fund -w a
@ -72,8 +63,8 @@ test-workspaces-fund@1.0.0
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -95,12 +86,13 @@ Set to `true` to use default system URL opener.
#### `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.
* 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 instead of unicode glyphs.
When set to true, npm uses unicode characters in the tree output.
When false, it uses ascii characters instead of unicode glyphs.
@ -109,9 +101,9 @@ false, it uses ascii characters instead of unicode glyphs.
* 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.
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:
@ -120,9 +112,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -131,7 +123,8 @@ This value is not exported to the environment for child processes.
* Default: null
* Type: null or Number
If there are multiple funding sources, which 1-indexed source URL to open.
If there are multiple funding sources, which 1-indexed source URL to
open.

8
deps/npm/docs/content/commands/npm-help-search.md vendored
View File

@ -14,14 +14,12 @@ Note: This command is unaware of workspaces.
### Description
This command will search the npm markdown documentation files for the terms
provided, and then list the results, sorted by relevance.
This command will search the npm markdown documentation files for the terms provided, and then list the results, sorted by relevance.
If only one result is found, then it will show that help topic.
If the argument to `npm help` is not a known help topic, then it will call
`help-search`. It is rarely if ever necessary to call this command
directly.
If the argument to `npm help` is not a known help topic, then it will call `help-search`.
It is rarely if ever necessary to call this command directly.
### Configuration

9
deps/npm/docs/content/commands/npm-help.md vendored
View File

@ -18,10 +18,8 @@ Note: This command is unaware of workspaces.
If supplied a topic, then show the appropriate documentation page.
If the topic does not exist, or if multiple terms are provided, then npm
will run the `help-search` command to find a match. Note that, if
`help-search` finds a single subject, then it will run `help` on that
topic, so unique matches are equivalent to specifying a topic name.
If the topic does not exist, or if multiple terms are provided, then npm will run the `help-search` command to find a match.
Note that, if `help-search` finds a single subject, then it will run `help` on that topic, so unique matches are equivalent to specifying a topic name.
### Configuration
@ -32,7 +30,8 @@ topic, so unique matches are equivalent to specifying a topic name.
The program to use to view help content.
Set to `"browser"` to view html help content in the default web browser.
Set to `"browser"` to view html help content in the default web
browser.

142
deps/npm/docs/content/commands/npm-init.md vendored
View File

@ -15,16 +15,12 @@ aliases: create, innit
### Description
`npm init <initializer>` can be used to set up a new or existing npm
package.
`npm init <initializer>` can be used to set up a new or existing npm package.
`initializer` in this case is an npm package named `create-<initializer>`,
which will be installed by [`npm-exec`](/commands/npm-exec), and then have its
main bin executed -- presumably creating or updating `package.json` and
running any other initialization-related operations.
which will be installed by [`npm-exec`](/commands/npm-exec), and then have its main bin executed -- presumably creating or updating `package.json` and running any other initialization-related operations.
The init command is transformed to a corresponding `npm exec` operation as
follows:
The init command is transformed to a corresponding `npm exec` operation as follows:
* `npm init foo` -> `npm exec create-foo`
* `npm init @usr/foo` -> `npm exec @usr/create-foo`
@ -32,46 +28,37 @@ follows:
* `npm init @usr@2.0.0` -> `npm exec @usr/create@2.0.0`
* `npm init @usr/foo@2.0.0` -> `npm exec @usr/create-foo@2.0.0`
If the initializer is omitted (by just calling `npm init`), init will fall
back to legacy init behavior. It will ask you a bunch of questions, and
then write a package.json for you. It will attempt to make reasonable
guesses based on existing fields, dependencies, and options selected. It is
strictly additive, so it will keep any fields and values that were already
set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If
you pass `--scope`, it will create a scoped package.
If the initializer is omitted (by just calling `npm init`), init will fall back to legacy init behavior.
It will ask you a bunch of questions, and then write a package.json for you.
It will attempt to make reasonable guesses based on existing fields, dependencies, and options selected.
It is strictly additive, so it will keep any fields and values that were already set.
You can also use `-y`/`--yes` to skip the questionnaire altogether.
If you pass `--scope`, it will create a scoped package.
*Note:* if a user already has the `create-<initializer>` package
globally installed, that will be what `npm init` uses. If you want npm
to use the latest version, or another specific version you must specify
it:
*Note:* if a user already has the `create-<initializer>` package globally installed, that will be what `npm init` uses.
If you want npm to use the latest version, or another specific version you must specify it:
* `npm init foo@latest` # fetches and runs the latest `create-foo` from
the registry
* `npm init foo@latest` # fetches and runs the latest `create-foo` from the registry
* `npm init foo@1.2.3` # runs `create-foo@1.2.3` specifically
#### Forwarding additional options
Any additional options will be passed directly to the command, so `npm init
foo -- --hello` will map to `npm exec -- create-foo --hello`.
Any additional options will be passed directly to the command, so `npm init foo -- --hello` will map to `npm exec -- create-foo --hello`.
To better illustrate how options are forwarded, here's a more evolved
example showing options passed to both the **npm cli** and a create package,
both following commands are equivalent:
To better illustrate how options are forwarded, here's a more evolved example showing options passed to both the **npm cli** and a create package, both following commands are equivalent:
- `npm init foo -y --registry=<url> -- --hello -a`
- `npm exec -y --registry=<url> -- create-foo --hello -a`
### Examples
Create a new React-based project using
[`create-react-app`](https://npm.im/create-react-app):
Create a new React-based project using [`create-react-app`](https://npm.im/create-react-app):
```bash
$ npm init react-app ./my-react-app
```
Create a new `esm`-compatible package using
[`create-esm`](https://npm.im/create-esm):
Create a new `esm`-compatible package using [`create-esm`](https://npm.im/create-esm):
```bash
$ mkdir my-esm-lib && cd my-esm-lib
@ -99,11 +86,8 @@ $ npm init --init-private -y
### Workspaces support
It's possible to create a new workspace within your project by using the
`workspace` config option. When using `npm init -w <dir>` the cli will
create the folders and boilerplate expected while also adding a reference
to your project `package.json` `"workspaces": []` property in order to make
sure that new generated **workspace** is properly set up as such.
It's possible to create a new workspace within your project by using the `workspace` config option.
When using `npm init -w <dir>` the cli will create the folders and boilerplate expected while also adding a reference to your project `package.json` `"workspaces": []` property in order to make sure that new generated **workspace** is properly set up as such.
Given a project with no workspaces, e.g:
@ -118,8 +102,7 @@ You may generate a new workspace using the legacy init:
$ npm init -w packages/a
```
That will generate a new folder and `package.json` file, while also updating
your top-level `package.json` to add the reference to this new workspace:
That will generate a new folder and `package.json` file, while also updating your top-level `package.json` to add the reference to this new workspace:
```
.
@ -129,23 +112,15 @@ your top-level `package.json` to add the reference to this new workspace:
`-- package.json
```
The workspaces init also supports the `npm init <initializer> -w <dir>`
syntax, following the same set of rules explained earlier in the initial
**Description** section of this page. Similar to the previous example of
creating a new React-based project using
[`create-react-app`](https://npm.im/create-react-app), the following syntax
will make sure to create the new react app as a nested **workspace** within your
project and configure your `package.json` to recognize it as such:
The workspaces init also supports the `npm init <initializer> -w <dir>` syntax, following the same set of rules explained earlier in the initial
**Description** section of this page.
Similar to the previous example of creating a new React-based project using [`create-react-app`](https://npm.im/create-react-app), the following syntax will make sure to create the new react app as a nested **workspace** within your project and configure your `package.json` to recognize it as such:
```bash
npm init -w packages/my-react-app react-app .
```
This will make sure to generate your react app as expected, one important
consideration to have in mind is that `npm exec` is going to be run in the
context of the newly created folder for that workspace, and that's the reason
why in this example the initializer uses the initializer name followed with a
dot to represent the current directory in that context, e.g: `react-app .`:
This will make sure to generate your react app as expected, one important consideration to have in mind is that `npm exec` is going to be run in the context of the newly created folder for that workspace, and that's the reason why in this example the initializer uses the initializer name followed with a dot to represent the current directory in that context, e.g: `react-app .`:
```
.
@ -166,7 +141,8 @@ dot to represent the current directory in that context, e.g: `react-app .`:
* 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
name.
@ -196,8 +172,8 @@ The value `npm init` should use by default for the package license.
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-package-json](https://github.com/npm/init-package-json) module
for more information, or [npm init](/commands/npm-init).
@ -206,8 +182,8 @@ more information, or [npm init](/commands/npm-init).
* Default: "commonjs"
* Type: String
The value that `npm init` should use by default for the package.json type
field.
The value that `npm init` should use by default for the package.json
type field.
@ -216,8 +192,8 @@ field.
* Default: "1.0.0"
* 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.
@ -226,7 +202,8 @@ number, if not already set in package.json.
* Default: false
* Type: Boolean
The value `npm init` should use by default for the package's private flag.
The value `npm init` should use by default for the package's private
flag.
@ -251,14 +228,16 @@ 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 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.
* Allow conflicting peerDependencies to be installed in the root
project.
* Implicitly set `--yes` during `npm init`.
* Allow clobbering existing values in `npm pkg`
* Allow unpublishing of entire packages (not just a single version).
@ -304,9 +283,9 @@ npm init --scope=@foo --yes
* 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.
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:
@ -315,9 +294,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -329,13 +308,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -344,8 +324,9 @@ This value is not exported to the environment for child processes.
* Default: true
* Type: Boolean
If set to true, the npm cli will run an update after operations that may
possibly change the workspaces installed to the `node_modules` folder.
If set to true, the npm cli will run an update after operations that
may possibly change the workspaces installed to the `node_modules`
folder.
@ -356,9 +337,10 @@ possibly change the workspaces installed to the `node_modules` folder.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.

158
deps/npm/docs/content/commands/npm-install-ci-test.md vendored
View File

@ -24,11 +24,12 @@ This command runs `npm ci` followed immediately by `npm test`.
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -39,10 +40,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -53,15 +54,15 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -70,25 +71,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -98,33 +103,35 @@ the order in which omit/include are specified on the command-line.
* 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.
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.
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 an 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.
When such an 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.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -135,10 +142,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -147,10 +154,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -162,9 +169,9 @@ submitted.
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.
@ -174,8 +181,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -184,13 +191,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -199,9 +207,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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.
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:
@ -210,9 +218,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -224,13 +232,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -241,9 +250,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -252,9 +262,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

225
deps/npm/docs/content/commands/npm-install-test.md vendored
View File

@ -14,14 +14,15 @@ alias: it
### Description
This command runs an `npm install` followed immediately by an `npm test`. It
takes exactly the same arguments as `npm install`.
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` unless when using `npm update` where it defaults to `false`
* Default: `true` unless when using `npm update` where it defaults to
`false`
* Type: Boolean
Save installed packages to a `package.json` file as dependencies.
@ -38,8 +39,8 @@ Will also prevent writing to `package-lock.json` if set to `false`.
* 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.
Dependencies saved to package.json will be configured with an exact
version rather than using npm's default semver range operator.
@ -48,12 +49,13 @@ rather than using npm's default semver range operator.
* 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.
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`
@ -65,11 +67,12 @@ folder instead of the current working directory. See
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -80,10 +83,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -94,15 +97,15 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -111,25 +114,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -139,18 +146,19 @@ the order in which omit/include are specified on the command-line.
* 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.
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.
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 an 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.
When such an 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.
@ -159,8 +167,8 @@ this warning is treated as a failure.
* Default: false
* Type: Boolean
Prefer to deduplicate packages if possible, rather than choosing a newer
version of a dependency.
Prefer to deduplicate packages if possible, rather than choosing a
newer version of a dependency.
@ -169,8 +177,9 @@ version of a dependency.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
@ -179,29 +188,31 @@ will also prevent _writing_ `package-lock.json` if `save` is true.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -212,10 +223,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -224,10 +235,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -237,14 +248,14 @@ submitted.
* 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 given date are installed.
If there are no versions available for the current set of dependencies, the
command will error.
versions that were available **on or before** the given date are
installed. If there are no versions available for the current set of
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`.
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`.
@ -256,9 +267,9 @@ will be used. For example, `foo@latest` might install `foo@1.2` even though
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.
@ -268,8 +279,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -278,13 +289,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -293,8 +305,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* Default: null
* Type: null or String
Override CPU architecture of native modules to install. Acceptable values
are same as `cpu` field of package.json, which comes from `process.arch`.
Override CPU architecture of native modules to install. Acceptable
values are same as `cpu` field of package.json, which comes from
`process.arch`.
@ -303,8 +316,8 @@ are same as `cpu` field of package.json, which comes from `process.arch`.
* Default: null
* Type: null or String
Override OS of native modules to install. Acceptable values are same as `os`
field of package.json, which comes from `process.platform`.
Override OS of native modules to install. Acceptable values are same
as `os` field of package.json, which comes from `process.platform`.
@ -313,8 +326,8 @@ field of package.json, which comes from `process.platform`.
* Default: null
* Type: null or String
Override libc of native modules to install. Acceptable values are same as
`libc` field of package.json
Override libc of native modules to install. Acceptable values are
same as `libc` field of package.json
@ -323,9 +336,9 @@ Override libc of native modules to install. Acceptable values are same as
* 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.
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:
@ -334,9 +347,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -348,13 +361,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -365,9 +379,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -376,9 +391,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

471
deps/npm/docs/content/commands/npm-install.md vendored
View File

@ -14,64 +14,45 @@ aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall
### Description
This command installs a package and any packages that it depends on. If the
package has a package-lock, or an npm shrinkwrap file, or a yarn lock file,
the installation of dependencies will be driven by that, respecting the
following order of precedence:
This command installs a package and any packages that it depends on.
If the package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, the installation of dependencies will be driven by that, respecting the following order of precedence:
* `npm-shrinkwrap.json`
* `package-lock.json`
* `yarn.lock`
See [package-lock.json](/configuring-npm/package-lock-json) and
[`npm shrinkwrap`](/commands/npm-shrinkwrap).
See [package-lock.json](/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/commands/npm-shrinkwrap).
A `package` is:
* a) a folder containing a program described by a
[`package.json`](/configuring-npm/package-json) file
* a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file
* b) a gzipped tarball containing (a)
* c) a url that resolves to (b)
* d) a `<name>@<version>` that is published on the registry (see
[`registry`](/using-npm/registry)) with (c)
* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that
points to (d)
* d) a `<name>@<version>` that is published on the registry (see [`registry`](/using-npm/registry)) with (c)
* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that points to (d)
* f) a `<name>` that has a "latest" tag satisfying (e)
* g) a `<git remote url>` that resolves to (a)
Even if you never publish your package, you can still get a lot of benefits
of using npm if you just want to write a node program (a), and perhaps if
you also want to be able to easily install it elsewhere after packing it up
into a tarball (b).
Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and perhaps if you also want to be able to easily install it elsewhere after packing it up into a tarball (b).
* `npm install` (in a package directory, no arguments):
Install the dependencies to the local `node_modules` folder.
In global mode (ie, with `-g` or `--global` appended to the command),
it installs the current package context (ie, the current working
directory) as a global package.
In global mode (ie, with `-g` or `--global` appended to the command), it installs the current package context (ie, the current working directory) as a global package.
By default, `npm install` will install all modules listed as
dependencies in [`package.json`](/configuring-npm/package-json).
By default, `npm install` will install all modules listed as dependencies in [`package.json`](/configuring-npm/package-json).
With the `--production` flag (or when the `NODE_ENV` environment
variable is set to `production`), npm will not install modules listed
in `devDependencies`. To install all modules listed in both
`dependencies` and `devDependencies` when `NODE_ENV` environment
variable is set to `production`, you can use `--production=false`.
With the `--production` flag (or when the `NODE_ENV` environment variable is set to `production`), npm will not install modules listed in `devDependencies`.
To install all modules listed in both `dependencies` and `devDependencies` when `NODE_ENV` environment variable is set to `production`, you can use `--production=false`.
> NOTE: The `--production` flag has no particular meaning when adding a
dependency to a project.
> NOTE: The `--production` flag has no particular meaning when adding a dependency to a project.
* `npm install <folder>`:
If `<folder>` sits inside the root of your project, its dependencies will be installed and may
be hoisted to the top-level `node_modules` as they would for other
types of dependencies. If `<folder>` sits outside the root of your project,
*npm will not install the package dependencies* in the directory `<folder>`,
but it will create a symlink to `<folder>`.
If `<folder>` sits inside the root of your project, its dependencies will be installed and may be hoisted to the top-level `node_modules` as they would for other types of dependencies.
If `<folder>` sits outside the root of your project, *npm will not install the package dependencies* in the directory `<folder>`, but it will create a symlink to `<folder>`.
> NOTE: If you want to install the content of a directory like a package from the registry instead of creating a link, you would need to use the `--install-links` option.
@ -84,19 +65,14 @@ into a tarball (b).
* `npm install <tarball file>`:
Install a package that is sitting on the filesystem. Note: if you just
want to link a dev directory into your npm root, you can do this more
easily by using [`npm link`](/commands/npm-link).
Install a package that is sitting on the filesystem.
Note: if you just want to link a dev directory into your npm root, you can do this more easily by using [`npm link`](/commands/npm-link).
Tarball requirements:
* The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as the
extension.
* The package contents should reside in a subfolder inside the tarball
(usually it is called `package/`). npm strips one directory layer
when installing the package (an equivalent of `tar x
--strip-components=1` is run).
* The package must contain a `package.json` file with `name` and
`version` properties.
* The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as the extension.
* The package contents should reside in a subfolder inside the tarball (usually it is called `package/`).
npm strips one directory layer when installing the package (an equivalent of `tar x --strip-components=1` is run).
* The package must contain a `package.json` file with `name` and `version` properties.
Example:
@ -106,8 +82,8 @@ into a tarball (b).
* `npm install <tarball url>`:
Fetch the tarball url, and then install it. In order to distinguish between
this and other options, the argument must start with "http://" or "https://"
Fetch the tarball url, and then install it.
In order to distinguish between this and other options, the argument must start with "http://" or "https://"
Example:
@ -117,11 +93,11 @@ into a tarball (b).
* `npm install [<@scope>/]<name>`:
Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
[`config`](/using-npm/config#tag). The config's default value is `latest`.)
Do a `<name>@<tag>` install, where `<tag>` is the "tag" config.
(See [`config`](/using-npm/config#tag).
The config's default value is `latest`.)
In most cases, this will install the version of the modules tagged as
`latest` on the npm registry.
In most cases, this will install the version of the modules tagged as `latest` on the npm registry.
Example:
@ -130,11 +106,10 @@ into a tarball (b).
```
`npm install` saves any specified packages into `dependencies` by default.
Additionally, you can control where and how they get saved with some
additional flags:
Additionally, you can control where and how they get saved with some additional flags:
* `-P, --save-prod`: Package will appear in your `dependencies`. This
is the default unless `-D` or `-O` are present.
* `-P, --save-prod`: Package will appear in your `dependencies`.
This is the default unless `-D` or `-O` are present.
* `-D, --save-dev`: Package will appear in your `devDependencies`.
@ -145,26 +120,21 @@ into a tarball (b).
* `--no-save`: Prevents saving to `dependencies`.
When using any of the above options to save dependencies to your
package.json, there are two additional, optional flags:
When using any of the above options to save dependencies to your package.json, there are two additional, optional flags:
* `-E, --save-exact`: Saved dependencies will be configured with an
exact version rather than using npm's default semver range operator.
* `-E, --save-exact`: Saved dependencies will be configured with an exact version rather than using npm's default semver range operator.
* `-B, --save-bundle`: Saved dependencies will also be added to your
`bundleDependencies` list.
* `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
Further, if you have an `npm-shrinkwrap.json` or `package-lock.json`
then it will be updated as well.
Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it will be updated as well.
`<scope>` is optional. The package will be downloaded from the registry
associated with the specified scope. If no registry is associated with
the given scope the default registry is assumed. See
[`scope`](/using-npm/scope).
`<scope>` is optional.
The package will be downloaded from the registry associated with the specified scope.
If no registry is associated with the given scope the default registry is assumed.
See [`scope`](/using-npm/scope).
Note: if you do not include the @-symbol on your scope name, npm will
interpret this as a GitHub repository instead, see below. Scopes names
must also be followed by a slash.
Note: if you do not include the @-symbol on your scope name, npm will interpret this as a GitHub repository instead, see below.
Scopes names must also be followed by a slash.
Examples:
@ -180,13 +150,10 @@ into a tarball (b).
* `npm install <alias>@npm:<name>`:
Install a package under a custom alias. Allows multiple versions of
a same-name package side-by-side, more convenient import names for
packages with otherwise long ones, and using git forks replacements
or forked npm packages as replacements. Aliasing works only on your
project and does not rename packages in transitive dependencies.
Aliases should follow the naming conventions stated in
[`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).
Install a package under a custom alias.
Allows multiple versions of a same-name package side-by-side, more convenient import names for packages with otherwise long ones, and using git forks replacements or forked npm packages as replacements.
Aliasing works only on your project and does not rename packages in transitive dependencies.
Aliases should follow the naming conventions stated in [`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).
Examples:
@ -200,8 +167,7 @@ into a tarball (b).
* `npm install [<@scope>/]<name>@<tag>`:
Install the version of the package that is referenced by the specified tag.
If the tag does not exist in the registry data for that package, then this
will fail.
If the tag does not exist in the registry data for that package, then this will fail.
Example:
@ -212,8 +178,8 @@ into a tarball (b).
* `npm install [<@scope>/]<name>@<version>`:
Install the specified version of the package. This will fail if the
version has not been published to the registry.
Install the specified version of the package.
This will fail if the version has not been published to the registry.
Example:
@ -225,11 +191,9 @@ into a tarball (b).
* `npm install [<@scope>/]<name>@<version range>`:
Install a version of the package matching the specified version range.
This will follow the same rules for resolving dependencies described in
[`package.json`](/configuring-npm/package-json).
This will follow the same rules for resolving dependencies described in [`package.json`](/configuring-npm/package-json).
Note that most version ranges must be put in quotes so that your shell
will treat it as a single argument.
Note that most version ranges must be put in quotes so that your shell will treat it as a single argument.
Example:
@ -240,8 +204,8 @@ into a tarball (b).
* `npm install <git remote url>`:
Installs the package from the hosted git provider, cloning it with
`git`. For a full git remote url, only that URL will be attempted.
Installs the package from the hosted git provider, cloning it with `git`.
For a full git remote url, only that URL will be attempted.
```bash
<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
@ -250,23 +214,15 @@ into a tarball (b).
`<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or
`git+file`.
If `#<commit-ish>` is provided, it will be used to clone exactly that
commit. If the commit-ish has the format `#semver:<semver>`, `<semver>`
can be any valid semver range or exact version, and npm will look for
any tags or refs matching that range in the remote repository, much as
it would for a registry dependency. If neither `#<commit-ish>` or
`#semver:<semver>` is specified, then the default branch of the
repository is used.
If `#<commit-ish>` is provided, it will be used to clone exactly that commit.
If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency.
If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch of the repository is used.
If the repository makes use of submodules, those submodules will be
cloned as well.
If the repository makes use of submodules, those submodules will be cloned as well.
If the package being installed contains a `prepare` script, its
`dependencies` and `devDependencies` will be installed, and the prepare
script will be run, before the package is packaged and installed.
If the package being installed contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed.
The following git environment variables are recognized by npm and will
be added to the environment when running git:
The following git environment variables are recognized by npm and will be added to the environment when running git:
* `GIT_ASKPASS`
* `GIT_EXEC_PATH`
@ -292,19 +248,13 @@ into a tarball (b).
* `npm install <githubname>/<githubrepo>[#<commit-ish>]`:
* `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:
Install the package at `https://github.com/githubname/githubrepo` by
attempting to clone it using `git`.
Install the package at `https://github.com/githubname/githubrepo` by attempting to clone it using `git`.
If `#<commit-ish>` is provided, it will be used to clone exactly that
commit. If the commit-ish has the format `#semver:<semver>`, `<semver>`
can be any valid semver range or exact version, and npm will look for
any tags or refs matching that range in the remote repository, much as
it would for a registry dependency. If neither `#<commit-ish>` or
`#semver:<semver>` is specified, then the default branch is used.
If `#<commit-ish>` is provided, it will be used to clone exactly that commit.
If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency.
If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch is used.
As with regular git dependencies, `dependencies` and `devDependencies`
will be installed if the package has a `prepare` script before the
package is done installing.
As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
Examples:
@ -315,13 +265,10 @@ into a tarball (b).
* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`:
Install the package at `https://gist.github.com/gistID` by attempting to
clone it using `git`. The GitHub username associated with the gist is
optional and will not be saved in `package.json`.
Install the package at `https://gist.github.com/gistID` by attempting to clone it using `git`.
The GitHub username associated with the gist is optional and will not be saved in `package.json`.
As with regular git dependencies, `dependencies` and `devDependencies` will
be installed if the package has a `prepare` script before the package is
done installing.
As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
Example:
@ -331,19 +278,13 @@ into a tarball (b).
* `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:
Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo`
by attempting to clone it using `git`.
Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo` by attempting to clone it using `git`.
If `#<commit-ish>` is provided, it will be used to clone exactly that
commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
be any valid semver range or exact version, and npm will look for any tags
or refs matching that range in the remote repository, much as it would for a
registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
specified, then `master` is used.
If `#<commit-ish>` is provided, it will be used to clone exactly that commit.
If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency.
If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
As with regular git dependencies, `dependencies` and `devDependencies` will
be installed if the package has a `prepare` script before the package is
done installing.
As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
Example:
@ -353,19 +294,13 @@ into a tarball (b).
* `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:
Install the package at `https://gitlab.com/gitlabname/gitlabrepo`
by attempting to clone it using `git`.
Install the package at `https://gitlab.com/gitlabname/gitlabrepo` by attempting to clone it using `git`.
If `#<commit-ish>` is provided, it will be used to clone exactly that
commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
be any valid semver range or exact version, and npm will look for any tags
or refs matching that range in the remote repository, much as it would for a
registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
specified, then `master` is used.
If `#<commit-ish>` is provided, it will be used to clone exactly that commit.
If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency.
If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
As with regular git dependencies, `dependencies` and `devDependencies` will
be installed if the package has a `prepare` script before the package is
done installing.
As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
Example:
@ -381,19 +316,14 @@ For example:
npm install sax@">=0.1.0 <0.2.0" bench supervisor
```
The `--tag` argument will apply to all of the specified install targets. If
a tag with the given name exists, the tagged version is preferred over
newer versions.
The `--tag` argument will apply to all of the specified install targets.
If a tag with the given name exists, the tagged version is preferred over newer versions.
The `--dry-run` argument will report in the usual way what the install
would have done without actually installing anything.
The `--dry-run` argument will report in the usual way what the install would have done without actually installing anything.
The `--package-lock-only` argument will only update the
`package-lock.json`, instead of checking `node_modules` and downloading
dependencies.
The `--package-lock-only` argument will only update the `package-lock.json`, instead of checking `node_modules` and downloading dependencies.
The `-f` or `--force` argument will force npm to fetch remote resources
even if a local copy exists on disk.
The `-f` or `--force` argument will force npm to fetch remote resources even if a local copy exists on disk.
```bash
npm install sax --force
@ -401,15 +331,15 @@ npm install sax --force
### Configuration
See the [`config`](/using-npm/config) help doc. Many of the configuration
params have some effect on installation, since that's most of what npm
does.
See the [`config`](/using-npm/config) help doc.
Many of the configuration params have some effect on installation, since that's most of what npm does.
These are some of the most common options related to installation.
#### `save`
* Default: `true` unless when using `npm update` where it defaults to `false`
* Default: `true` unless when using `npm update` where it defaults to
`false`
* Type: Boolean
Save installed packages to a `package.json` file as dependencies.
@ -426,8 +356,8 @@ Will also prevent writing to `package-lock.json` if set to `false`.
* 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.
Dependencies saved to package.json will be configured with an exact
version rather than using npm's default semver range operator.
@ -436,12 +366,13 @@ rather than using npm's default semver range operator.
* 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.
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`
@ -453,11 +384,12 @@ folder instead of the current working directory. See
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -468,10 +400,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -482,15 +414,15 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -499,25 +431,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -527,18 +463,19 @@ the order in which omit/include are specified on the command-line.
* 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.
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.
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 an 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.
When such an 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.
@ -547,8 +484,8 @@ this warning is treated as a failure.
* Default: false
* Type: Boolean
Prefer to deduplicate packages if possible, rather than choosing a newer
version of a dependency.
Prefer to deduplicate packages if possible, rather than choosing a
newer version of a dependency.
@ -557,8 +494,9 @@ version of a dependency.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
@ -567,29 +505,31 @@ will also prevent _writing_ `package-lock.json` if `save` is true.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -600,10 +540,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -612,10 +552,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -625,14 +565,14 @@ submitted.
* 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 given date are installed.
If there are no versions available for the current set of dependencies, the
command will error.
versions that were available **on or before** the given date are
installed. If there are no versions available for the current set of
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`.
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`.
@ -644,9 +584,9 @@ will be used. For example, `foo@latest` might install `foo@1.2` even though
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.
@ -656,8 +596,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -666,13 +606,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -681,8 +622,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* Default: null
* Type: null or String
Override CPU architecture of native modules to install. Acceptable values
are same as `cpu` field of package.json, which comes from `process.arch`.
Override CPU architecture of native modules to install. Acceptable
values are same as `cpu` field of package.json, which comes from
`process.arch`.
@ -691,8 +633,8 @@ are same as `cpu` field of package.json, which comes from `process.arch`.
* Default: null
* Type: null or String
Override OS of native modules to install. Acceptable values are same as `os`
field of package.json, which comes from `process.platform`.
Override OS of native modules to install. Acceptable values are same
as `os` field of package.json, which comes from `process.platform`.
@ -701,8 +643,8 @@ field of package.json, which comes from `process.platform`.
* Default: null
* Type: null or String
Override libc of native modules to install. Acceptable values are same as
`libc` field of package.json
Override libc of native modules to install. Acceptable values are
same as `libc` field of package.json
@ -711,9 +653,9 @@ Override libc of native modules to install. Acceptable values are same as
* 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.
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:
@ -722,9 +664,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -736,13 +678,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -753,9 +696,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -764,16 +708,15 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.
### Algorithm
Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`,
the npm install algorithm produces:
Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`, the npm install algorithm produces:
```bash
A
@ -782,9 +725,8 @@ A
+-- D
```
That is, the dependency from B to C is satisfied by the fact that A already
caused C to be installed at a higher level. D is still installed at the top
level because nothing conflicts with it.
That is, the dependency from B to C is satisfied by the fact that A already caused C to be installed at a higher level.
D is still installed at the top level because nothing conflicts with it.
For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces:
@ -796,13 +738,10 @@ A
+-- D@1
```
Because B's D@1 will be installed in the top-level, C now has to install
D@2 privately for itself. This algorithm is deterministic, but different
trees may be produced if two dependencies are requested for installation in
a different order.
Because B's D@1 will be installed in the top-level, C now has to install D@2 privately for itself.
This algorithm is deterministic, but different trees may be produced if two dependencies are requested for installation in a different order.
See [folders](/configuring-npm/folders) for a more detailed description of
the specific folder structures that npm creates.
See [folders](/configuring-npm/folders) for a more detailed description of the specific folder structures that npm creates.
### See Also

233
deps/npm/docs/content/commands/npm-link.md vendored
View File

@ -14,31 +14,23 @@ alias: ln
### Description
This is handy for installing your own stuff, so that you can work on it and
test iteratively without having to continually rebuild.
This is handy for installing your own stuff, so that you can work on it and test iteratively without having to continually rebuild.
Package linking is a two-step process.
First, `npm link` in a package folder with no arguments will create a
symlink in the global folder `{prefix}/lib/node_modules/<package>` that
links to the package where the `npm link` command was executed. It will
also link any bins in the package to `{prefix}/bin/{name}`. Note that
`npm link` uses the global prefix (see `npm prefix -g` for its value).
First, `npm link` in a package folder with no arguments will create a symlink in the global folder `{prefix}/lib/node_modules/<package>` that links to the package where the `npm link` command was executed.
It will also link any bins in the package to `{prefix}/bin/{name}`.
Note that `npm link` uses the global prefix (see `npm prefix -g` for its value).
Next, in some other location, `npm link package-name` will create a
symbolic link from globally-installed `package-name` to `node_modules/` of
the current folder.
Next, in some other location, `npm link package-name` will create a symbolic link from globally-installed `package-name` to `node_modules/` of the current folder.
Note that `package-name` is taken from `package.json`, _not_ from the
directory name.
Note that `package-name` is taken from `package.json`, _not_ from the directory name.
The package name can be optionally prefixed with a scope. See
[`scope`](/using-npm/scope). The scope must be preceded by an @-symbol and
followed by a slash.
The package name can be optionally prefixed with a scope.
See [`scope`](/using-npm/scope).
The scope must be preceded by an @-symbol and followed by a slash.
When creating tarballs for `npm publish`, the linked packages are
"snapshotted" to their current state by resolving the symbolic links, if
they are included in `bundleDependencies`.
When creating tarballs for `npm publish`, the linked packages are "snapshotted" to their current state by resolving the symbolic links, if they are included in `bundleDependencies`.
For example:
@ -50,11 +42,11 @@ npm link redis # link-install the package
```
Now, any changes to `~/projects/node-redis` will be reflected in
`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link
should be to the package name, not the directory name for that package.
`~/projects/node-bloggy/node_modules/node-redis/`.
Note that the link should be to the package name, not the directory name for that package.
You may also shortcut the two steps in one. For example, to do the
above use-case in a shorter way:
You may also shortcut the two steps in one.
For example, to do the above use-case in a shorter way:
```bash
cd ~/projects/node-bloggy # go into the dir of your main project
@ -68,14 +60,12 @@ The second line is the equivalent of doing:
npm link redis
```
That is, it first creates a global link, and then links the global
installation target into your project's `node_modules` folder.
That is, it first creates a global link, and then links the global installation target into your project's `node_modules` folder.
Note that in this case, you are referring to the directory name,
`node-redis`, rather than the package name `redis`.
If your linked package is scoped (see [`scope`](/using-npm/scope)) your
link command must include that scope, e.g.
If your linked package is scoped (see [`scope`](/using-npm/scope)) your link command must include that scope, e.g.
```bash
npm link @myorg/privatepackage
@ -83,36 +73,26 @@ npm link @myorg/privatepackage
### Caveat
Note that package dependencies linked in this way are _not_ saved to
`package.json` by default, on the assumption that the intention is to have
a link stand in for a regular non-link dependency. Otherwise, for example,
if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace
the `^3.0.1` dependency with `file:../path/to/node-redis`, which you
probably don't want! Additionally, other users or developers on your
project would run into issues if they do not have their folders set up
exactly the same as yours.
Note that package dependencies linked in this way are _not_ saved to `package.json` by default, on the assumption that the intention is to have a link stand in for a regular non-link dependency.
Otherwise, for example, if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace the `^3.0.1` dependency with `file:../path/to/node-redis`, which you probably don't want! Additionally, other users or developers on your project would run into issues if they do not have their folders set up exactly the same as yours.
If you are adding a _new_ dependency as a link, you should add it to the
relevant metadata by running `npm install <dep> --package-lock-only`.
If you are adding a _new_ dependency as a link, you should add it to the relevant metadata by running `npm install <dep> --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 <dep> --save` to do so.
If you _want_ to save the `file:` reference in your `package.json` and `package-lock.json` files, you can use `npm link <dep> --save` to do so.
### Workspace Usage
`npm link <pkg> --workspace <name>` will link the relevant package as a
dependency of the specified workspace(s). Note that It may actually be
linked into the parent project's `node_modules` folder, if there are no
conflicting dependencies.
`npm link <pkg> --workspace <name>` will link the relevant package as a dependency of the specified workspace(s).
Note that It may actually be linked into the parent project's `node_modules` folder, if there are no conflicting dependencies.
`npm link --workspace <name>` will create a global link to the specified
workspace(s).
`npm link --workspace <name>` will create a global link to the specified workspace(s).
### Configuration
#### `save`
* Default: `true` unless when using `npm update` where it defaults to `false`
* Default: `true` unless when using `npm update` where it defaults to
`false`
* Type: Boolean
Save installed packages to a `package.json` file as dependencies.
@ -129,8 +109,8 @@ Will also prevent writing to `package-lock.json` if set to `false`.
* 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.
Dependencies saved to package.json will be configured with an exact
version rather than using npm's default semver range operator.
@ -139,12 +119,13 @@ rather than using npm's default semver range operator.
* 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.
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`
@ -156,11 +137,12 @@ folder instead of the current working directory. See
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -171,10 +153,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -185,8 +167,8 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
@ -196,18 +178,19 @@ on deeper dependencies. Sets `--install-strategy=shallow`.
* 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.
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.
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 an 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.
When such an 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.
@ -216,15 +199,16 @@ this warning is treated as a failure.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -233,25 +217,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -262,10 +250,10 @@ the order in which omit/include are specified on the command-line.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -274,10 +262,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -289,9 +277,9 @@ submitted.
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.
@ -301,8 +289,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -311,13 +299,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -326,9 +315,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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.
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:
@ -337,9 +326,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -351,13 +340,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -368,9 +358,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -379,9 +370,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

20
deps/npm/docs/content/commands/npm-login.md vendored
View File

@ -15,22 +15,20 @@ Note: This command is unaware of workspaces.
### Description
Verify a user in the specified registry, and save the credentials to the
`.npmrc` file. If no registry is specified, the default registry will be
used (see [`config`](/using-npm/config)).
`.npmrc` file.
If no registry is specified, the default registry will be used (see [`config`](/using-npm/config)).
When you run `npm login`, the CLI automatically generates a legacy token of `publish` type. For more information, see [About legacy tokens](/about-access-tokens#about-legacy-tokens).
When you run `npm login`, the CLI automatically generates a legacy token of `publish` type.
For more information, see [About legacy tokens](/about-access-tokens#about-legacy-tokens).
When using `legacy` for your `auth-type`, the username and password, are
read in from prompts.
When using `legacy` for your `auth-type`, the username and password, are read in from prompts.
To reset your password, go to <https://www.npmjs.com/forgot>
To change your email address, go to <https://www.npmjs.com/email-edit>
You may use this command multiple times with the same user account to
authorize on a new machine. When authenticating on a new machine,
the username, password and email address must all match with
your existing record.
You may use this command multiple times with the same user account to authorize on a new machine.
When authenticating on a new machine, the username, password and email address must all match with your existing record.
### Configuration
@ -79,8 +77,8 @@ npm init --scope=@foo --yes
* Default: "web"
* Type: "legacy" or "web"
What authentication strategy to use with `login`. Note that if an `otp`
config is given, this value will always be set to `legacy`.
What authentication strategy to use with `login`. Note that if an
`otp` config is given, this value will always be set to `legacy`.

11
deps/npm/docs/content/commands/npm-logout.md vendored
View File

@ -14,16 +14,13 @@ Note: This command is unaware of workspaces.
### Description
When logged into a registry that supports token-based authentication, tell
the server to end this token's session. This will invalidate the token
everywhere you're using it, not just for the current environment.
When logged into a registry that supports token-based authentication, tell the server to end this token's session.
This will invalidate the token everywhere you're using it, not just for the current environment.
When logged into a legacy registry that uses username and password
authentication, this will clear the credentials in your user configuration.
When logged into a legacy registry that uses username and password authentication, this will clear the credentials in your user configuration.
In this case, it will _only_ affect the current environment.
If `--scope` is provided, this will find the credentials for the registry
connected to that scope, if set.
If `--scope` is provided, this will find the credentials for the registry connected to that scope, if set.
### Configuration

136
deps/npm/docs/content/commands/npm-ls.md vendored
View File

@ -14,32 +14,25 @@ alias: list
### Description
This command will print to stdout all the versions of packages that are
installed, as well as their dependencies when `--all` is specified, in a
tree structure.
This command will print to stdout all the versions of packages that are installed, as well as their dependencies when `--all` is specified, in a tree structure.
Note: to get a "bottoms up" view of why a given package is included in the
tree at all, use [`npm explain`](/commands/npm-explain).
Note: to get a "bottoms up" view of why a given package is included in the tree at all, use [`npm explain`](/commands/npm-explain).
Positional arguments are `name@version-range` identifiers, which will limit
the results to only the paths to the packages named. Note that nested
packages will *also* show the paths to the specified packages. For
example, running `npm ls promzard` in npm's source tree will show:
Positional arguments are `name@version-range` identifiers, which will limit the results to only the paths to the packages named.
Note that nested packages will *also* show the paths to the specified packages.
For example, running `npm ls promzard` in npm's source tree will show:
```bash
npm@11.6.1 /path/to/npm
npm@11.6.2 /path/to/npm
└─┬ init-package-json@0.0.4
└── promzard@0.1.5
```
It will print out extraneous, missing, and invalid packages.
If a project specifies git urls for dependencies these are shown
in parentheses after the `name@version` to make it easier for users to
recognize potential forks of a project.
If a project specifies git urls for dependencies these are shown in parentheses after the `name@version` to make it easier for users to recognize potential forks of a project.
The tree shown is the logical dependency tree, based on package
dependencies, not the physical layout of your `node_modules` folder.
The tree shown is the logical dependency tree, based on package dependencies, not the physical layout of your `node_modules` folder.
When run as `ll` or `la`, it shows extended information by default.
@ -50,9 +43,9 @@ When run as `ll` or `la`, it shows extended information by default.
* 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.
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.
@ -63,8 +56,8 @@ upon by the current project.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -84,8 +77,8 @@ Show extended information in `ls`, `search`, and `help-search`.
* 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.
@ -94,12 +87,13 @@ Output parseable results from commands that write to standard output. For
* 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.
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`
@ -107,20 +101,21 @@ folder instead of the current working directory. See
#### `depth`
* Default: `Infinity` if `--all` is set, otherwise `0`
* Default: `Infinity` if `--all` is set; otherwise, `0`
* Type: null or Number
The depth to go when recursing packages for `npm ls`.
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.
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.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -129,25 +124,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -156,7 +155,8 @@ the order in which omit/include are specified on the command-line.
* Default: false
* Type: Boolean
Used with `npm ls`, limiting output to only those packages that are linked.
Used with `npm ls`, limiting output to only those packages that are
linked.
@ -165,25 +165,27 @@ Used with `npm ls`, limiting output to only those packages that are linked.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
#### `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.
* 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 instead of unicode glyphs.
When set to true, npm uses unicode characters in the tree output.
When false, it uses ascii characters instead of unicode glyphs.
@ -192,9 +194,9 @@ false, it uses ascii characters instead of unicode glyphs.
* 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.
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:
@ -203,9 +205,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -217,13 +219,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -234,9 +237,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -245,9 +249,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

22
deps/npm/docs/content/commands/npm-org.md vendored
View File

@ -56,9 +56,8 @@ $ npm org ls my-org @mx-santos
### Description
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.
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
@ -76,11 +75,12 @@ The base URL of the npm registry.
* 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`.
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.
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.
@ -91,8 +91,8 @@ password, npm will prompt on the command line for one.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -103,8 +103,8 @@ Not supported by all npm commands.
* 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.

108
deps/npm/docs/content/commands/npm-outdated.md vendored
View File

@ -12,39 +12,26 @@ npm outdated [<package-spec> ...]
### Description
This command will check the registry to see if any (or, specific) installed
packages are currently outdated.
This command will check the registry to see if any (or, specific) installed packages are currently outdated.
By default, only the direct dependencies of the root project and direct
dependencies of your configured *workspaces* are shown.
By default, only the direct dependencies of the root project and direct dependencies of your configured *workspaces* are shown.
Use `--all` to find all outdated meta-dependencies as well.
In the output:
* `wanted` is the maximum version of the package that satisfies the semver
range specified in `package.json`. If there's no available semver range
(i.e. you're running `npm outdated --global`, or the package isn't
included in `package.json`), then `wanted` shows the currently-installed
version.
* `wanted` is the maximum version of the package that satisfies the semver range specified in `package.json`.
If there's no available semver range (i.e. you're running `npm outdated --global`, or the package isn't included in `package.json`), then `wanted` shows the currently-installed version.
* `latest` is the version of the package tagged as latest in the registry.
Running `npm publish` with no special configuration will publish the
package with a dist-tag of `latest`. This may or may not be the maximum
version of the package, or the most-recently published version of the
package, depending on how the package's developer manages the latest
[dist-tag](/commands/npm-dist-tag).
Running `npm publish` with no special configuration will publish the package with a dist-tag of `latest`.
This may or may not be the maximum version of the package, or the most-recently published version of the package, depending on how the package's developer manages the latest [dist-tag](/commands/npm-dist-tag).
* `location` is where in the physical tree the package is located.
* `depended by` shows which package depends on the displayed dependency
* `package type` (when using `--long` / `-l`) tells you whether this
package is a `dependency` or a dev/peer/optional dependency. Packages not
included in `package.json` are always marked `dependencies`.
* `homepage` (when using `--long` / `-l`) is the `homepage` value contained
in the package's packument
* `package type` (when using `--long` / `-l`) tells you whether this package is a `dependency` or a dev/peer/optional dependency.
Packages not included in `package.json` are always marked `dependencies`.
* `homepage` (when using `--long` / `-l`) is the `homepage` value contained in the package's packument
* `depended by location` (when using `--long` / `-l`) shows location of the package that depends on the displayed dependency
* Red means there's a newer version matching your semver requirements, so
you should update now.
* Yellow indicates that there's a newer version _above_ your semver
requirements (usually new major, or new 0.x minor) so proceed with
caution.
* Red means there's a newer version matching your semver requirements, so you should update now.
* Yellow indicates that there's a newer version _above_ your semver requirements (usually new major, or new 0.x minor) so proceed with caution.
### An example
@ -70,20 +57,14 @@ With these `dependencies`:
A few things to note:
* `glob` requires `^5`, which prevents npm from installing `glob@6`, which
is outside the semver range.
* Git dependencies will always be reinstalled, because of how they're
specified. The installed committish might satisfy the dependency
specifier (if it's something immutable, like a commit SHA), or it might
not, so `npm outdated` and `npm update` have to fetch Git repos to check.
This is why currently doing a reinstall of a Git dependency always forces
a new clone and install.
* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because
npm uses dist-tags to manage its `latest` and `next` release channels.
`npm update` will install the _newest_ version, but `npm install npm`
(with no semver range) will install whatever's tagged as `latest`.
* `once` is just plain out of date. Reinstalling `node_modules` from
scratch or running `npm update` will bring it up to spec.
* `glob` requires `^5`, which prevents npm from installing `glob@6`, which is outside the semver range.
* Git dependencies will always be reinstalled, because of how they're specified.
The installed committish might satisfy the dependency specifier (if it's something immutable, like a commit SHA), or it might not, so `npm outdated` and `npm update` have to fetch Git repos to check.
This is why currently doing a reinstall of a Git dependency always forces a new clone and install.
* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because npm uses dist-tags to manage its `latest` and `next` release channels.
`npm update` will install the _newest_ version, but `npm install npm` (with no semver range) will install whatever's tagged as `latest`.
* `once` is just plain out of date.
Reinstalling `node_modules` from scratch or running `npm update` will bring it up to spec.
### Configuration
@ -92,9 +73,9 @@ A few things to note:
* 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.
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.
@ -105,8 +86,8 @@ upon by the current project.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -126,8 +107,8 @@ Show extended information in `ls`, `search`, and `help-search`.
* 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.
@ -136,12 +117,13 @@ Output parseable results from commands that write to standard output. For
* 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.
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`
@ -152,9 +134,9 @@ folder instead of the current working directory. See
* 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.
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:
@ -163,9 +145,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -175,14 +157,14 @@ This value is not exported to the environment for child processes.
* 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 given date are installed.
If there are no versions available for the current set of dependencies, the
command will error.
versions that were available **on or before** the given date are
installed. If there are no versions available for the current set of
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`.
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`.

56
deps/npm/docs/content/commands/npm-owner.md vendored
View File

@ -18,20 +18,18 @@ alias: author
Manage ownership of published packages.
* ls: List all the users who have access to modify a package and push new
versions. Handy when you need to know who to bug for help.
* add: Add a new user as a maintainer of a package. This user is enabled
to modify metadata, publish new versions, and add other owners.
* rm: Remove a user from the package owner list. This immediately revokes
their privileges.
* ls: List all the users who have access to modify a package and push new versions.
Handy when you need to know who to bug for help.
* add: Add a new user as a maintainer of a package.
This user is enabled to modify metadata, publish new versions, and add other owners.
* rm: Remove a user from the package owner list.
This immediately revokes their privileges.
Note that there is only one level of access. Either you can modify a package,
or you can't. Future versions may contain more fine-grained access levels, but
that is not implemented at this time.
Note that there is only one level of access.
Either you can modify a package, or you can't.
Future versions may contain more fine-grained access levels, but that is not implemented at this time.
If you have two-factor authentication enabled with `auth-and-writes` (see
[`npm-profile`](/commands/npm-profile)) then you'll need to go through a second factor
flow when changing ownership or include an otp on the command line with `--otp`.
If you have two-factor authentication enabled with `auth-and-writes` (see [`npm-profile`](/commands/npm-profile)) then you'll need to go through a second factor flow when changing ownership or include an otp on the command line with `--otp`.
### Configuration
@ -49,11 +47,12 @@ The base URL of the npm registry.
* 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`.
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.
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.
@ -62,9 +61,9 @@ password, npm will prompt on the command line for one.
* 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.
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:
@ -73,9 +72,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -87,13 +86,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.

66
deps/npm/docs/content/commands/npm-pack.md vendored
View File

@ -17,13 +17,14 @@ npm pack <package-spec>
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -34,8 +35,8 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -55,9 +56,9 @@ Directory in which `npm pack` will save tarballs.
* 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.
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:
@ -66,9 +67,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -80,13 +81,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -97,9 +99,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -110,23 +113,18 @@ This value is not exported to the environment for child processes.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
### Description
For anything that's installable (that is, a package folder, tarball,
tarball url, git url, name@tag, name@version, name, or scoped name), this
command will fetch it to the cache, copy the tarball to the current working
directory as `<name>-<version>.tgz`, and then write the filenames out to
stdout.
For anything that's installable (that is, a package folder, tarball, tarball url, git url, name@tag, name@version, name, or scoped name), this command will fetch it to the cache, copy the tarball to the current working directory as `<name>-<version>.tgz`, and then write the filenames out to stdout.
If the same package is specified multiple times, then the file will be
overwritten the second time.
If the same package is specified multiple times, then the file will be overwritten the second time.
If no arguments are supplied, then npm packs the current package folder.

123
deps/npm/docs/content/commands/npm-pkg.md vendored
View File

@ -18,13 +18,9 @@ npm pkg fix
### Description
A command that automates the management of `package.json` files.
`npm pkg` provide 3 different sub commands that allow you to modify or retrieve
values for given object keys in your `package.json`.
`npm pkg` provide 3 different sub commands that allow you to modify or retrieve values for given object keys in your `package.json`.
The syntax to retrieve and set fields is a dot separated representation of
the nested object properties to be found within your `package.json`, it's the
same notation used in [`npm view`](/commands/npm-view) to retrieve information
from the registry manifest, below you can find more examples on how to use it.
The syntax to retrieve and set fields is a dot separated representation of the nested object properties to be found within your `package.json`, it's the same notation used in [`npm view`](/commands/npm-view) to retrieve information from the registry manifest, below you can find more examples on how to use it.
Returned values are always in **json** format.
@ -32,8 +28,7 @@ Returned values are always in **json** format.
Retrieves a value `key`, defined in your `package.json` file.
For example, in order to retrieve the name of the current package, you
can run:
For example, in order to retrieve the name of the current package, you can run:
```bash
npm pkg get name
@ -45,32 +40,29 @@ Returned values are always in **json** format.
npm pkg get name version
```
You can view child fields by separating them with a period. To retrieve
the value of a test `script` value, you would run the following command:
You can view child fields by separating them with a period.
To retrieve the value of a test `script` value, you would run the following command:
```bash
npm pkg get scripts.test
```
For fields that are arrays, requesting a non-numeric field will return
all of the values from the objects in the list. For example, to get all
the contributor emails for a package, you would run:
For fields that are arrays, requesting a non-numeric field will return all of the values from the objects in the list.
For example, to get all the contributor emails for a package, you would run:
```bash
npm pkg get contributors.email
```
You may also use numeric indices in square braces to specifically select
an item in an array field. To just get the email address of the first
contributor in the list, you can run:
You may also use numeric indices in square braces to specifically select an item in an array field.
To just get the email address of the first contributor in the list, you can run:
```bash
npm pkg get contributors[0].email
```
For complex fields you can also name a property in square brackets
to specifically select a child field. This is especially helpful
with the exports object:
For complex fields you can also name a property in square brackets to specifically select a child field.
This is especially helpful with the exports object:
```bash
npm pkg get "exports[.].require"
@ -78,19 +70,12 @@ Returned values are always in **json** format.
* `npm pkg set <field>=<value>`
Sets a `value` in your `package.json` based on the `field` value. When
saving to your `package.json` file the same set of rules used during
`npm install` and other cli commands that touches the `package.json` file
are used, making sure to respect the existing indentation and possibly
applying some validation prior to saving values to the file.
Sets a `value` in your `package.json` based on the `field` value.
When saving to your `package.json` file the same set of rules used during `npm install` and other cli commands that touches the `package.json` file are used, making sure to respect the existing indentation and possibly applying some validation prior to saving values to the file.
The same syntax used to retrieve values from your package can also be used
to define new properties or overriding existing ones, below are some
examples of how the dot separated syntax can be used to edit your
`package.json` file.
The same syntax used to retrieve values from your package can also be used to define new properties or overriding existing ones, below are some examples of how the dot separated syntax can be used to edit your `package.json` file.
Defining a new bin named `mynewcommand` in your `package.json` that points
to a file `cli.js`:
Defining a new bin named `mynewcommand` in your `package.json` that points to a file `cli.js`:
```bash
npm pkg set bin.mynewcommand=cli.js
@ -102,23 +87,19 @@ Returned values are always in **json** format.
npm pkg set description='Awesome package' engines.node='>=10'
```
It's also possible to add to array values, for example to add a new
contributor entry:
It's also possible to add to array values, for example to add a new contributor entry:
```bash
npm pkg set contributors[0].name='Foo' contributors[0].email='foo@bar.ca'
```
You may also append items to the end of an array using the special
empty bracket notation:
You may also append items to the end of an array using the special empty bracket notation:
```bash
npm pkg set contributors[].name='Foo' contributors[].name='Bar'
```
It's also possible to parse values as json prior to saving them to your
`package.json` file, for example in order to set a `"private": true`
property:
It's also possible to parse values as json prior to saving them to your `package.json` file, for example in order to set a `"private": true` property:
```bash
npm pkg set private=true --json
@ -134,9 +115,8 @@ Returned values are always in **json** format.
Deletes a `key` from your `package.json`
The same syntax used to set values from your package can also be used
to remove existing ones. For example, in order to remove a script named
build:
The same syntax used to set values from your package can also be used to remove existing ones.
For example, in order to remove a script named build:
```bash
npm pkg delete scripts.build
@ -144,28 +124,20 @@ Returned values are always in **json** format.
* `npm pkg fix`
Auto corrects common errors in your `package.json`. npm already
does this during `publish`, which leads to subtle (mostly harmless)
differences between the contents of your `package.json` file and the
manifest that npm uses during installation.
Auto corrects common errors in your `package.json`.
npm already does this during `publish`, which leads to subtle (mostly harmless) differences between the contents of your `package.json` file and the manifest that npm uses during installation.
### Workspaces support
You can set/get/delete items across your configured workspaces by using the
[`workspace`](/using-npm/config#workspace) or
[`workspaces`](/using-npm/config#workspaces) config options.
You can set/get/delete items across your configured workspaces by using the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) config options.
For example, setting a `funding` value across all configured workspaces
of a project:
For example, setting a `funding` value across all configured workspaces of a project:
```bash
npm pkg set funding=https://example.com --ws
```
When using `npm pkg get` to retrieve info from your configured workspaces, the
returned result will be in a json format in which top level keys are the
names of each workspace, the values of these keys will be the result values
returned from each of the configured workspaces, e.g:
When using `npm pkg get` to retrieve info from your configured workspaces, the returned result will be in a json format in which top level keys are the names of each workspace, the values of these keys will be the result values returned from each of the configured workspaces, e.g:
```
npm pkg get name version --ws
@ -194,14 +166,16 @@ 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 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.
* Allow conflicting peerDependencies to be installed in the root
project.
* Implicitly set `--yes` during `npm init`.
* Allow clobbering existing values in `npm pkg`
* Allow unpublishing of entire packages (not just a single version).
@ -218,8 +192,8 @@ recommended that you do not use this option!
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -230,9 +204,9 @@ Not supported by all npm commands.
* 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.
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:
@ -241,9 +215,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -255,13 +229,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
## See Also

20
deps/npm/docs/content/commands/npm-prefix.md vendored
View File

@ -14,12 +14,11 @@ Note: This command is unaware of workspaces.
### Description
Print the local prefix to standard output. This is the closest parent directory
to contain a `package.json` file or `node_modules` directory, unless `-g` is
also specified.
Print the local prefix to standard output.
This is the closest parent directory to contain a `package.json` file or `node_modules` directory, unless `-g` is also specified.
If `-g` is specified, this will be the value of the global prefix. See
[`npm config`](/commands/npm-config) for more detail.
If `-g` is specified, this will be the value of the global prefix.
See [`npm config`](/commands/npm-config) for more detail.
### Example
@ -40,12 +39,13 @@ npm prefix -g
* 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.
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`

52
deps/npm/docs/content/commands/npm-profile.md vendored
View File

@ -17,12 +17,11 @@ Note: This command is unaware of workspaces.
### Description
Change your profile information on the registry. Note that this command
depends on the registry implementation, so third-party registries may not
support this interface.
Change your profile information on the registry.
Note that this command depends on the registry implementation, so third-party registries may not support this interface.
* `npm profile get [<property>]`: Display all of the properties of your
profile, or one or more specific properties. It looks like:
* `npm profile get [<property>]`: Display all of the properties of your profile, or one or more specific properties.
It looks like:
```
name: example
@ -37,23 +36,19 @@ created: 2015-02-26T01:38:35.892Z
updated: 2017-10-02T21:29:45.922Z
```
* `npm profile set <property> <value>`: Set the value of a profile
property. You can set the following properties this way: email, fullname,
homepage, freenode, twitter, github
* `npm profile set <property> <value>`: Set the value of a profile property.
You can set the following properties this way: email, fullname, homepage, freenode, twitter, github
* `npm profile set password`: Change your password. This is interactive,
you'll be prompted for your current password and a new password. You'll
also be prompted for an OTP if you have two-factor authentication
enabled.
* `npm profile set password`: Change your password.
This is interactive, you'll be prompted for your current password and a new password.
You'll also be prompted for an OTP if you have two-factor authentication enabled.
* `npm profile enable-2fa [auth-and-writes|auth-only]`: Enables two-factor
authentication. Defaults to `auth-and-writes` mode. Modes are:
* `auth-only`: Require an OTP when logging in or making changes to your
account's authentication. The OTP will be required on both the website
and the command line.
* `auth-and-writes`: Requires an OTP at all the times `auth-only` does,
and also requires one when publishing a module, setting the `latest`
dist-tag, or changing access via `npm access` and `npm owner`.
* `npm profile enable-2fa [auth-and-writes|auth-only]`: Enables two-factor authentication.
Defaults to `auth-and-writes` mode.
Modes are:
* `auth-only`: Require an OTP when logging in or making changes to your account's authentication.
The OTP will be required on both the website and the command line.
* `auth-and-writes`: Requires an OTP at all the times `auth-only` does, and also requires one when publishing a module, setting the `latest` dist-tag, or changing access via `npm access` and `npm owner`.
* `npm profile disable-2fa`: Disables two-factor authentication.
@ -79,8 +74,8 @@ The base URL of the npm registry.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -91,8 +86,8 @@ Not supported by all npm commands.
* 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.
@ -101,11 +96,12 @@ Output parseable results from commands that write to standard output. For
* 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`.
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.
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.

120
deps/npm/docs/content/commands/npm-prune.md vendored
View File

@ -12,32 +12,26 @@ npm prune [[<@scope>/]<pkg>...]
### Description
This command removes "extraneous" packages. If a package name is provided,
then only packages matching one of the supplied names are removed.
This command removes "extraneous" packages.
If a package name is provided, then only packages matching one of the supplied names are removed.
Extraneous packages are those present in the `node_modules` folder that are
not listed as any package's dependency list.
Extraneous packages are those present in the `node_modules` folder that are not listed as any package's dependency list.
If the `--omit=dev` flag is specified or the `NODE_ENV` environment
variable is set to `production`, this command will remove the packages
specified in your `devDependencies`.
If the `--omit=dev` flag is specified or the `NODE_ENV` environment variable is set to `production`, this command will remove the packages specified in your `devDependencies`.
If the `--dry-run` flag is used then no changes will actually be made.
If the `--json` flag is used, then the changes `npm prune` made (or would
have made with `--dry-run`) are printed as a JSON object.
If the `--json` flag is used, then the changes `npm prune` made (or would have made with `--dry-run`) are printed as a JSON object.
In normal operation, extraneous modules are pruned automatically, so you'll
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.
In normal operation, extraneous modules are pruned automatically, so you'll 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.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -46,25 +40,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -73,13 +71,14 @@ the order in which omit/include are specified on the command-line.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -90,8 +89,8 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -99,16 +98,17 @@ Not supported by all npm commands.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -119,10 +119,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -131,9 +131,9 @@ run any pre- or post-scripts.
* 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.
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:
@ -142,9 +142,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -156,13 +156,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -173,9 +174,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -184,9 +186,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

159
deps/npm/docs/content/commands/npm-publish.md vendored
View File

@ -14,79 +14,55 @@ npm publish <package-spec>
Publishes a package to the registry so that it can be installed by name.
By default npm will publish to the public registry. This can be
overridden by specifying a different default registry or using a
[`scope`](/using-npm/scope) in the name, combined with a
scope-configured registry (see
[`package.json`](/configuring-npm/package-json)).
By default npm will publish to the public registry.
This can be overridden by specifying a different default registry or using a [`scope`](/using-npm/scope) in the name, combined with a scope-configured registry (see [`package.json`](/configuring-npm/package-json)).
A `package` is interpreted the same way as other commands (like
`npm install`) and can be:
A `package` is interpreted the same way as other commands (like `npm install`) and can be:
* a) a folder containing a program described by a
[`package.json`](/configuring-npm/package-json) file
* a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file
* b) a gzipped tarball containing (a)
* c) a url that resolves to (b)
* d) a `<name>@<version>` that is published on the registry (see
[`registry`](/using-npm/registry)) with (c)
* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that
points to (d)
* d) a `<name>@<version>` that is published on the registry (see [`registry`](/using-npm/registry)) with (c)
* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that points to (d)
* f) a `<name>` that has a "latest" tag satisfying (e)
* g) a `<git remote url>` that resolves to (a)
The publish will fail if the package name and version combination already
exists in the specified registry.
The publish will fail if the package name and version combination already exists in the specified registry.
Once a package is published with a given name and version, that specific
name and version combination can never be used again, even if it is removed
with [`npm unpublish`](/commands/npm-unpublish).
Once a package is published with a given name and version, that specific name and version combination can never be used again, even if it is removed with [`npm unpublish`](/commands/npm-unpublish).
As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the
tarball will be submitted to the registry during publication. Subsequent
installs will use the strongest supported algorithm to verify downloads.
As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the tarball will be submitted to the registry during publication.
Subsequent installs will use the strongest supported algorithm to verify downloads.
Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures
out the files to be included and packs them into a tarball to be uploaded
to the registry.
Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures out the files to be included and packs them into a tarball to be uploaded to the registry.
### Files included in package
To see what will be included in your package, run `npm pack --dry-run`. All
files are included by default, with the following exceptions:
To see what will be included in your package, run `npm pack --dry-run`.
All files are included by default, with the following exceptions:
- Certain files that are relevant to package installation and distribution
are always included. For example, `package.json`, `README.md`,
- Certain files that are relevant to package installation and distribution are always included.
For example, `package.json`, `README.md`,
`LICENSE`, and so on.
- If there is a "files" list in
[`package.json`](/configuring-npm/package-json), then only the files
specified will be included. (If directories are specified, then they
will be walked recursively and their contents included, subject to the
same ignore rules.)
- If there is a "files" list in [`package.json`](/configuring-npm/package-json), then only the files specified will be included.
(If directories are specified, then they will be walked recursively and their contents included, subject to the same ignore rules.)
- If there is a `.gitignore` or `.npmignore` file, then ignored files in
that and all child directories will be excluded from the package. If
_both_ files exist, then the `.gitignore` is ignored, and only the
- If there is a `.gitignore` or `.npmignore` file, then ignored files in that and all child directories will be excluded from the package.
If _both_ files exist, then the `.gitignore` is ignored, and only the
`.npmignore` is used.
`.npmignore` files follow the [same pattern
rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
as `.gitignore` files
`.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) as `.gitignore` files
- If the file matches certain patterns, then it will _never_ be included,
unless explicitly added to the `"files"` list in `package.json`, or
un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file.
- If the file matches certain patterns, then it will _never_ be included, unless explicitly added to the `"files"` list in `package.json`, or un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file.
- Symbolic links are never included in npm packages.
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.
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.
See [`package.json`](/configuring-npm/package-json) for more info on
what can and can't be ignored.
See [`package.json`](/configuring-npm/package-json) for more info on what can and can't be ignored.
### Configuration
@ -95,24 +71,24 @@ what can and can't be ignored.
* 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.
It is the tag added to the package@version specified in the `npm dist-tag
add` command, if no explicit tag is given.
It is the tag added to the package@version specified in the `npm
dist-tag add` 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.
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.
If used in the `npm publish` command, this is the tag that will be added to
the package submitted to the registry.
If used in the `npm publish` command, this is the tag that will be
added to the package submitted to the registry.
#### `access`
* Default: 'public' for new packages, existing packages it will not change the
current level
* Default: 'public' for new packages, existing packages it will not
change the current level
* Type: null, "restricted", or "public"
If you do not want your scoped package to be publicly viewable (and
@ -120,10 +96,10 @@ installable) set `--access=restricted`.
Unscoped packages cannot be set to `restricted`.
Note: This defaults to not changing the current access level for existing
packages. Specifying a value of `restricted` or `public` during publish will
change the access for an existing package the same way that `npm access set
status` would.
Note: This defaults to not changing the current access level for
existing packages. Specifying a value of `restricted` or `public`
during publish will change the access for an existing package the
same way that `npm access set status` would.
@ -132,13 +108,14 @@ status` would.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -147,11 +124,12 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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`.
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.
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.
@ -160,9 +138,9 @@ password, npm will prompt on the command line for one.
* 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.
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:
@ -171,9 +149,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -185,13 +163,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -202,9 +181,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -213,8 +193,8 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When publishing from a supported cloud CI/CD system, the package will be
publicly linked to where it was built and published from.
When publishing from a supported cloud CI/CD system, the package will
be publicly linked to where it was built and published from.
This config cannot be used with: `provenance-file`
@ -223,7 +203,8 @@ This config can not be used with: `provenance-file`
* Default: null
* Type: Path
When publishing, the provenance bundle at the given path will be used.
When publishing, the provenance bundle at the given path will be
used.
This config cannot be used with: `provenance`

75
deps/npm/docs/content/commands/npm-query.md vendored
View File

@ -12,8 +12,7 @@ npm query <selector>
### Description
The `npm query` command allows for usage of css selectors in order to retrieve
an array of dependency objects.
The `npm query` command allows for usage of css selectors in order to retrieve an array of dependency objects.
### Piping npm query to other commands
@ -138,21 +137,16 @@ npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
### Expecting a certain number of results
One common use of `npm query` is to make sure there is only one version of
a certain dependency in your tree. This is especially common for
ecosystems like that rely on `typescript` where having state split
across two different but identically-named packages causes bugs. You
can use the `--expect-results` or `--expect-result-count` in your setup
to ensure that npm will exit with an exit code if your tree doesn't look
like you want it to.
One common use of `npm query` is to make sure there is only one version of a certain dependency in your tree.
This is especially common for ecosystems like that rely on `typescript` where having state split across two different but identically-named packages causes bugs.
You can use the `--expect-results` or `--expect-result-count` in your setup to ensure that npm will exit with an exit code if your tree doesn't look like you want it to.
```sh
$ npm query '#react' --expect-result-count=1
```
Perhaps you want to quickly check if there are any production
dependencies that could be updated:
Perhaps you want to quickly check if there are any production dependencies that could be updated:
```sh
$ npm query ':root>:outdated(in-range).prod' --no-expect-results
@ -160,7 +154,8 @@ $ npm query ':root>:outdated(in-range).prod' --no-expect-results
### Package lock only mode
If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded. This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.
This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
### Configuration
@ -169,12 +164,13 @@ If package-lock-only is enabled, only the information in the package lock (or sh
* 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.
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`
@ -185,9 +181,9 @@ folder instead of the current working directory. See
* 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.
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:
@ -196,9 +192,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -210,13 +206,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -227,9 +224,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -238,14 +236,15 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
@ -254,8 +253,8 @@ For `list` this means the output will be based on the tree described by the
* Default: null
* Type: null or Boolean
Tells npm whether or not to expect results from the command. Can be either
true (expect some results) or false (expect no results).
Tells npm whether or not to expect results from the command. Can be
either true (expect some results) or false (expect no results).
This config cannot be used with: `expect-result-count`

81
deps/npm/docs/content/commands/npm-rebuild.md vendored
View File

@ -36,7 +36,8 @@ If there is a `binding.gyp` file in the root of your package, then npm will use
}
```
This default behavior is suppressed if the `package.json` has its own `install` or `preinstall` scripts. It is also suppressed if the package specifies `"gypfile": false`
This default behavior is suppressed if the `package.json` has its own `install` or `preinstall` scripts.
It is also suppressed if the package specifies `"gypfile": false`
### Configuration
@ -45,12 +46,13 @@ This default behavior is suppressed if the `package.json` has its own `install`
* 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.
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`
@ -64,24 +66,25 @@ folder instead of the current working directory. See
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.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -92,10 +95,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -104,9 +107,9 @@ run any pre- or post-scripts.
* 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.
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:
@ -115,9 +118,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -129,13 +132,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -146,9 +150,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -157,9 +162,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

39
deps/npm/docs/content/commands/npm-repo.md vendored
View File

@ -12,11 +12,8 @@ npm repo [<pkgname> [<pkgname> ...]]
### Description
This command tries to guess at the likely location of a package's
repository URL, and then tries to open it using the
[`--browser` config](/using-npm/config#browser) param. If no package name is
provided, it will search for a `package.json` in the current folder and use the
`repository` property.
This command tries to guess at the likely location of a package's repository URL, and then tries to open it using the [`--browser` config](/using-npm/config#browser) param.
If no package name is provided, it will search for a `package.json` in the current folder and use the `repository` property.
### Configuration
@ -48,9 +45,9 @@ The base URL of the npm registry.
* 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.
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:
@ -59,9 +56,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -73,13 +70,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -90,9 +88,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.

22
deps/npm/docs/content/commands/npm-restart.md vendored
View File

@ -12,18 +12,16 @@ npm restart [-- <args>]
### Description
This restarts a project. It is equivalent to running `npm run
restart`.
This restarts a project.
It is equivalent to running `npm run restart`.
If the current project has a `"restart"` script specified in
`package.json`, then the following scripts will be run:
If the current project has a `"restart"` script specified in `package.json`, then the following scripts will be run:
1. prerestart
2. restart
3. postrestart
If it does _not_ have a `"restart"` script specified, but it does have
`stop` and/or `start` scripts, then the following scripts will be run:
If it does _not_ have a `"restart"` script specified, but it does have `stop` and/or `start` scripts, then the following scripts will be run:
1. prerestart
2. prestop
@ -43,10 +41,10 @@ If it does _not_ have a `"restart"` script specified, but it does have
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -55,8 +53,8 @@ run any pre- or post-scripts.
* 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 <package-spec>` commands.
The shell to use for scripts run with the `npm exec`, `npm run` and
`npm init <package-spec>` commands.

15
deps/npm/docs/content/commands/npm-root.md vendored
View File

@ -16,8 +16,8 @@ Note: This command is unaware of workspaces.
Print the effective `node_modules` folder to standard out.
Useful for using npm in shell scripts that do things with the
`node_modules` folder. For example:
Useful for using npm in shell scripts that do things with the `node_modules` folder.
For example:
```bash
#!/bin/bash
@ -32,12 +32,13 @@ echo "Global packages installed in: ${global_node_modules}"
* 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.
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`

150
deps/npm/docs/content/commands/npm-run.md vendored
View File

@ -14,16 +14,15 @@ aliases: run-script, rum, urn
### Description
This runs an arbitrary command from a package's `"scripts"` object. If no
This runs an arbitrary command from a package's `"scripts"` object.
If no
`"command"` is provided, it will list the available scripts.
`run[-script]` is used by the test, start, restart, and stop commands, but
can be called directly, as well. When the scripts in the package are
printed out, they're separated into lifecycle (test, start, restart) and
directly-run scripts.
`run[-script]` is used by the test, start, restart, and stop commands, but can be called directly, as well.
When the scripts in the package are printed out, they're separated into lifecycle (test, start, restart) and directly-run scripts.
Any positional arguments are passed to the specified script. Use `--` to
pass `-`-prefixed flags and options which would otherwise be parsed by npm.
Any positional arguments are passed to the specified script.
Use `--` to pass `-`-prefixed flags and options which would otherwise be parsed by npm.
For example:
@ -31,19 +30,14 @@ For example:
npm run test -- --grep="pattern"
```
The arguments will only be passed to the script specified after `npm run`
and not to any `pre` or `post` script.
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
environment variables that will be available to the script at runtime. If an
"env" command is defined in your package, it will take precedence over the
built-in.
The `env` script is a special built-in command that can be used to list environment variables that will be available to the script at runtime.
If an "env" command is defined in your package, it will take precedence over the built-in.
In addition to the shell's pre-existing `PATH`, `npm run` adds
`node_modules/.bin` to the `PATH` provided to scripts. Any binaries
provided by locally-installed dependencies can be used without the
`node_modules/.bin` prefix. For example, if there is a `devDependency` on
`tap` in your package, you should write:
In addition to the shell's pre-existing `PATH`, `npm run` adds `node_modules/.bin` to the `PATH` provided to scripts.
Any binaries provided by locally-installed dependencies can be used without the `node_modules/.bin` prefix.
For example, if there is a `devDependency` on `tap` in your package, you should write:
```bash
"scripts": {"test": "tap test/*.js"}
@ -55,33 +49,22 @@ instead of
"scripts": {"test": "node_modules/.bin/tap test/*.js"}
```
The actual shell your script is run within is platform dependent. By default,
on Unix-like systems it is the `/bin/sh` command, on Windows it is
`cmd.exe`.
The actual shell your script is run within is platform dependent.
By default, on Unix-like systems it is the `/bin/sh` command, on Windows it is `cmd.exe`.
The actual shell referred to by `/bin/sh` also depends on the system.
You can customize the shell with the
[`script-shell` config](/using-npm/config#script-shell).
You can customize the shell with the [`script-shell` config](/using-npm/config#script-shell).
Scripts are run from the root of the package folder, regardless of what the
current working directory is when `npm run` is called. If you want your
script to use different behavior based on what subdirectory you're in, you
can use the `INIT_CWD` environment variable, which holds the full path you
were in when you ran `npm run`.
Scripts are run from the root of the package folder, regardless of what the current working directory is when `npm run` is called.
If you want your script to use different behavior based on what subdirectory you're in, you can use the `INIT_CWD` environment variable, which holds the full path you were in when you ran `npm run`.
`npm run` sets the `NODE` environment variable to the `node` executable
with which `npm` is executed.
`npm run` sets the `NODE` environment variable to the `node` executable with which `npm` is executed.
If you try to run a script without having a `node_modules` directory and it
fails, you will be given a warning to run `npm install`, just in case you've
forgotten.
If you try to run a script without having a `node_modules` directory and it fails, you will be given a warning to run `npm install`, just in case you've forgotten.
### Workspaces support
You may use the [`workspace`](/using-npm/config#workspace) or
[`workspaces`](/using-npm/config#workspaces) configs in order to run an
arbitrary command from a package's `"scripts"` object in the context of the
specified workspaces. If no `"command"` is provided, it will list the available
scripts for each of these configured workspaces.
You may use the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) configs in order to run an arbitrary command from a package's `"scripts"` object in the context of the specified workspaces.
If no `"command"` is provided, it will list the available scripts for each of these configured workspaces.
Given a project with configured workspaces, e.g:
@ -97,8 +80,8 @@ Given a project with configured workspaces, e.g:
`-- package.json
```
Assuming the workspace configuration is properly set up at the root level
`package.json` file. e.g:
Assuming the workspace configuration is properly set up at the root level `package.json` file.
e.g:
```
{
@ -106,9 +89,7 @@ Assuming the workspace configuration is properly set up at the root level
}
```
And that each of the configured workspaces has a configured `test` script,
we can run tests in all of them using the
[`workspaces` config](/using-npm/config#workspaces):
And that each of the configured workspaces has a configured `test` script, we can run tests in all of them using the [`workspaces` config](/using-npm/config#workspaces):
```
npm test --workspaces
@ -116,24 +97,20 @@ npm test --workspaces
#### Filtering workspaces
It's also possible to run a script in a single workspace using the `workspace`
config along with a name or directory path:
It's also possible to run a script in a single workspace using the `workspace` config along with a name or directory path:
```
npm test --workspace=a
```
The `workspace` config can also be specified multiple times in order to run a
specific script in the context of multiple workspaces. When defining values for
the `workspace` config in the command line, it also possible to use `-w` as a
shorthand, e.g:
The `workspace` config can also be specified multiple times in order to run a specific script in the context of multiple workspaces.
When defining values for the `workspace` config in the command line, it also possible to use `-w` as a shorthand, e.g:
```
npm test -w a -w b
```
This last command will run `test` in both `./packages/a` and `./packages/b`
packages.
This last command will run `test` in both `./packages/a` and `./packages/b` packages.
### Configuration
@ -142,9 +119,9 @@ packages.
* 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.
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:
@ -153,9 +130,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -167,13 +144,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -184,9 +162,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -195,12 +174,12 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
If true, npm will not exit with an error code when `run` 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` 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.
This value is not exported to the environment for child processes.
@ -211,25 +190,26 @@ This value is not exported to the environment for child processes.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -238,8 +218,8 @@ but can be useful for debugging.
* 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 <package-spec>` commands.
The shell to use for scripts run with the `npm exec`, `npm run` and
`npm init <package-spec>` commands.

63
deps/npm/docs/content/commands/npm-sbom.md vendored
View File

@ -12,9 +12,8 @@ npm sbom
### Description
The `npm sbom` command generates a Software Bill of Materials (SBOM) listing the
dependencies for the current project. SBOMs can be generated in either
[SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format.
The `npm sbom` command generates a Software Bill of Materials (SBOM) listing the dependencies for the current project.
SBOMs can be generated in either [SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format.
### Example CycloneDX SBOM
@ -208,17 +207,16 @@ dependencies for the current project. SBOMs can be generated in either
### Package lock only mode
If package-lock-only is enabled, only the information in the package
lock (or shrinkwrap) is loaded. This means that information from the
package.json files of your dependencies will not be included in the
result set (e.g. description, homepage, engines).
If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.
This means that information from the package.json files of your dependencies will not be included in the result set (e.g.
description, homepage, engines).
### Configuration
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -227,11 +225,12 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
@ -240,14 +239,15 @@ variable will be set to `'production'` for all lifecycle scripts.
* Default: false
* Type: Boolean
If set to true, the current operation will only use the `package-lock.json`,
ignoring `node_modules`.
If set to true, the current operation will only use the
`package-lock.json`, ignoring `node_modules`.
For `update` this means only the `package-lock.json` will be updated,
instead of checking `node_modules` and downloading dependencies.
For `list` this means the output will be based on the tree described by the
`package-lock.json`, rather than the contents of `node_modules`.
For `list` this means the output will be based on the tree described
by the `package-lock.json`, rather than the contents of
`node_modules`.
@ -265,9 +265,9 @@ SBOM format to use when generating SBOMs.
* Default: "library"
* Type: "library", "application", or "framework"
The type of package described by the generated SBOM. For SPDX, this is the
value for the `primaryPackagePurpose` field. For CycloneDX, this is the
value for the `type` field.
The type of package described by the generated SBOM. For SPDX, this
is the value for the `primaryPackagePurpose` field. For CycloneDX,
this is the value for the `type` field.
@ -276,9 +276,9 @@ value for the `type` field.
* 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.
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:
@ -287,9 +287,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -301,13 +301,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
## See Also

62
deps/npm/docs/content/commands/npm-search.md vendored
View File

@ -16,26 +16,20 @@ Note: This command is unaware of workspaces.
### Description
Search the registry for packages matching the search terms. `npm search`
performs a linear, incremental, lexically-ordered search through package
metadata for all files in the registry. If your terminal has color
support, it will further highlight the matches in the results. This can
be disabled with the config item `color`
Search the registry for packages matching the search terms.
`npm search`
performs a linear, incremental, lexically-ordered search through package metadata for all files in the registry.
If your terminal has color support, it will further highlight the matches in the results.
This can be disabled with the config item `color`
Additionally, using the `--searchopts` and `--searchexclude` options
paired with more search terms will include and exclude further patterns.
The main difference between `--searchopts` and the standard search terms
is that the former does not highlight results in the output and you can
use them more fine-grained filtering. Additionally, you can add both of
these to your config to change default search filtering behavior.
Additionally, using the `--searchopts` and `--searchexclude` options paired with more search terms will include and exclude further patterns.
The main difference between `--searchopts` and the standard search terms is that the former does not highlight results in the output and you can use them more fine-grained filtering.
Additionally, you can add both of these to your config to change default search filtering behavior.
Search also allows targeting of maintainers in search results, by prefixing
their npm username with `=`.
Search also allows targeting of maintainers in search results, by prefixing their npm username with `=`.
If a term starts with `/`, then it's interpreted as a regular expression
and supports standard JavaScript RegExp syntax. In this case search will
ignore a trailing `/` . (Note you must escape or quote many regular
expression characters in most shells.)
If a term starts with `/`, then it's interpreted as a regular expression and supports standard JavaScript RegExp syntax.
In this case search will ignore a trailing `/` . (Note you must escape or quote many regular expression characters in most shells.)
### Configuration
@ -46,8 +40,8 @@ expression characters in most shells.)
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -55,11 +49,12 @@ Not supported by all npm commands.
#### `color`
* Default: true unless the NO_COLOR environ is set to something other than '0'
* 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.
@ -68,8 +63,8 @@ true, then only prints color codes for tty file descriptors.
* 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.
@ -87,8 +82,8 @@ Show the description in `npm search`
* Default: 20
* Type: Number
Number of items to limit search results to. Will not apply at all to legacy
searches.
Number of items to limit search results to. Will not apply at all to
legacy searches.
@ -124,8 +119,8 @@ The base URL of the npm registry.
* 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.
@ -134,9 +129,9 @@ look for updates immediately even for fresh package data.
* 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`.
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`.
@ -145,8 +140,9 @@ will be requested from the server. To force full offline mode, use
* Default: false
* Type: Boolean
Force offline mode: no network requests will be done during install. To
allow the CLI to fill in missing cache data, see `--prefer-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`.

9
deps/npm/docs/content/commands/npm-shrinkwrap.md vendored
View File

@ -14,12 +14,9 @@ Note: This command is unaware of workspaces.
### Description
This command repurposes `package-lock.json` into a publishable
`npm-shrinkwrap.json` or simply creates a new one. The file created and
updated by this command will then take precedence over any other existing
or future `package-lock.json` files. For a detailed explanation of the
design and purpose of package locks in npm, see
[package-lock-json](/configuring-npm/package-lock-json).
This command repurposes `package-lock.json` into a publishable `npm-shrinkwrap.json` or simply creates a new one.
The file created and updated by this command will then take precedence over any other existing or future `package-lock.json` files.
For a detailed explanation of the design and purpose of package locks in npm, see [package-lock-json](/configuring-npm/package-lock-json).
### See Also

25
deps/npm/docs/content/commands/npm-star.md vendored
View File

@ -14,10 +14,11 @@ Note: This command is unaware of workspaces.
### Description
"Starring" a package means that you have some interest in it. It's
a vaguely positive way to show that you care.
"Starring" a package means that you have some interest in it.
It's a vaguely positive way to show that you care.
It's a boolean thing. Starring repeatedly has no additional effect.
It's a boolean thing.
Starring repeatedly has no additional effect.
### More
@ -46,12 +47,13 @@ The base URL of the npm registry.
#### `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.
* 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 instead of unicode glyphs.
When set to true, npm uses unicode characters in the tree output.
When false, it uses ascii characters instead of unicode glyphs.
@ -60,11 +62,12 @@ false, it uses ascii characters instead of unicode glyphs.
* 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`.
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.
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.

6
deps/npm/docs/content/commands/npm-stars.md vendored
View File

@ -14,11 +14,9 @@ Note: This command is unaware of workspaces.
### Description
If you have starred a lot of neat things and want to find them again
quickly this command lets you do just that.
If you have starred a lot of neat things and want to find them again quickly this command lets you do just that.
You may also want to see your friend's favorite packages, in this case
you will most certainly enjoy this command.
You may also want to see your friend's favorite packages, in this case you will most certainly enjoy this command.
### Configuration

26
deps/npm/docs/content/commands/npm-start.md vendored
View File

@ -12,18 +12,14 @@ npm start [-- <args>]
### Description
This runs a predefined command specified in the `"start"` property of
a package's `"scripts"` object.
This runs a predefined command specified in the `"start"` property of a package's `"scripts"` object.
If the `"scripts"` object does not define a `"start"` property, npm
will run `node server.js`.
If the `"scripts"` object does not define a `"start"` property, npm will run `node server.js`.
Note that this is different from the default node behavior of running
the file specified in a package's `"main"` attribute when evoking with
`node .`
Note that this is different from the default node behavior of running the file specified in a package's `"main"` attribute when evoking with `node .`
As of [`npm@2.0.0`](https://blog.npmjs.org/post/98131109725/npm-2-0-0), you can
use custom arguments when executing scripts. Refer to [`npm run`](/commands/npm-run) for more details.
As of [`npm@2.0.0`](https://blog.npmjs.org/post/98131109725/npm-2-0-0), you can use custom arguments when executing scripts.
Refer to [`npm run`](/commands/npm-run) for more details.
### Example
@ -54,10 +50,10 @@ npm start
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -66,8 +62,8 @@ run any pre- or post-scripts.
* 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 <package-spec>` commands.
The shell to use for scripts run with the `npm exec`, `npm run` and
`npm init <package-spec>` commands.

18
deps/npm/docs/content/commands/npm-stop.md vendored
View File

@ -12,11 +12,9 @@ npm stop [-- <args>]
### Description
This runs a predefined command specified in the "stop" property of a
package's "scripts" object.
This runs a predefined command specified in the "stop" property of a package's "scripts" object.
Unlike with [npm start](/commands/npm-start), there is no default script
that will run if the `"stop"` property is not defined.
Unlike with [npm start](/commands/npm-start), there is no default script that will run if the `"stop"` property is not defined.
### Example
@ -47,10 +45,10 @@ npm stop
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -59,8 +57,8 @@ run any pre- or post-scripts.
* 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 <package-spec>` commands.
The shell to use for scripts run with the `npm exec`, `npm run` and
`npm init <package-spec>` commands.

62
deps/npm/docs/content/commands/npm-team.md vendored
View File

@ -18,22 +18,18 @@ Note: This command is unaware of workspaces.
### Description
Used to manage teams in organizations, and change team memberships. Does not
handle permissions for packages.
Used to manage teams in organizations, and change team memberships.
Does not handle permissions for packages.
Teams must always be fully qualified with the organization/scope they belong to
when operating on them, separated by a colon (`:`). That is, if you have a
`newteam` team in an `org` organization, you must always refer to that team
as `@org:newteam` in these commands.
Teams must always be fully qualified with the organization/scope they belong to when operating on them, separated by a colon (`:`).
That is, if you have a `newteam` team in an `org` organization, you must always refer to that team as `@org:newteam` in these commands.
If you have two-factor authentication enabled in `auth-and-writes` mode, then
you can provide a code from your authenticator with `[--otp <otpcode>]`.
If you don't include this then you will be taken through a second factor flow based
on your `authtype`.
If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`.
If you don't include this then you will be taken through a second factor flow based on your `authtype`.
* create / destroy:
Create a new team, or destroy an existing one. Note: You cannot remove the
`developers` team, [learn more.](https://docs.npmjs.com/about-developers-team)
Create a new team, or destroy an existing one.
Note: You cannot remove the `developers` team, [learn more.](https://docs.npmjs.com/about-developers-team)
Here's how to create a new team `newteam` under the `org` org:
@ -41,8 +37,7 @@ on your `authtype`.
npm team create @org:newteam
```
You should see a confirming message such as: `+@org:newteam` once the new
team has been created.
You should see a confirming message such as: `+@org:newteam` once the new team has been created.
* add:
Add a user to an existing team.
@ -58,8 +53,7 @@ on your `authtype`.
* rm:
Using `npm team rm` you can also remove users from a team they belong to.
Here's an example removing user `username` from `newteam` team
in `org` organization:
Here's an example removing user `username` from `newteam` team in `org` organization:
```bash
npm team rm @org:newteam username
@ -69,9 +63,8 @@ on your `authtype`.
`username removed from @org:newteam`
* ls:
If performed on an organization name, will return a list of existing teams
under that organization. If performed on a team, it will instead return a list
of all users belonging to that particular team.
If performed on an organization name, will return a list of existing teams under that organization.
If performed on a team, it will instead return a list of all users belonging to that particular team.
Here's an example of how to list all teams from an org named `org`:
@ -87,18 +80,14 @@ on your `authtype`.
### Details
`npm team` always operates directly on the current registry, configurable from
the command line using `--registry=<registry url>`.
`npm team` always operates directly on the current registry, configurable from the command line using `--registry=<registry url>`.
You must be a *team admin* to create teams and manage team membership, under
the given organization. Listing teams and team memberships may be done by
any member of the organization.
You must be a *team admin* to create teams and manage team membership, under the given organization.
Listing teams and team memberships may be done by any member of the organization.
Organization creation and management of team admins and *organization* members
is done through the website, not the npm CLI.
Organization creation and management of team admins and *organization* members is done through the website, not the npm CLI.
To use teams to manage permissions on packages belonging to your organization,
use the `npm access` command to grant or revoke the appropriate permissions.
To use teams to manage permissions on packages belonging to your organization, use the `npm access` command to grant or revoke the appropriate permissions.
### Configuration
@ -116,11 +105,12 @@ The base URL of the npm registry.
* 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`.
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.
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.
@ -129,8 +119,8 @@ password, npm will prompt on the command line for one.
* 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.
@ -141,8 +131,8 @@ Output parseable results from commands that write to standard output. For
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.

15
deps/npm/docs/content/commands/npm-test.md vendored
View File

@ -14,8 +14,7 @@ aliases: tst, t
### Description
This runs a predefined command specified in the `"test"` property of
a package's `"scripts"` object.
This runs a predefined command specified in the `"test"` property of a package's `"scripts"` object.
### Example
@ -44,10 +43,10 @@ npm test
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -56,8 +55,8 @@ run any pre- or post-scripts.
* 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 <package-spec>` commands.
The shell to use for scripts run with the `npm exec`, `npm run` and
`npm init <package-spec>` commands.

46
deps/npm/docs/content/commands/npm-token.md vendored
View File

@ -19,8 +19,8 @@ Note: This command is unaware of workspaces.
This lets you list, create and revoke authentication tokens.
* `npm token list`:
Shows a table of all active authentication tokens. You can request
this as JSON with `--json` or tab-separated values with `--parseable`.
Shows a table of all active authentication tokens.
You can request this as JSON with `--json` or tab-separated values with `--parseable`.
```
Read only token npm_1f… with id 7f3134 created 2017-10-21
@ -33,29 +33,22 @@ Publish token npm_… with id e0cf92 created 2017-10-02
```
* `npm token create [--read-only] [--cidr=<cidr-ranges>]`:
Create a new authentication token. It can be `--read-only`, or accept
a list of
[CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)
ranges with which to limit use of this token. This will prompt you for
your password, and, if you have two-factor authentication enabled, an
otp.
Create a new authentication token.
It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token.
This will prompt you for your password, and, if you have two-factor authentication enabled, an otp.
Currently, the cli can not generate automation tokens. Please refer to
the [docs
website](https://docs.npmjs.com/creating-and-viewing-access-tokens)
for more information on generating automation tokens.
Currently, the cli cannot generate automation tokens.
Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens.
```
Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d
```
* `npm token revoke <token|id>`:
Immediately removes an authentication token from the registry. You
will no longer be able to use it. This can accept both complete
tokens (such as those you get back from `npm token create`, and those
found in your `.npmrc`), and ids as seen in the parseable or json
output of `npm token list`. This will NOT accept the truncated token
found in the normal `npm token list` output.
Immediately removes an authentication token from the registry.
You will no longer be able to use it.
This can accept both complete tokens (such as those you get back from `npm token create`, and those found in your `.npmrc`), and ids as seen in the parseable or json output of `npm token list`.
This will NOT accept the truncated token found in the normal `npm token list` output.
### Configuration
@ -64,8 +57,8 @@ Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d
* 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.
@ -74,8 +67,8 @@ access tokens with the `npm token create` command.
* Default: null
* Type: null or String (can be set multiple times)
This is a list of CIDR address to be used when configuring limited access
tokens with the `npm token create` command.
This is a list of CIDR address to be used when configuring limited
access tokens with the `npm token create` command.
@ -93,11 +86,12 @@ The base URL of the npm registry.
* 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`.
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.
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.

28
deps/npm/docs/content/commands/npm-undeprecate.md vendored
View File

@ -14,11 +14,9 @@ Note: This command is unaware of workspaces.
### Description
This command will update the npm registry entry for a package, removing any
deprecation warnings that currently exist.
This command will update the npm registry entry for a package, removing any deprecation warnings that currently exist.
It works in the same way as [npm deprecate](/commands/npm-deprecate), except
that this command removes deprecation warnings instead of adding them.
It works in the same way as [npm deprecate](/commands/npm-deprecate), except that this command removes deprecation warnings instead of adding them.
### Configuration
@ -36,11 +34,12 @@ The base URL of the npm registry.
* 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`.
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.
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.
@ -49,13 +48,14 @@ password, npm will prompt on the command line for one.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
### See Also

76
deps/npm/docs/content/commands/npm-uninstall.md vendored
View File

@ -14,26 +14,19 @@ aliases: unlink, remove, rm, r, un
### Description
This uninstalls a package, completely removing everything npm installed
on its behalf.
This uninstalls a package, completely removing everything npm installed on its behalf.
It also removes the package from the `dependencies`, `devDependencies`,
`optionalDependencies`, and `peerDependencies` objects in your
`package.json`.
`optionalDependencies`, and `peerDependencies` objects in your `package.json`.
Further, if you have an `npm-shrinkwrap.json` or `package-lock.json`, npm
will update those files as well.
Further, if you have an `npm-shrinkwrap.json` or `package-lock.json`, npm will update those files as well.
`--no-save` will tell npm not to remove the package from your
`package.json`, `npm-shrinkwrap.json`, or `package-lock.json` files.
`--no-save` will tell npm not to remove the package from your `package.json`, `npm-shrinkwrap.json`, or `package-lock.json` files.
`--save` or `-S` will tell npm to remove the package from your
`package.json`, `npm-shrinkwrap.json`, and `package-lock.json` files.
This is the default, but you may need to use this if you have for
instance `save=false` in your `npmrc` file
`--save` or `-S` will tell npm to remove the package from your `package.json`, `npm-shrinkwrap.json`, and `package-lock.json` files.
This is the default, but you may need to use this if you have for instance `save=false` in your `npmrc` file
In global mode (ie, with `-g` or `--global` appended to the command),
it uninstalls the current package context as a global package.
In global mode (ie, with `-g` or `--global` appended to the command), it uninstalls the current package context as a global package.
`--no-save` is ignored in this case.
Scope is optional and follows the usual rules for [`scope`](/using-npm/scope).
@ -44,8 +37,7 @@ Scope is optional and follows the usual rules for [`scope`](/using-npm/scope).
npm uninstall sax
```
`sax` will no longer be in your `package.json`, `npm-shrinkwrap.json`, or
`package-lock.json` files.
`sax` will no longer be in your `package.json`, `npm-shrinkwrap.json`, or `package-lock.json` files.
```bash
npm uninstall lodash --no-save
@ -58,7 +50,8 @@ npm uninstall lodash --no-save
#### `save`
* Default: `true` unless when using `npm update` where it defaults to `false`
* Default: `true` unless when using `npm update` where it defaults to
`false`
* Type: Boolean
Save installed packages to a `package.json` file as dependencies.
@ -75,12 +68,13 @@ Will also prevent writing to `package-lock.json` if set to `false`.
* 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.
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`
@ -91,9 +85,9 @@ folder instead of the current working directory. See
* 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.
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:
@ -102,9 +96,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -116,13 +110,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -133,9 +128,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -144,9 +140,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

82
deps/npm/docs/content/commands/npm-unpublish.md vendored
View File

@ -10,35 +10,25 @@ description: Remove a package from the registry
npm unpublish [<package-spec>]
```
To learn more about how the npm registry treats unpublish, see our
[unpublish policies](https://docs.npmjs.com/policies/unpublish).
To learn more about how the npm registry treats unpublish, see our [unpublish policies](https://docs.npmjs.com/policies/unpublish).
### Warning
Consider using the [`deprecate`](/commands/npm-deprecate) command instead,
if your intent is to encourage users to upgrade, or if you no longer
want to maintain a package.
Consider using the [`deprecate`](/commands/npm-deprecate) command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package.
### Description
This removes a package version from the registry, deleting its entry and
removing the tarball.
This removes a package version from the registry, deleting its entry and removing the tarball.
The npm registry will return an error if you are not [logged
in](/commands/npm-adduser).
The npm registry will return an error if you are not [logged in](/commands/npm-adduser).
If you do not specify a package name at all, the name and version to be
unpublished will be pulled from the project in the current directory.
If you do not specify a package name at all, the name and version to be unpublished will be pulled from the project in the current directory.
If you specify a package name but do not specify a version or if you
remove all of a package's versions then the registry will remove the
root package entry entirely.
If you specify a package name but do not specify a version or if you remove all of a package's versions then the registry will remove the root package entry entirely.
Even if you unpublish a package version, that specific name and version
combination can never be reused. In order to publish the package again,
you must use a new version number. If you unpublish the entire package,
you may not publish any new versions of that package until 24 hours have
passed.
Even if you unpublish a package version, that specific name and version combination can never be reused.
In order to publish the package again, you must use a new version number.
If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.
### Configuration
@ -47,13 +37,14 @@ passed.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -68,14 +59,16 @@ 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 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.
* Allow conflicting peerDependencies to be installed in the root
project.
* Implicitly set `--yes` during `npm init`.
* Allow clobbering existing values in `npm pkg`
* Allow unpublishing of entire packages (not just a single version).
@ -90,9 +83,9 @@ recommended that you do not use this option!
* 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.
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:
@ -101,9 +94,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -115,13 +108,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.

21
deps/npm/docs/content/commands/npm-unstar.md vendored
View File

@ -14,8 +14,7 @@ Note: This command is unaware of workspaces.
### Description
"Unstarring" a package is the opposite of [`npm star`](/commands/npm-star),
it removes an item from your list of favorite packages.
"Unstarring" a package is the opposite of [`npm star`](/commands/npm-star), it removes an item from your list of favorite packages.
### More
@ -42,12 +41,13 @@ The base URL of the npm registry.
#### `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.
* 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 instead of unicode glyphs.
When set to true, npm uses unicode characters in the tree output.
When false, it uses ascii characters instead of unicode glyphs.
@ -56,11 +56,12 @@ false, it uses ascii characters instead of unicode glyphs.
* 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`.
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.
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.

244
deps/npm/docs/content/commands/npm-update.md vendored
View File

@ -14,30 +14,21 @@ aliases: up, upgrade, udpate
### Description
This command will update all the packages listed to the latest version
(specified by the [`tag` config](/using-npm/config#tag)), respecting the semver
constraints of both your package and its dependencies (if they also require the
same package).
This command will update all the packages listed to the latest version (specified by the [`tag` config](/using-npm/config#tag)), respecting the semver constraints of both your package and its dependencies (if they also require the same package).
It will also install missing packages.
If the `-g` flag is specified, this command will update globally installed
packages.
If the `-g` flag is specified, this command will update globally installed packages.
If no package name is specified, all packages in the specified location (global
or local) will be updated.
If no package name is specified, all packages in the specified location (global or local) will be updated.
Note that by default `npm update` will not update the semver values of direct
dependencies in your project `package.json`. If you want to also update
values in `package.json` you can run: `npm update --save` (or add the
`save=true` option to a [configuration file](/configuring-npm/npmrc)
to make that the default behavior).
Note that by default `npm update` will not update the semver values of direct dependencies in your project `package.json`.
If you want to also update values in `package.json` you can run: `npm update --save` (or add the `save=true` option to a [configuration file](/configuring-npm/npmrc) to make that the default behavior).
### Example
For the examples below, assume that the current package is `app` and it depends
on dependencies, `dep1` (`dep2`, .. etc.). The published versions of `dep1`
are:
For the examples below, assume that the current package is `app` and it depends on dependencies, `dep1` (`dep2`, .. etc.).
The published versions of `dep1` are:
```json
{
@ -79,9 +70,9 @@ However, if `app`'s `package.json` contains:
}
```
In this case, running `npm update` will install `dep1@1.1.2`. Even though the
`latest` tag points to `1.2.2`, this version does not satisfy `~1.1.1`, which is
equivalent to `>=1.1.1 <1.2.0`. So the highest-sorting version that satisfies
In this case, running `npm update` will install `dep1@1.1.2`.
Even though the `latest` tag points to `1.2.2`, this version does not satisfy `~1.1.1`, which is equivalent to `>=1.1.1 <1.2.0`.
So the highest-sorting version that satisfies
`~1.1.1` is used, which is `1.1.2`.
#### Caret Dependencies below 1.0.0
@ -104,8 +95,7 @@ If the dependence were on `^0.4.0`:
}
```
Then `npm update` will install `dep1@0.4.1`, because that is the highest-sorting
version that satisfies `^0.4.0` (`>= 0.4.0 <0.5.0`)
Then `npm update` will install `dep1@0.4.1`, because that is the highest-sorting version that satisfies `^0.4.0` (`>= 0.4.0 <0.5.0`)
#### Subdependencies
@ -133,32 +123,26 @@ and `dep2` itself depends on this limited range of `dep1`
}
```
Then `npm update` will install `dep1@1.1.2` because that is the highest
version that `dep2` allows. npm will prioritize having a single version
of `dep1` in your tree rather than two when that single version can
satisfy the semver requirements of multiple dependencies in your tree.
In this case if you really did need your package to use a newer version
you would need to use `npm install`.
Then `npm update` will install `dep1@1.1.2` because that is the highest version that `dep2` allows.
npm will prioritize having a single version of `dep1` in your tree rather than two when that single version can satisfy the semver requirements of multiple dependencies in your tree.
In this case if you really did need your package to use a newer version you would need to use `npm install`.
#### Updating Globally-Installed Packages
`npm update -g` will apply the `update` action to each globally installed
package that is `outdated` -- that is, has a version that is different from
`wanted`.
`npm update -g` will apply the `update` action to each globally installed package that is `outdated` -- that is, has a version that is different from `wanted`.
Note: Globally installed packages are treated as if they are installed with a
caret semver range specified. So if you require to update to `latest` you may
need to run `npm install -g [<pkg>...]`
Note: Globally installed packages are treated as if they are installed with a caret semver range specified.
So if you require to update to `latest` you may need to run `npm install -g [<pkg>...]`
NOTE: If a package has been upgraded to a version newer than `latest`, it will
be _downgraded_.
NOTE: If a package has been upgraded to a version newer than `latest`, it will be _downgraded_.
### Configuration
#### `save`
* Default: `true` unless when using `npm update` where it defaults to `false`
* Default: `true` unless when using `npm update` where it defaults to
`false`
* Type: Boolean
Save installed packages to a `package.json` file as dependencies.
@ -175,12 +159,13 @@ Will also prevent writing to `package-lock.json` if set to `false`.
* 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.
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`
@ -192,11 +177,12 @@ folder instead of the current working directory. See
* Type: "hoisted", "nested", "shallow", or "linked"
Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.
@ -207,10 +193,10 @@ link in place, unhoisted.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=nested`
Instead of hoisting package installs in `node_modules`, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets `--install-strategy=nested`.
Instead of hoisting package installs in `node_modules`, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets `--install-strategy=nested`.
@ -221,15 +207,15 @@ de-duplicating. Sets `--install-strategy=nested`.
* DEPRECATED: This option has been deprecated in favor of
`--install-strategy=shallow`
Only install direct dependencies in the top level `node_modules`, but hoist
on deeper dependencies. Sets `--install-strategy=shallow`.
Only install direct dependencies in the top level `node_modules`, but
hoist on deeper dependencies. Sets `--install-strategy=shallow`.
#### `omit`
* Default: 'dev' if the `NODE_ENV` environment variable is set to
'production', otherwise empty.
'production'; otherwise, empty.
* Type: "dev", "optional", or "peer" (can be set multiple times)
Dependency types to omit from the installation tree on disk.
@ -238,25 +224,29 @@ 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 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.
If the resulting omit list includes `'dev'`, then the `NODE_ENV`
environment variable will be set to `'production'` for all lifecycle
scripts.
#### `include`
* Default:
* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
* Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)
Option that allows for defining which types of dependencies to install.
Option that allows for defining which types of dependencies to
install.
This is the inverse of `--omit=<type>`.
Dependency types specified in `--include` will not be omitted, regardless of
the order in which omit/include are specified on the command-line.
Dependency types specified in `--include` will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.
@ -266,18 +256,19 @@ the order in which omit/include are specified on the command-line.
* 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.
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.
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 an 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.
When such an 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.
@ -286,23 +277,25 @@ this warning is treated as a failure.
* 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.
If set to false, then ignore `package-lock.json` files when
installing. This will also prevent _writing_ `package-lock.json` if
`save` is true.
#### `foreground-scripts`
* Default: `false` unless when using `npm pack` or `npm publish` where it
defaults to `true`
* Default: `false` unless when using `npm pack` or `npm publish` where
it defaults to `true`
* Type: Boolean
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.
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.
@ -313,10 +306,10 @@ but can be useful for debugging.
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` will still
run their intended script if `ignore-scripts` is set, but they will *not*
run any pre- or post-scripts.
Note that commands explicitly intended to run a particular script,
such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm
run` will still run their intended script if `ignore-scripts` is set,
but they will *not* run any pre- or post-scripts.
@ -325,10 +318,10 @@ run any pre- or post-scripts.
* Default: true
* Type: Boolean
When "true" submit audit reports alongside the current npm command 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.
When "true" submit audit reports alongside the current npm command 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.
@ -338,14 +331,14 @@ submitted.
* 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 given date are installed.
If there are no versions available for the current set of dependencies, the
command will error.
versions that were available **on or before** the given date are
installed. If there are no versions available for the current set of
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`.
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`.
@ -357,9 +350,9 @@ will be used. For example, `foo@latest` might install `foo@1.2` even though
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.
@ -369,8 +362,8 @@ systems.
* 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.
acknowledging the number of dependencies looking for funding. See
[`npm fund`](/commands/npm-fund) for details.
@ -379,13 +372,14 @@ fund`](/commands/npm-fund) for details.
* 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`.
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.
Note: This is NOT honored by other network related commands, eg
`dist-tags`, `owner`, etc.
@ -394,9 +388,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
* 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.
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:
@ -405,9 +399,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -419,13 +413,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -436,9 +431,10 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
@ -447,9 +443,9 @@ This value is not exported to the environment for child processes.
* Default: false
* Type: Boolean
When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.
When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.

134
deps/npm/docs/content/commands/npm-version.md vendored
View File

@ -19,8 +19,8 @@ alias: verison
* Default: false
* Type: Boolean
Prevents throwing an error when `npm version` is used to set the new version
to the same value as the current version.
Prevents throwing an error when `npm version` is used to set the new
version to the same value as the current version.
@ -38,8 +38,8 @@ Run git commit hooks when using the `npm version` command.
* Default: true
* Type: Boolean
Tag the commit when using the `npm version` command. Setting this to false
results in no commit being made at all.
Tag the commit when using the `npm version` command. Setting this to
false results in no commit being made at all.
@ -50,8 +50,8 @@ results in no commit being made at all.
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -62,8 +62,8 @@ Not supported by all npm commands.
* 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`.
The "prerelease identifier" to use as a prefix for the "prerelease"
part of a semver. Like the `rc` in `1.2.0-rc.8`.
@ -72,11 +72,11 @@ a semver. Like the `rc` in `1.2.0-rc.8`.
* Default: false
* Type: Boolean
If set to true, then the `npm version` command will tag the version using
`-s` to add a signature.
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.
Note that git requires you to have set up GPG keys in your git
configs for this to work properly.
@ -85,9 +85,9 @@ this to work properly.
* 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.
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:
@ -96,9 +96,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -110,13 +110,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -125,8 +126,9 @@ This value is not exported to the environment for child processes.
* Default: true
* Type: Boolean
If set to true, the npm cli will run an update after operations that may
possibly change the workspaces installed to the `node_modules` folder.
If set to true, the npm cli will run an update after operations that
may possibly change the workspaces installed to the `node_modules`
folder.
@ -137,77 +139,66 @@ possibly change the workspaces installed to the `node_modules` folder.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
### Description
Run this in a package directory to bump the version and write the new data
back to `package.json`, `package-lock.json`, and, if present,
Run this in a package directory to bump the version and write the new data back to `package.json`, `package-lock.json`, and, if present,
`npm-shrinkwrap.json`.
The `newversion` argument should be a valid semver string, a valid second
argument to [semver.inc](https://github.com/npm/node-semver#functions) (one
of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`,
`prerelease`), or `from-git`. In the second case, the existing version will
be incremented by 1 in the specified field. `from-git` will try to read
the latest git tag, and use that as the new npm version.
The `newversion` argument should be a valid semver string, a valid second argument to [semver.inc](https://github.com/npm/node-semver#functions) (one of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`), or `from-git`.
In the second case, the existing version will be incremented by 1 in the specified field.
`from-git` will try to read the latest git tag, and use that as the new npm version.
If run in a git repo, it will also create a version commit and tag. This
behavior is controlled by `git-tag-version` (see below), and can be
disabled on the command line by running `npm --no-git-tag-version version`.
It will fail if the working directory is not clean, unless the `-f` or
`--force` flag is set.
If run in a git repo, it will also create a version commit and tag.
This behavior is controlled by `git-tag-version` (see below), and can be disabled on the command line by running `npm --no-git-tag-version version`.
It will fail if the working directory is not clean, unless the `-f` or `--force` flag is set.
If supplied with `-m` or [`--message` config](/using-npm/config#message) option,
npm will use it as a commit message when creating a version commit. If the
`message` config contains `%s` then that will be replaced with the resulting
version number. For example:
If supplied with `-m` or [`--message` config](/using-npm/config#message) option, npm will use it as a commit message when creating a version commit.
If the `message` config contains `%s` then that will be replaced with the resulting version number.
For example:
```bash
npm version patch -m "Upgrade to %s for reasons"
```
If the [`sign-git-tag` config](/using-npm/config#sign-git-tag) is set, then the
tag will be signed using the `-s` flag to git. Note that you must have a default
GPG key set up in your git config for this to work properly. For example:
If the [`sign-git-tag` config](/using-npm/config#sign-git-tag) is set, then the tag will be signed using the `-s` flag to git.
Note that you must have a default GPG key set up in your git config for this to work properly.
For example:
```bash
$ npm config set sign-git-tag true
$ npm version patch
You need a passphrase to unlock the secret key for
user: "isaacs (http://blog.izs.me/) <i@izs.me>"
You need a passphrase to unlock the secret key for user: "isaacs (http://blog.izs.me/) <i@izs.me>"
2048-bit RSA key, ID 6C481CF6, created 2010-08-31
Enter passphrase:
```
If `preversion`, `version`, or `postversion` are in the `scripts` property
of the package.json, they will be executed as part of running `npm
version`.
If `preversion`, `version`, or `postversion` are in the `scripts` property of the package.json, they will be executed as part of running `npm version`.
The exact order of execution is as follows:
1. Check to make sure the git working directory is clean before we get
started. Your scripts may add files to the commit in future steps.
1. Check to make sure the git working directory is clean before we get started.
Your scripts may add files to the commit in future steps.
This step is skipped if the `--force` flag is set.
2. Run the `preversion` script. These scripts have access to the old
`version` in package.json. A typical use would be running your full
test suite before deploying. Any files you want added to the commit
should be explicitly added using `git add`.
3. Bump `version` in `package.json` as requested (`patch`, `minor`,
`major`, etc).
4. Run the `version` script. These scripts have access to the new `version`
in package.json (so they can incorporate it into file headers in
generated files for example). Again, scripts should explicitly add
generated files to the commit using `git add`.
2. Run the `preversion` script.
These scripts have access to the old `version` in package.json.
A typical use would be running your full test suite before deploying.
Any files you want added to the commit should be explicitly added using `git add`.
3. Bump `version` in `package.json` as requested (`patch`, `minor`, `major`, etc).
4. Run the `version` script.
These scripts have access to the new `version` in package.json (so they can incorporate it into file headers in generated files for example).
Again, scripts should explicitly add generated files to the commit using `git add`.
5. Commit and tag.
6. Run the `postversion` script. Use it to clean up the file system or
automatically push the commit and/or tag.
6. Run the `postversion` script.
Use it to clean up the file system or automatically push the commit and/or tag.
Take the following example:
@ -221,10 +212,9 @@ Take the following example:
}
```
This runs all your tests and proceeds only if they pass. Then runs your
`build` script, and adds everything in the `dist` directory to the commit.
After the commit, it pushes the new commit and tag up to the server, and
deletes the `build/temp` directory.
This runs all your tests and proceeds only if they pass.
Then runs your `build` script, and adds everything in the `dist` directory to the commit.
After the commit, it pushes the new commit and tag up to the server, and deletes the `build/temp` directory.
### See Also

82
deps/npm/docs/content/commands/npm-view.md vendored
View File

@ -33,7 +33,8 @@ npm view ronn@0.3.5 dependencies
```
By default, `npm view` shows data about the current project context (by looking for a `package.json`).
To show field data for the current project use a file path (i.e. `.`):
To show field data for the current project use a file path (i.e.
`.`):
```bash
npm view . dependencies
@ -46,25 +47,22 @@ To view the git repository URL for the latest version of `npm`, you would run th
npm view npm repository.url
```
This makes it easy to view information about a dependency with a bit of
shell scripting. For example, to view all the data about the version of
`opts` that `ronn` depends on, you could write the following:
This makes it easy to view information about a dependency with a bit of shell scripting.
For example, to view all the data about the version of `opts` that `ronn` depends on, you could write the following:
```bash
npm view opts@$(npm view ronn dependencies.opts)
```
For fields that are arrays, requesting a non-numeric field will return
all of the values from the objects in the list. For example, to get all
the contributor email addresses for the `express` package, you would run:
For fields that are arrays, requesting a non-numeric field will return all of the values from the objects in the list.
For example, to get all the contributor email addresses for the `express` package, you would run:
```bash
npm view express contributors.email
```
You may also use numeric indices in square braces to specifically select
an item in an array field. To just get the email address of the first
contributor in the list, you can run:
You may also use numeric indices in square braces to specifically select an item in an array field.
To just get the email address of the first contributor in the list, you can run:
```bash
npm view express contributors[0].email
@ -77,31 +75,28 @@ npm view express time'[4.8.0]'
```
Multiple fields may be specified, and will be printed one after another.
For example, to get all the contributor names and email addresses, you
can do this:
For example, to get all the contributor names and email addresses, you can do this:
```bash
npm view express contributors.name contributors.email
```
"Person" fields are shown as a string if they would be shown as an
object. So, for example, this will show the list of `npm` contributors in
the shortened string format. (See [`package.json`](/configuring-npm/package-json) for more on this.)
"Person" fields are shown as a string if they would be shown as an object.
So, for example, this will show the list of `npm` contributors in the shortened string format.
(See [`package.json`](/configuring-npm/package-json) for more on this.)
```bash
npm view npm contributors
```
If a version range is provided, then data will be printed for every
matching version of the package. This will show which version of `jsdom`
was required by each matching version of `yui3`:
If a version range is provided, then data will be printed for every matching version of the package.
This will show which version of `jsdom` was required by each matching version of `yui3`:
```bash
npm view yui3@'>0.5.4' dependencies.jsdom
```
To show the `connect` package version history, you can do
this:
To show the `connect` package version history, you can do this:
```bash
npm view connect versions
@ -116,8 +111,8 @@ npm view connect versions
Whether or not to output JSON data, rather than the normal output.
* In `npm pkg set` it enables parsing set values with JSON.parse() before
saving them to your `package.json`.
* In `npm pkg set` it enables parsing set values with JSON.parse()
before saving them to your `package.json`.
Not supported by all npm commands.
@ -128,9 +123,9 @@ Not supported by all npm commands.
* 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.
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:
@ -139,9 +134,9 @@ Valid values for the `workspace` config are either:
* Path to a parent workspace directory (will result in selecting all
workspaces within that folder)
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.
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.
@ -153,13 +148,14 @@ This value is not exported to the environment for child processes.
Set to true to run the command in the context of **all** configured
workspaces.
Explicitly setting this to false will cause commands like `install` to
ignore workspaces altogether. When not set explicitly:
Explicitly setting this to false will cause commands like `install`
to ignore workspaces altogether. When not set explicitly:
- Commands that operate on the `node_modules` tree (install, update, etc.)
will link workspaces into the `node_modules` folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
_unless_ one or more workspaces are specified in the `workspace` config.
- Commands that operate on the `node_modules` tree (install, update,
etc.) will link workspaces into the `node_modules` folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, _unless_ one or more workspaces are specified in the
`workspace` config.
This value is not exported to the environment for child processes.
@ -170,25 +166,23 @@ This value is not exported to the environment for child processes.
Include the workspace root when workspaces are enabled for a command.
When false, specifying individual workspaces via the `workspace` config, or
all workspaces via the `workspaces` flag, will cause npm to operate only on
the specified workspaces, and not on the root project.
When false, specifying individual workspaces via the `workspace`
config, or all workspaces via the `workspaces` flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.
This value is not exported to the environment for child processes.
### Output
If only a single string field for a single version is output, then it
will not be colorized or quoted, to enable piping the output to
another command. If the field is an object, it will be output as a JavaScript object literal.
If only a single string field for a single version is output, then it will not be colorized or quoted, to enable piping the output to another command.
If the field is an object, it will be output as a JavaScript object literal.
If the `--json` flag is given, the outputted fields will be JSON.
If the version range matches multiple versions then each printed value
will be prefixed with the version it applies to.
If the version range matches multiple versions then each printed value will be prefixed with the version it applies to.
If multiple fields are requested, then each of them is prefixed with
the field name.
If multiple fields are requested, then each of them is prefixed with the field name.
### See Also

7
deps/npm/docs/content/commands/npm-whoami.md vendored
View File

@ -16,12 +16,9 @@ Note: This command is unaware of workspaces.
Display the npm username of the currently logged-in user.
If logged into a registry that provides token-based authentication, then
connect to the `/-/whoami` registry endpoint to find the username
associated with the token, and print to standard output.
If logged into a registry that provides token-based authentication, then connect to the `/-/whoami` registry endpoint to find the username associated with the token, and print to standard output.
If logged into a registry that uses Basic Auth, then simply print the
`username` portion of the authentication string.
If logged into a registry that uses Basic Auth, then simply print the `username` portion of the authentication string.
### Configuration

129
deps/npm/docs/content/commands/npm.md vendored
View File

@ -14,138 +14,111 @@ Note: This command is unaware of workspaces.
### Version
11.6.1
11.6.2
### Description
npm is the package manager for the Node JavaScript platform. It puts
modules in place so that node can find them, and manages dependency
conflicts intelligently.
npm is the package manager for the Node JavaScript platform.
It puts modules in place so that node can find them, and manages dependency conflicts intelligently.
It is extremely configurable to support a variety of use cases. Most
commonly, you use it to publish, discover, install, and develop node
programs.
It is extremely configurable to support a variety of use cases.
Most commonly, you use it to publish, discover, install, and develop node programs.
Run `npm help` to get a list of available commands.
### Important
npm comes preconfigured to use npm's public registry at
https://registry.npmjs.org by default. Use of the npm public registry is
subject to terms of use available at
https://docs.npmjs.com/policies/terms.
npm comes preconfigured to use npm's public registry at https://registry.npmjs.org by default.
Use of the npm public registry is subject to terms of use available at https://docs.npmjs.com/policies/terms.
You can configure npm to use any compatible registry you like, and even
run your own registry. Use of someone else's registry is governed by
their terms of use.
You can configure npm to use any compatible registry you like, and even run your own registry.
Use of someone else's registry is governed by their terms of use.
### Introduction
You probably got npm because you want to install stuff.
The very first thing you will most likely want to run in any node
program is `npm install` to install its dependencies.
The very first thing you will most likely want to run in any node program is `npm install` to install its dependencies.
You can also run `npm install blerg` to install the latest version of
"blerg". Check out [`npm install`](/commands/npm-install) for more
info. It can do a lot of stuff.
You can also run `npm install blerg` to install the latest version of "blerg". Check out [`npm install`](/commands/npm-install) for more info.
It can do a lot of stuff.
Use the `npm search` command to show everything that's available in the
public registry. Use `npm ls` to show everything you've installed.
Use the `npm search` command to show everything that's available in the public registry.
Use `npm ls` to show everything you've installed.
### Dependencies
If a package lists a dependency using a git URL, npm will install that
dependency using the [`git`](https://github.com/git-guides/install-git)
command and will generate an error if it is not installed.
If a package lists a dependency using a git URL, npm will install that dependency using the [`git`](https://github.com/git-guides/install-git) command and will generate an error if it is not installed.
If one of the packages npm tries to install is a native node module and
requires compiling of C++ Code, npm will use
[node-gyp](https://github.com/nodejs/node-gyp) for that task.
For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp)
needs Python, make and a buildchain like GCC. On Windows,
Python and Microsoft Visual Studio C++ are needed. For more information
visit [the node-gyp repository](https://github.com/nodejs/node-gyp) and
the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki).
If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use [node-gyp](https://github.com/nodejs/node-gyp) for that task.
For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp) needs Python, make and a buildchain like GCC. On Windows, Python and Microsoft Visual Studio C++ are needed.
For more information visit [the node-gyp repository](https://github.com/nodejs/node-gyp) and the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki).
### Directories
See [`folders`](/configuring-npm/folders) to learn about where npm puts
stuff.
See [`folders`](/configuring-npm/folders) to learn about where npm puts stuff.
In particular, npm has two modes of operation:
* local mode:
npm installs packages into the current project directory, which
defaults to the current working directory. Packages install to
`./node_modules`, and bins to `./node_modules/.bin`.
npm installs packages into the current project directory, which defaults to the current working directory.
Packages install to `./node_modules`, and bins to `./node_modules/.bin`.
* global mode:
npm installs packages into the install prefix at
`$npm_config_prefix/lib/node_modules` and bins to
`$npm_config_prefix/bin`.
npm installs packages into the install prefix at `$npm_config_prefix/lib/node_modules` and bins to `$npm_config_prefix/bin`.
Local mode is the default. Use `-g` or `--global` on any command to
run in global mode instead.
Local mode is the default.
Use `-g` or `--global` on any command to run in global mode instead.
### Developer Usage
If you're using npm to develop and publish your code, check out the
following help topics:
If you're using npm to develop and publish your code, check out the following help topics:
* json:
Make a package.json file. See
[`package.json`](/configuring-npm/package-json).
Make a package.json file.
See [`package.json`](/configuring-npm/package-json).
* link:
Links your current working code into Node's path, so that you don't
have to reinstall every time you make a change. Use [`npm
link`](/commands/npm-link) to do this.
Links your current working code into Node's path, so that you don't have to reinstall every time you make a change.
Use [`npm link`](/commands/npm-link) to do this.
* install:
It's a good idea to install things if you don't need the symbolic
link. Especially, installing other peoples code from the registry is
done via [`npm install`](/commands/npm-install)
It's a good idea to install things if you don't need the symbolic link.
Especially, installing other peoples code from the registry is done via [`npm install`](/commands/npm-install)
* adduser:
Create an account or log in. When you do this, npm will store
credentials in the user config file.
Create an account or log in.
When you do this, npm will store credentials in the user config file.
* publish:
Use the [`npm publish`](/commands/npm-publish) command to upload your
code to the registry.
Use the [`npm publish`](/commands/npm-publish) command to upload your code to the registry.
#### Configuration
npm is extremely configurable. It reads its configuration options from
5 places.
npm is extremely configurable.
It reads its configuration options from 5 places.
* Command line switches:
Set a config with `--key val`. All keys take a value, even if they
are booleans (the config parser doesn't know what the options are at
the time of parsing). If you do not provide a value (`--key`) then
the option is set to boolean `true`.
Set a config with `--key val`.
All keys take a value, even if they are booleans (the config parser doesn't know what the options are at the time of parsing).
If you do not provide a value (`--key`) then the option is set to boolean `true`.
* Environment Variables:
Set any config by prefixing the name in an environment variable with
`npm_config_`. For example, `export npm_config_key=val`.
Set any config by prefixing the name in an environment variable with `npm_config_`.
For example, `export npm_config_key=val`.
* User Configs:
The file at `$HOME/.npmrc` is an ini-formatted list of configs. If
present, it is parsed. If the `userconfig` option is set in the cli
or env, that file will be used instead.
The file at `$HOME/.npmrc` is an ini-formatted list of configs.
If present, it is parsed.
If the `userconfig` option is set in the cli or env, that file will be used instead.
* Global Configs:
The file found at `./etc/npmrc` (relative to the global prefix will be
parsed if it is found. See [`npm prefix`](/commands/npm-prefix) for
more info on the global prefix. If the `globalconfig` option is set
in the cli, env, or user config, then that file is parsed instead.
The file found at `./etc/npmrc` (relative to the global prefix will be parsed if it is found.
See [`npm prefix`](/commands/npm-prefix) for more info on the global prefix.
If the `globalconfig` option is set in the cli, env, or user config, then that file is parsed instead.
* Defaults:
npm's default configuration options are defined in
`lib/utils/config/definitions.js`. These must not be changed.
npm's default configuration options are defined in `lib/utils/config/definitions.js`.
These must not be changed.
See [`config`](/using-npm/config) for much much more information.
See [`config`](/using-npm/config) for much, much, more information.
### Contributions
Patches welcome!
If you would like to help, but don't know what to work on, read the
[contributing
guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and
check the issues list.
If you would like to help, but don't know what to work on, read the [contributing guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and check the issues list.
### Bugs

105
deps/npm/docs/content/commands/npx.md vendored
View File

@ -15,52 +15,32 @@ npx --package=foo -c '<cmd> [args...]'
### Description
This command allows you to run an arbitrary command from an npm package
(either one installed locally, or fetched remotely), in a similar context
as running it via `npm run`.
This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via `npm run`.
Whatever packages are specified by the `--package` option will be
provided in the `PATH` of the executed command, along with any locally
installed package executables. The `--package` option may be
specified multiple times, to execute the supplied command in an environment
where all specified packages are available.
Whatever packages are specified by the `--package` option will be provided in the `PATH` of the executed command, along with any locally installed package executables.
The `--package` option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.
If any requested packages are not present in the local project
dependencies, then they are installed to a folder in the npm cache, which
is added to the `PATH` environment variable in the executed process. A
prompt is printed (which can be suppressed by providing either `--yes` or
`--no`).
If any requested packages are not present in the local project dependencies, then they are installed to a folder in the npm cache, which is added to the `PATH` environment variable in the executed process.
A prompt is printed (which can be suppressed by providing either `--yes` or `--no`).
Package names provided without a specifier will be matched with whatever
version exists in the local project. Package names with a specifier will
only be considered a match if they have the exact same name and version as
the local dependency.
Package names provided without a specifier will be matched with whatever version exists in the local project.
Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.
If no `-c` or `--call` option is provided, then the positional arguments
are used to generate the command string. If no `--package` options
are provided, then npm will attempt to determine the executable name from
the package specifier provided as the first positional argument according
to the following heuristic:
If no `-c` or `--call` option is provided, then the positional arguments are used to generate the command string.
If no `--package` options are provided, then npm will attempt to determine the executable name from the package specifier provided as the first positional argument according to the following heuristic:
- If the package has a single entry in its `bin` field in `package.json`,
or if all entries are aliases of the same command, then that command
will be used.
- If the package has multiple `bin` entries, and one of them matches the
unscoped portion of the `name` field, then that command will be used.
- If this does not result in exactly one option (either because there are
no bin entries, or none of them match the `name` of the package), then
- If the package has a single entry in its `bin` field in `package.json`, or if all entries are aliases of the same command, then that command will be used.
- If the package has multiple `bin` entries, and one of them matches the unscoped portion of the `name` field, then that command will be used.
- If this does not result in exactly one option (either because there are no bin entries, or none of them match the `name` of the package), then
`npm exec` exits with an error.
To run a binary _other than_ the named binary, specify one or more
`--package` options, which will prevent npm from inferring the package from
the first command argument.
`--package` options, which will prevent npm from inferring the package from the first command argument.
### `npx` vs `npm exec`
When run via the `npx` binary, all flags and options *must* be set prior to
any positional arguments. When run via `npm exec`, a double-hyphen `--`
flag can be used to suppress npm's parsing of switches and options that
should be sent to the executed command.
When run via the `npx` binary, all flags and options *must* be set prior to any positional arguments.
When run via `npm exec`, a double-hyphen `--` flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command.
For example:
@ -68,34 +48,30 @@ For example:
$ npx foo@latest bar --package=@npmcli/foo
```
In this case, npm will resolve the `foo` package name, and run the
following command:
In this case, npm will resolve the `foo` package name, and run the following command:
```
$ foo bar --package=@npmcli/foo
```
Since the `--package` option comes _after_ the positional arguments, it is
treated as an argument to the executed command.
Since the `--package` option comes _after_ the positional arguments, it is treated as an argument to the executed command.
In contrast, due to npm's argument parsing logic, running this command is
different:
In contrast, due to npm's argument parsing logic, running this command is different:
```
$ npm exec foo@latest bar --package=@npmcli/foo
```
In this case, npm will parse the `--package` option first, resolving the
`@npmcli/foo` package. Then, it will execute the following command in that
context:
`@npmcli/foo` package.
Then, it will execute the following command in that context:
```
$ foo@latest bar
```
The double-hyphen character is recommended to explicitly tell npm to stop
parsing command line options and switches. The following command would
thus be equivalent to the `npx` command above:
The double-hyphen character is recommended to explicitly tell npm to stop parsing command line options and switches.
The following command would thus be equivalent to the `npx` command above:
```
$ npm exec -- foo@latest bar --package=@npmcli/foo
@ -103,16 +79,14 @@ $ npm exec -- foo@latest bar --package=@npmcli/foo
### Examples
Run the version of `tap` in the local dependencies, with the provided
arguments:
Run the version of `tap` in the local dependencies, with the provided arguments:
```
$ npm exec -- tap --bail test/foo.js
$ npx tap --bail test/foo.js
```
Run a command _other than_ the command whose name matches the package name
by specifying a `--package` option:
Run a command _other than_ the command whose name matches the package name by specifying a `--package` option:
```
$ npm exec --package=foo -- bar --bar-argument
@ -129,32 +103,27 @@ $ npx -c 'eslint && say "hooray, lint passed"'
### Compatibility with Older npx Versions
The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx`
package deprecated at that time. `npx` uses the `npm exec`
command instead of a separate argument parser and install process, with
some affordances to maintain backwards compatibility with the arguments it
accepted in previous versions.
The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` package deprecated at that time.
`npx` uses the `npm exec` command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions.
This resulted in some shifts in its functionality:
- Any `npm` config value may be provided.
- To prevent security and user-experience problems from mistyping package
names, `npx` prompts before installing anything. Suppress this
prompt with the `-y` or `--yes` option.
- To prevent security and user-experience problems from mistyping package names, `npx` prompts before installing anything.
Suppress this prompt with the `-y` or `--yes` option.
- The `--no-install` option is deprecated, and will be converted to `--no`.
- Shell fallback functionality is removed, as it is not advisable.
- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand
for `--package` in npx. This is maintained, but only for the `npx`
executable.
- The `--ignore-existing` option is removed. Locally installed bins are
always present in the executed process `PATH`.
- The `--npm` option is removed. `npx` will always use the `npm` it ships
with.
- The `--node-arg` and `-n` options have been removed. Use [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) instead: e.g.,
- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand for `--package` in npx.
This is maintained, but only for the `npx` executable.
- The `--ignore-existing` option is removed.
Locally installed bins are always present in the executed process `PATH`.
- The `--npm` option is removed.
`npx` will always use the `npm` it ships with.
- The `--node-arg` and `-n` options have been removed.
Use [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) instead: e.g.,
`NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true`
- The `--always-spawn` option is redundant, and thus removed.
- The `--shell` option is replaced with `--script-shell`, but maintained
in the `npx` executable for backwards compatibility.
- The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility.
### See Also

144
deps/npm/docs/content/configuring-npm/folders.md vendored
View File

@ -6,60 +6,49 @@ description: Folder Structures Used by npm
### Description
npm puts various things on your computer. That's its job.
npm puts various things on your computer.
That's its job.
This document will tell you what it puts where.
#### tl;dr
* Local install (default): puts stuff in `./node_modules` of the current
package root.
* Global install (with `-g`): puts stuff in /usr/local or wherever node
is installed.
* Local install (default): puts stuff in `./node_modules` of the current package root.
* Global install (with `-g`): puts stuff in /usr/local or wherever node is installed.
* Install it **locally** if you're going to `require()` it.
* Install it **globally** if you're going to run it on the command line.
* If you need both, then install it in both places, or use `npm link`.
#### prefix Configuration
The [`prefix` config](/using-npm/config#prefix) defaults to the location where
node is installed. On most systems, this is `/usr/local`. On Windows, it's
`%AppData%\npm`. On Unix systems, it's one level up, since node is typically
installed at `{prefix}/bin/node` rather than `{prefix}/node.exe`.
The [`prefix` config](/using-npm/config#prefix) defaults to the location where node is installed.
On most systems, this is `/usr/local`.
On Windows, it's `%AppData%\npm`.
On Unix systems, it's one level up, since node is typically installed at `{prefix}/bin/node` rather than `{prefix}/node.exe`.
When the `global` flag is set, npm installs things into this prefix.
When it is not set, it uses the root of the current package, or the
current working directory if not in a package already.
When it is not set, it uses the root of the current package, or the current working directory if not in a package already.
#### Node Modules
Packages are dropped into the `node_modules` folder under the `prefix`.
When installing locally, this means that you can
`require("packagename")` to load its main module, or
`require("packagename/lib/path/to/sub/module")` to load other modules.
When installing locally, this means that you can `require("packagename")` to load its main module, or `require("packagename/lib/path/to/sub/module")` to load other modules.
Global installs on Unix systems go to `{prefix}/lib/node_modules`.
Global installs on Windows go to `{prefix}/node_modules` (that is, no
`lib` folder.)
Global installs on Windows go to `{prefix}/node_modules` (that is, no `lib` folder.)
Scoped packages are installed the same way, except they are grouped together
in a sub-folder of the relevant `node_modules` folder with the name of that
scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place
the package in `{prefix}/node_modules/@myorg/package`. See
[`scope`](/using-npm/scope) for more details.
Scoped packages are installed the same way, except they are grouped together in a sub-folder of the relevant `node_modules` folder with the name of that scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place the package in `{prefix}/node_modules/@myorg/package`.
See [`scope`](/using-npm/scope) for more details.
If you wish to `require()` a package, then install it locally.
#### Executables
When in global mode, executables are linked into `{prefix}/bin` on Unix,
or directly into `{prefix}` on Windows. Ensure that path is in your
terminal's `PATH` environment to run them.
When in global mode, executables are linked into `{prefix}/bin` on Unix, or directly into `{prefix}` on Windows.
Ensure that path is in your terminal's `PATH` environment to run them.
When in local mode, executables are linked into
`./node_modules/.bin` so that they can be made available to scripts run
through npm. (For example, so that a test runner will be in the path
when you run `npm test`.)
When in local mode, executables are linked into `./node_modules/.bin` so that they can be made available to scripts run through npm.
(For example, so that a test runner will be in the path when you run `npm test`.)
#### Man Pages
@ -71,67 +60,48 @@ Man pages are not installed on Windows systems.
#### Cache
See [`npm cache`](/commands/npm-cache). Cache files are stored in `~/.npm` on Posix, or
`%LocalAppData%/npm-cache` on Windows.
See [`npm cache`](/commands/npm-cache).
Cache files are stored in `~/.npm` on Posix, or `%LocalAppData%/npm-cache` on Windows.
This is controlled by the [`cache` config](/using-npm/config#cache) param.
### More Information
When installing locally, npm first tries to find an appropriate
`prefix` folder. This is so that `npm install foo@1.2.3` will install
to the sensible root of your package, even if you happen to have `cd`ed
into some other folder.
When installing locally, npm first tries to find an appropriate `prefix` folder.
This is so that `npm install foo@1.2.3` will install to the sensible root of your package, even if you happen to have `cd`ed into some other folder.
Starting at the $PWD, npm will walk up the folder tree checking for a
folder that contains either a `package.json` file, or a `node_modules`
folder. If such a thing is found, then that is treated as the effective
"current directory" for the purpose of running npm commands. (This
behavior is inspired by and similar to git's .git-folder seeking
logic when running git commands in a working dir.)
Starting at the $PWD, npm will walk up the folder tree checking for a folder that contains either a `package.json` file, or a `node_modules` folder.
If such a thing is found, then that is treated as the effective "current directory" for the purpose of running npm commands.
(This behavior is inspired by and similar to git's .git-folder seeking logic when running git commands in a working dir.)
If no package root is found, then the current folder is used.
When you run `npm install foo@1.2.3`, then the package is loaded into
the cache, and then unpacked into `./node_modules/foo`. Then, any of
foo's dependencies are similarly unpacked into
`./node_modules/foo/node_modules/...`.
When you run `npm install foo@1.2.3`, then the package is loaded into the cache, and then unpacked into `./node_modules/foo`.
Then, any of foo's dependencies are similarly unpacked into `./node_modules/foo/node_modules/...`.
Any bin files are symlinked to `./node_modules/.bin/`, so that they may
be found by npm scripts when necessary.
Any bin files are symlinked to `./node_modules/.bin/`, so that they may be found by npm scripts when necessary.
#### Global Installation
If the [`global` config](/using-npm/config#global) is set to true, then npm will
install packages "globally".
If the [`global` config](/using-npm/config#global) is set to true, then npm will install packages "globally".
For global installation, packages are installed roughly the same way,
but using the folders described above.
For global installation, packages are installed roughly the same way, but using the folders described above.
#### Cycles, Conflicts, and Folder Parsimony
Cycles are handled using the property of node's module system that it
walks up the directories looking for `node_modules` folders. So, at every
stage, if a package is already installed in an ancestor `node_modules`
folder, then it is not installed at the current location.
Cycles are handled using the property of node's module system that it walks up the directories looking for `node_modules` folders.
So, at every stage, if a package is already installed in an ancestor `node_modules` folder, then it is not installed at the current location.
Consider the case above, where `foo -> bar -> baz`. Imagine if, in
addition to that, baz depended on bar, so you'd have:
`foo -> bar -> baz -> bar -> baz ...`. However, since the folder
structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to
put another copy of bar into `.../baz/node_modules`, since when baz calls
`require("bar")`, it will get the copy that is installed in
`foo/node_modules/bar`.
Consider the case above, where `foo -> bar -> baz`.
Imagine if, in addition to that, baz depended on bar, so you'd have:
`foo -> bar -> baz -> bar -> baz ...`.
However, since the folder structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to put another copy of bar into `.../baz/node_modules`, since when baz calls `require("bar")`, it will get the copy that is installed in `foo/node_modules/bar`.
This shortcut is only used if the exact same
version would be installed in multiple nested `node_modules` folders. It
is still possible to have `a/node_modules/b/node_modules/a` if the two
"a" packages are different versions. However, without repeating the
exact same package multiple times, an infinite regress will always be
prevented.
This shortcut is only used if the exact same version would be installed in multiple nested `node_modules` folders.
It is still possible to have `a/node_modules/b/node_modules/a` if the two "a" packages are different versions.
However, without repeating the exact same package multiple times, an infinite regress will always be prevented.
Another optimization can be made by installing dependencies at the
highest level possible, below the localized "target" folder (hoisting).
Another optimization can be made by installing dependencies at the highest level possible, below the localized "target" folder (hoisting).
Since version 3, npm hoists dependencies by default.
#### Example
@ -152,8 +122,7 @@ foo
`-- bar
```
In this case, we might expect a folder structure like this
(with all dependencies hoisted to the highest level possible):
In this case, we might expect a folder structure like this (with all dependencies hoisted to the highest level possible):
```bash
foo
@ -167,36 +136,29 @@ foo
+-- quux (3.2.0) <---[E]
```
Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are
installed in foo's `node_modules` folder.
Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are installed in foo's `node_modules` folder.
Even though the latest copy of blerg is 1.3.7, foo has a specific
dependency on version 1.2.5. So, that gets installed at [A]. Since the
parent installation of blerg satisfies bar's dependency on `blerg@1.x`,
it does not install another copy under [B].
Even though the latest copy of blerg is 1.3.7, foo has a specific dependency on version 1.2.5.
So, that gets installed at [A].
Since the parent installation of blerg satisfies bar's dependency on `blerg@1.x`, it does not install another copy under [B].
Bar [B] also has dependencies on baz and asdf. Because it depends on `baz@2.x`, it cannot
re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D],
and must install its own copy [C]. In order to minimize duplication, npm hoists
dependencies to the top level by default, so asdf is installed under [A].
Bar [B] also has dependencies on baz and asdf.
Because it depends on `baz@2.x`, it cannot re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], and must install its own copy [C].
In order to minimize duplication, npm hoists dependencies to the top level by default, so asdf is installed under [A].
Underneath bar, the `baz -> quux -> bar` dependency creates a cycle.
However, because bar is already in quux's ancestry [B], it does not
unpack another copy of bar into that folder. Likewise, quux's [E]
folder tree is empty, because its dependency on bar is satisfied
by the parent folder copy installed at [B].
However, because bar is already in quux's ancestry [B], it does not unpack another copy of bar into that folder.
Likewise, quux's [E] folder tree is empty, because its dependency on bar is satisfied by the parent folder copy installed at [B].
For a graphical breakdown of what is installed where, use `npm ls`.
#### Publishing
Upon publishing, npm will look in the `node_modules` folder. If any of
the items there are not in the `bundleDependencies` array, then they will
not be included in the package tarball.
Upon publishing, npm will look in the `node_modules` folder.
If any of the items there are not in the `bundleDependencies` array, then they will not be included in the package tarball.
This allows a package maintainer to install all of their dependencies
(and dev dependencies) locally, but only re-publish those items that
cannot be found elsewhere. See [`package.json`](/configuring-npm/package-json) for more information.
This allows a package maintainer to install all of their dependencies (and dev dependencies) locally, but only re-publish those items that cannot be found elsewhere.
See [`package.json`](/configuring-npm/package-json) for more information.
### See also

54
deps/npm/docs/content/configuring-npm/install.md vendored
View File

@ -6,27 +6,19 @@ description: Download and install node and npm
### Description
To publish and install packages to and from the public npm registry, you
must install Node.js and the npm command line interface using either a Node
version manager or a Node installer. **We strongly recommend using a Node
version manager to install Node.js and npm.** We do not recommend using a
Node installer, since the Node installation process installs npm in a
directory with local permissions and can cause permissions errors when you
run npm packages globally.
To publish and install packages to and from the public npm registry, you must install Node.js and the npm command line interface using either a Node version manager or a Node installer.
**We strongly recommend using a Node version manager to install Node.js and npm.** We do not recommend using a
Node installer, since the Node installation process installs npm in a directory with local permissions and can cause permissions errors when you run npm packages globally.
### Overview
- [Checking your version of npm and
Node.js](#checking-your-version-of-npm-and-nodejs)
- [Using a Node version manager to install Node.js and
npm](#using-a-node-version-manager-to-install-nodejs-and-npm)
- [Using a Node installer to install Node.js and
npm](#using-a-node-installer-to-install-nodejs-and-npm)
- [Checking your version of npm and Node.js](#checking-your-version-of-npm-and-nodejs)
- [Using a Node version manager to install Node.js and npm](#using-a-node-version-manager-to-install-nodejs-and-npm)
- [Using a Node installer to install Node.js and npm](#using-a-node-installer-to-install-nodejs-and-npm)
### Checking your version of npm and Node.js
To see if you already have Node.js and npm installed and check the
installed version, run the following commands:
To see if you already have Node.js and npm installed and check the installed version, run the following commands:
```
node -v
@ -35,37 +27,27 @@ npm -v
### Using a Node version manager to install Node.js and npm
Node version managers allow you to install and switch between multiple
versions of Node.js and npm on your system so you can test your
applications on multiple versions of npm to ensure they work for users on
different versions. You can
[search for them on GitHub](https://github.com/search?q=node+version+manager+archived%3Afalse&type=repositories&ref=advsearch).
Node version managers allow you to install and switch between multiple versions of Node.js and npm on your system so you can test your applications on multiple versions of npm to ensure they work for users on different versions.
You can [search for them on GitHub](https://github.com/search?q=node+version+manager+archived%3Afalse&type=repositories&ref=advsearch).
### Using a Node installer to install Node.js and npm
If you are unable to use a Node version manager, you can use a Node
installer to install both Node.js and npm on your system.
If you are unable to use a Node version manager, you can use a Node installer to install both Node.js and npm on your system.
* [Node.js installer](https://nodejs.org/en/download/)
* [NodeSource installer](https://github.com/nodesource/distributions). If
you use Linux, we recommend that you use a NodeSource installer.
* [NodeSource installer](https://github.com/nodesource/distributions).
If you use Linux, we recommend that you use a NodeSource installer.
#### macOS or Windows Node installers
If you're using macOS or Windows, use one of the installers from the
[Node.js download page](https://nodejs.org/en/download/). Be sure to
install the version labeled **LTS**. Other versions have not yet been
tested with npm.
If you're using macOS or Windows, use one of the installers from the [Node.js download page](https://nodejs.org/en/download/).
Be sure to install the version labeled **LTS**. Other versions have not yet been tested with npm.
#### Linux or other operating systems Node installers
If you're using Linux or another operating system, use one of the following
installers:
If you're using Linux or another operating system, use one of the following installers:
- [NodeSource installer](https://github.com/nodesource/distributions)
(recommended)
- One of the installers on the [Node.js download
page](https://nodejs.org/en/download/)
- [NodeSource installer](https://github.com/nodesource/distributions) (recommended)
- One of the installers on the [Node.js download page](https://nodejs.org/en/download/)
Or see [this page](https://nodejs.org/en/download/package-manager/) to
install npm for Linux in the way many Linux developers prefer.
Or see [this page](https://nodejs.org/en/download/package-manager/) to install npm for Linux in the way many Linux developers prefer.

21
deps/npm/docs/content/configuring-npm/npm-shrinkwrap-json.md vendored
View File

@ -6,25 +6,16 @@ description: A publishable lockfile
### Description
`npm-shrinkwrap.json` is a file created by [`npm
shrinkwrap`](/commands/npm-shrinkwrap). It is identical to
`package-lock.json`, with one major caveat: Unlike `package-lock.json`,
`npm-shrinkwrap.json` is a file created by [`npm shrinkwrap`](/commands/npm-shrinkwrap).
It is identical to `package-lock.json`, with one major caveat: Unlike `package-lock.json`,
`npm-shrinkwrap.json` may be included when publishing a package.
The recommended use-case for `npm-shrinkwrap.json` is applications deployed
through the publishing process on the registry: for example, daemons and
command-line tools intended as global installs or `devDependencies`. It's
strongly discouraged for library authors to publish this file, since that
would prevent end users from having control over transitive dependency
updates.
The recommended use-case for `npm-shrinkwrap.json` is applications deployed through the publishing process on the registry: for example, daemons and command-line tools intended as global installs or `devDependencies`.
It's strongly discouraged for library authors to publish this file, since that would prevent end users from having control over transitive dependency updates.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in a
package root, `npm-shrinkwrap.json` will be preferred over the
`package-lock.json` file.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in a package root, `npm-shrinkwrap.json` will be preferred over the `package-lock.json` file.
For full details and description of the `npm-shrinkwrap.json` file format,
refer to the manual page for
[package-lock.json](/configuring-npm/package-lock-json).
For full details and description of the `npm-shrinkwrap.json` file format, refer to the manual page for [package-lock.json](/configuring-npm/package-lock-json).
### See also

67
deps/npm/docs/content/configuring-npm/npmrc.md vendored
View File

@ -6,14 +6,11 @@ description: The npm config files
### Description
npm gets its config settings from the command line, environment variables,
and `npmrc` files.
npm gets its config settings from the command line, environment variables, and `npmrc` files.
The `npm config` command can be used to update and edit the contents of the
user and global npmrc files.
The `npm config` command can be used to update and edit the contents of the user and global npmrc files.
For a list of available configuration options, see
[config](/using-npm/config).
For a list of available configuration options, see [config](/using-npm/config).
### Files
@ -25,21 +22,21 @@ The four relevant files are:
* npm builtin config file (`/path/to/npm/npmrc`)
All npm config files are an ini-formatted list of `key = value` parameters.
Environment variables can be replaced using `${VARIABLE_NAME}`. By default
if the variable is not defined, it is left unreplaced. By adding `?` after
variable name they can be forced to evaluate to an empty string instead. For
example:
Environment variables can be replaced using `${VARIABLE_NAME}`.
By default if the variable is not defined, it is left unreplaced.
By adding `?` after variable name they can be forced to evaluate to an empty string instead.
For example:
```bash
cache = ${HOME}/.npm-packages
node-options = "${NODE_OPTIONS?} --use-system-ca"
```
Each of these files is loaded, and config options are resolved in priority
order. For example, a setting in the userconfig file would override the
setting in the globalconfig file.
Each of these files is loaded, and config options are resolved in priority order.
For example, a setting in the userconfig file would override the setting in the globalconfig file.
Array values are specified by adding "[]" after the key name. For example:
Array values are specified by adding "[]" after the key name.
For example:
```bash
key[] = "first value"
@ -49,7 +46,8 @@ key[] = "second value"
#### Comments
Lines in `.npmrc` files are interpreted as comments when they begin with a
`;` or `#` character. `.npmrc` files are parsed by
`;` or `#` character.
`.npmrc` files are parsed by
[npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
For example:
@ -62,43 +60,35 @@ For example:
#### Per-project config file
When working locally in a project, a `.npmrc` file in the root of the
project (ie, a sibling of `node_modules` and `package.json`) will set
config values specific to this project.
When working locally in a project, a `.npmrc` file in the root of the project (ie, a sibling of `node_modules` and `package.json`) will set config values specific to this project.
Note that this only applies to the root of the project that you're running
npm in. It has no effect when your module is published. For example, you
can't publish a module that forces itself to install globally, or in a
different location.
Note that this only applies to the root of the project that you're running npm in.
It has no effect when your module is published.
For example, you can't publish a module that forces itself to install globally, or in a different location.
Additionally, this file is not read in global mode, such as when running
`npm install -g`.
Additionally, this file is not read in global mode, such as when running `npm install -g`.
#### Per-user config file
`$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on
the command line)
`$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on the command line)
#### Global config file
`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): This file
is an ini-file formatted list of `key = value` parameters. Environment
variables can be replaced as above.
`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): This file is an ini-file formatted list of `key = value` parameters.
Environment variables can be replaced as above.
#### Built-in config file
`path/to/npm/itself/npmrc`
This is an unchangeable "builtin" configuration file that npm keeps
consistent across updates. Set fields in here using the `./configure`
script that comes with npm. This is primarily for distribution maintainers
to override default configs in a standard and consistent manner.
This is an unchangeable "builtin" configuration file that npm keeps consistent across updates.
Set fields in here using the `./configure` script that comes with npm.
This is primarily for distribution maintainers to override default configs in a standard and consistent manner.
### Auth related configuration
The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`,
and `keyfile` must all be scoped to a specific registry. This ensures that
`npm` will never send credentials to the wrong host.
The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`, and `keyfile` must all be scoped to a specific registry.
This ensures that `npm` will never send credentials to the wrong host.
The full list is:
- `_auth` (base64 authentication string)
@ -111,9 +101,8 @@ The full list is:
- `keyfile` (path to key file)
In order to scope these values, they must be prefixed by a URI fragment.
If the credential is meant for any request to a registry on a single host,
the scope may look like `//registry.npmjs.org/:`. If it must be scoped to a
specific path on the host that path may also be provided, such as
If the credential is meant for any request to a registry on a single host, the scope may look like `//registry.npmjs.org/:`.
If it must be scoped to a specific path on the host that path may also be provided, such as
`//my-custom-registry.org/unique/path:`.
```

575
deps/npm/docs/content/configuring-npm/package-json.md vendored
View File

File diff suppressed because it is too large Load Diff

232
deps/npm/docs/content/configuring-npm/package-lock-json.md vendored
View File

@ -6,228 +6,164 @@ description: A manifestation of the manifest
### Description
`package-lock.json` is automatically generated for any operations where npm
modifies either the `node_modules` tree, or `package.json`. It describes the
exact tree that was generated, such that subsequent installs are able to
generate identical trees, regardless of intermediate dependency updates.
`package-lock.json` is automatically generated for any operations where npm modifies either the `node_modules` tree, or `package.json`.
It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.
This file is intended to be committed into source repositories, and serves
various purposes:
This file is intended to be committed into source repositories, and serves various purposes:
* Describe a single representation of a dependency tree such that
teammates, deployments, and continuous integration are guaranteed to
install exactly the same dependencies.
* Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
* Provide a facility for users to "time-travel" to previous states of
`node_modules` without having to commit the directory itself.
* Provide a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself.
* Facilitate greater visibility of tree changes through readable source
control diffs.
* Facilitate greater visibility of tree changes through readable source control diffs.
* Optimize the installation process by allowing npm to skip repeated
metadata resolutions for previously-installed packages.
* Optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.
* As of npm v7, lockfiles include enough information to gain a complete
picture of the package tree, reducing the need to read `package.json`
files, and allowing for significant performance improvements.
* As of npm v7, lockfiles include enough information to gain a complete picture of the package tree, reducing the need to read `package.json` files, and allowing for significant performance improvements.
When `npm` creates or updates `package-lock.json`, it will infer line endings and indentation from `package.json` so that the formatting of both files matches.
### `package-lock.json` vs `npm-shrinkwrap.json`
Both of these files have the same format, and perform similar functions in
the root of a project.
Both of these files have the same format, and perform similar functions in the root of a project.
The difference is that `package-lock.json` cannot be published, and it will
be ignored if found in any place other than the root project.
The difference is that `package-lock.json` cannot be published, and it will be ignored if found in any place other than the root project.
In contrast, [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) allows
publication, and defines the dependency tree from the point encountered.
This is not recommended unless deploying a CLI tool or otherwise using the
publication process for producing production packages.
In contrast, [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json) allows publication, and defines the dependency tree from the point encountered.
This is not recommended unless deploying a CLI tool or otherwise using the publication process for producing production packages.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in the
root of a project, `npm-shrinkwrap.json` will take precedence and
`package-lock.json` will be ignored.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in the root of a project, `npm-shrinkwrap.json` will take precedence and `package-lock.json` will be ignored.
### Hidden Lockfiles
In order to avoid processing the `node_modules` folder repeatedly, npm as
of v7 uses a "hidden" lockfile present in
`node_modules/.package-lock.json`. This contains information about the
tree, and is used in lieu of reading the entire `node_modules` hierarchy
provided that the following conditions are met:
In order to avoid processing the `node_modules` folder repeatedly, npm as of v7 uses a "hidden" lockfile present in `node_modules/.package-lock.json`.
This contains information about the tree, and is used in lieu of reading the entire `node_modules` hierarchy provided that the following conditions are met:
- All package folders it references exist in the `node_modules` hierarchy.
- No package folders exist in the `node_modules` hierarchy that are not
listed in the lockfile.
- The modified time of the file is at least as recent as all of the package
folders it references.
- No package folders exist in the `node_modules` hierarchy that are not listed in the lockfile.
- The modified time of the file is at least as recent as all of the package folders it references.
That is, the hidden lockfile will only be relevant if it was created as
part of the most recent update to the package tree. If another CLI mutates
the tree in any way, this will be detected, and the hidden lockfile will be
ignored.
That is, the hidden lockfile will only be relevant if it was created as part of the most recent update to the package tree.
If another CLI mutates the tree in any way, this will be detected, and the hidden lockfile will be ignored.
Note that it _is_ possible to manually change the _contents_ of a package
in such a way that the modified time of the package folder is unaffected.
For example, if you add a file to `node_modules/foo/lib/bar.js`, then the
modified time on `node_modules/foo` will not reflect this change. If you
are manually editing files in `node_modules`, it is generally best to
delete the file at `node_modules/.package-lock.json`.
Note that it _is_ possible to manually change the _contents_ of a package in such a way that the modified time of the package folder is unaffected.
For example, if you add a file to `node_modules/foo/lib/bar.js`, then the modified time on `node_modules/foo` will not reflect this change.
If you are manually editing files in `node_modules`, it is generally best to delete the file at `node_modules/.package-lock.json`.
As the hidden lockfile is ignored by older npm versions, it does not
contain the backwards compatibility affordances present in "normal"
lockfiles. That is, it is `lockfileVersion: 3`, rather than
`lockfileVersion: 2`.
As the hidden lockfile is ignored by older npm versions, it does not contain the backwards compatibility affordances present in "normal" lockfiles.
That is, it is `lockfileVersion: 3`, rather than `lockfileVersion: 2`.
### Handling Old Lockfiles
When npm detects a lockfile from npm v6 or before during the package
installation process, it is automatically updated to fetch missing
information from either the `node_modules` tree or (in the case of empty
`node_modules` trees or very old lockfile formats) the npm registry.
When npm detects a lockfile from npm v6 or before during the package installation process, it is automatically updated to fetch missing information from either the `node_modules` tree or (in the case of empty `node_modules` trees or very old lockfile formats) the npm registry.
### File Format
#### `name`
The name of the package this is a package-lock for. This will match what's
in `package.json`.
The name of the package this is a package-lock for.
This will match what's in `package.json`.
#### `version`
The version of the package this is a package-lock for. This will match
what's in `package.json`.
The version of the package this is a package-lock for.
This will match what's in `package.json`.
#### `lockfileVersion`
An integer version, starting at `1` with the version number of this
document whose semantics were used when generating this
`package-lock.json`.
An integer version, starting at `1` with the version number of this document whose semantics were used when generating this `package-lock.json`.
Note that the file format changed significantly in npm v7 to track
information that would have otherwise required looking in `node_modules` or
the npm registry. Lockfiles generated by npm v7 will contain
`lockfileVersion: 2`.
Note that the file format changed significantly in npm v7 to track information that would have otherwise required looking in `node_modules` or the npm registry.
Lockfiles generated by npm v7 will contain `lockfileVersion: 2`.
* No version provided: an "ancient" shrinkwrap file from a version of npm
prior to npm v5.
* No version provided: an "ancient" shrinkwrap file from a version of npm prior to npm v5.
* `1`: The lockfile version used by npm v5 and v6.
* `2`: The lockfile version used by npm v7 and v8. Backwards compatible to v1
lockfiles.
* `3`: The lockfile version used by npm v9 and above. Backwards compatible to npm v7.
* `2`: The lockfile version used by npm v7 and v8. Backwards compatible to v1 lockfiles.
* `3`: The lockfile version used by npm v9 and above.
Backwards compatible to npm v7.
npm will always attempt to get whatever data it can out of a lockfile, even
if it is not a version that it was designed to support.
npm will always attempt to get whatever data it can out of a lockfile, even if it is not a version that it was designed to support.
#### `packages`
This is an object that maps package locations to an object containing the
information about that package.
This is an object that maps package locations to an object containing the information about that package.
The root project is typically listed with a key of `""`, and all other
packages are listed with their relative paths from the root project folder.
The root project is typically listed with a key of `""`, and all other packages are listed with their relative paths from the root project folder.
Package descriptors have the following fields:
* version: The version found in `package.json`
* resolved: The place where the package was actually resolved from. In
the case of packages fetched from the registry, this will be a url to a
tarball. In the case of git dependencies, this will be the full git url
with commit sha. In the case of link dependencies, this will be the
location of the link target. `registry.npmjs.org` is a magic value meaning
"the currently configured registry".
* resolved: The place where the package was actually resolved from.
In the case of packages fetched from the registry, this will be a url to a tarball.
In the case of git dependencies, this will be the full git url with commit sha.
In the case of link dependencies, this will be the location of the link target.
`registry.npmjs.org` is a magic value meaning "the currently configured registry".
* integrity: A `sha512` or `sha1` [Standard Subresource
Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
string for the artifact that was unpacked in this location.
* integrity: A `sha512` or `sha1` [Standard Subresource Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) string for the artifact that was unpacked in this location.
* link: A flag to indicate that this is a symbolic link. If this is
present, no other fields are specified, since the link target will also
be included in the lockfile.
* link: A flag to indicate that this is a symbolic link.
If this is present, no other fields are specified, since the link target will also be included in the lockfile.
* dev, optional, devOptional: If the package is strictly part of the
`devDependencies` tree, then `dev` will be true. If it is strictly part
of the `optionalDependencies` tree, then `optional` will be set. If it
is both a `dev` dependency _and_ an `optional` dependency of a non-dev
dependency, then `devOptional` will be set. (An `optional` dependency of
a `dev` dependency will have both `dev` and `optional` set.)
`devDependencies` tree, then `dev` will be true.
If it is strictly part of the `optionalDependencies` tree, then `optional` will be set.
If it is both a `dev` dependency _and_ an `optional` dependency of a non-dev dependency, then `devOptional` will be set.
(An `optional` dependency of a `dev` dependency will have both `dev` and `optional` set.)
* inBundle: A flag to indicate that the package is a bundled dependency.
* hasInstallScript: A flag to indicate that the package has a `preinstall`,
`install`, or `postinstall` script.
* hasInstallScript: A flag to indicate that the package has a `preinstall`, `install`, or `postinstall` script.
* hasShrinkwrap: A flag to indicate that the package has an
`npm-shrinkwrap.json` file.
* hasShrinkwrap: A flag to indicate that the package has an `npm-shrinkwrap.json` file.
* bin, license, engines, dependencies, optionalDependencies: fields from
`package.json`
* bin, license, engines, dependencies, optionalDependencies: fields from `package.json`
#### dependencies
Legacy data for supporting versions of npm that use `lockfileVersion: 1`.
This is a mapping of package names to dependency objects. Because the
object structure is strictly hierarchical, symbolic link dependencies are
somewhat challenging to represent in some cases.
This is a mapping of package names to dependency objects.
Because the object structure is strictly hierarchical, symbolic link dependencies are somewhat challenging to represent in some cases.
npm v7 ignores this section entirely if a `packages` section is present,
but does keep it up to date in order to support switching between npm v6
and npm v7.
npm v7 ignores this section entirely if a `packages` section is present, but does keep it up to date in order to support switching between npm v6 and npm v7.
Dependency objects have the following fields:
* version: a specifier that varies depending on the nature of the package,
and is usable in fetching a new copy of it.
* version: a specifier that varies depending on the nature of the package, and is usable in fetching a new copy of it.
* bundled dependencies: Regardless of source, this is a version number
that is purely for informational purposes.
* registry sources: This is a version number. (eg, `1.2.3`)
* git sources: This is a git specifier with resolved committish. (eg,
`git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
* http tarball sources: This is the URL of the tarball. (eg,
`https://example.com/example-1.3.0.tgz`)
* local tarball sources: This is the file URL of the tarball. (eg
`file:///opt/storage/example-1.3.0.tgz`)
* local link sources: This is the file URL of the link. (eg
`file:libs/our-module`)
* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
* registry sources: This is a version number.
(eg, `1.2.3`)
* git sources: This is a git specifier with resolved committish.
(eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
* http tarball sources: This is the URL of the tarball.
(eg, `https://example.com/example-1.3.0.tgz`)
* local tarball sources: This is the file URL of the tarball.
(eg `file:///opt/storage/example-1.3.0.tgz`)
* local link sources: This is the file URL of the link.
(eg `file:libs/our-module`)
* integrity: A `sha512` or `sha1` [Standard Subresource
Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
string for the artifact that was unpacked in this location. For git
dependencies, this is the commit sha.
* integrity: A `sha512` or `sha1` [Standard Subresource Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) string for the artifact that was unpacked in this location.
For git dependencies, this is the commit sha.
* resolved: For registry sources this is path of the tarball relative to
the registry URL. If the tarball URL isn't on the same server as the
registry URL then this is a complete URL. `registry.npmjs.org` is a magic
value meaning "the currently configured registry".
* resolved: For registry sources this is path of the tarball relative to the registry URL.
If the tarball URL isn't on the same server as the registry URL then this is a complete URL.
`registry.npmjs.org` is a magic value meaning "the currently configured registry".
* bundled: If true, this is the bundled dependency and will be installed
by the parent module. When installing, this module will be extracted
from the parent module during the extract phase, not installed as a
separate dependency.
* bundled: If true, this is the bundled dependency and will be installed by the parent module.
When installing, this module will be extracted from the parent module during the extract phase, not installed as a separate dependency.
* dev: If true then this dependency is either a development dependency ONLY
of the top level module or a transitive dependency of one. This is false
for dependencies that are both a development dependency of the top level
and a transitive dependency of a non-development dependency of the top
level.
* dev: If true then this dependency is either a development dependency ONLY of the top level module or a transitive dependency of one.
This is false for dependencies that are both a development dependency of the top level and a transitive dependency of a non-development dependency of the top level.
* optional: If true then this dependency is either an optional dependency
ONLY of the top level module or a transitive dependency of one. This is
false for dependencies that are both an optional dependency of the top
level and a transitive dependency of a non-optional dependency of the top
level.
* optional: If true then this dependency is either an optional dependency ONLY of the top level module or a transitive dependency of one.
This is false for dependencies that are both an optional dependency of the top level and a transitive dependency of a non-optional dependency of the top level.
* requires: This is a mapping of module name to version. This is a list of
everything this module requires, regardless of where it will be
installed. The version should match via normal matching rules a
dependency either in our `dependencies` or in a level higher than us.
* requires: This is a mapping of module name to version.
This is a list of everything this module requires, regardless of where it will be installed.
The version should match via normal matching rules a dependency either in our `dependencies` or in a level higher than us.
* dependencies: The dependencies of this dependency, exactly as at the top
level.
* dependencies: The dependencies of this dependency, exactly as at the top level.
### See also

875
deps/npm/docs/content/using-npm/config.md vendored
View File

File diff suppressed because it is too large Load Diff

56
deps/npm/docs/content/using-npm/dependency-selectors.md vendored
View File

@ -11,13 +11,15 @@ The [`npm query`](/commands/npm-query) command exposes a new dependency selector
- Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax
- Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible
- Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
- Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
- Consolidates redundant logic of similar query commands in `npm` (ex.
`npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
### Dependency Selector Syntax
#### Overview:
- there is no "type" or "tag" selectors (ex. `div, h1, a`) as a dependency/target is the only type of `Node` that can be queried
- there is no "type" or "tag" selectors (ex.
`div, h1, a`) as a dependency/target is the only type of `Node` that can be queried
- the term "dependencies" is in reference to any `Node` found in a `tree` returned by `Arborist`
#### Combinators
@ -66,13 +68,17 @@ The [`npm query`](/commands/npm-query) command exposes a new dependency selector
##### `:semver(<spec>, [selector], [function])`
The `:semver()` pseudo selector allows comparing fields from each node's `package.json` using [semver](https://github.com/npm/node-semver#readme) methods. It accepts up to 3 parameters, all but the first of which are optional.
The `:semver()` pseudo selector allows comparing fields from each node's `package.json` using [semver](https://github.com/npm/node-semver#readme) methods.
It accepts up to 3 parameters, all but the first of which are optional.
- `spec` a semver version or range
- `selector` an attribute selector for each node (default `[version]`)
- `function` a semver method to apply, one of: `satisfies`, `intersects`, `subset`, `gt`, `gte`, `gtr`, `lt`, `lte`, `ltr`, `eq`, `neq` or the special function `infer` (default `infer`)
When the special `infer` function is used the `spec` and the actual value from the node are compared. If both are versions, according to `semver.valid()`, `eq` is used. If both values are ranges, according to `!semver.valid()`, `intersects` is used. If the values are mixed types `satisfies` is used.
When the special `infer` function is used the `spec` and the actual value from the node are compared.
If both are versions, according to `semver.valid()`, `eq` is used.
If both values are ranges, according to `!semver.valid()`, `intersects` is used.
If the values are mixed types `satisfies` is used.
Some examples:
@ -82,7 +88,8 @@ Some examples:
##### `:outdated(<type>)`
The `:outdated` pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated. The type parameter may be one of the following:
The `:outdated` pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated.
The type parameter may be one of the following:
- `any` (default) a version exists that is greater than the current one
- `in-range` a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies
@ -91,11 +98,14 @@ The `:outdated` pseudo selector retrieves data from the registry and returns inf
- `minor` a version exists that is a semver minor greater than the current one
- `patch` a version exists that is a semver patch greater than the current one
In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects. The following data can be found under the `queryContext` property of each node.
In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects.
The following data can be found under the `queryContext` property of each node.
- `versions` an array of every available version of the given node
- `outdated.inRange` an array of objects, each with a `from` and `versions`, where `from` is the on-disk location of the node that depends on the current node and `versions` is an array of all available versions that satisfies that dependency. This is only populated if `:outdated(in-range)` is used.
- `outdated.outOfRange` an array of objects, identical in shape to `inRange`, but where the `versions` array is every available version that does not satisfy the dependency. This is only populated if `:outdated(out-of-range)` is used.
- `outdated.inRange` an array of objects, each with a `from` and `versions`, where `from` is the on-disk location of the node that depends on the current node and `versions` is an array of all available versions that satisfies that dependency.
This is only populated if `:outdated(in-range)` is used.
- `outdated.outOfRange` an array of objects, identical in shape to `inRange`, but where the `versions` array is every available version that does not satisfy the dependency.
This is only populated if `:outdated(out-of-range)` is used.
Some examples:
@ -104,9 +114,13 @@ Some examples:
##### `:vuln`
The `:vuln` pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability. Only dependencies whose current version matches a vulnerability will be returned. For example if you have `semver@7.6.0` in your tree, a vulnerability for `semver` which affects versions `<=6.3.1` will not match.
The `:vuln` pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability.
Only dependencies whose current version matches a vulnerability will be returned.
For example if you have `semver@7.6.0` in your tree, a vulnerability for `semver` which affects versions `<=6.3.1` will not match.
You can also filter results by certain attributes in advisories. Currently that includes `severity` and `cwe`. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
You can also filter results by certain attributes in advisories.
Currently that includes `severity` and `cwe`.
Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the `queryContext` attribute of each node under the `advisories` attribute.
@ -121,7 +135,8 @@ Some examples:
The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
- `[]` attribute selector (ie. existence of attribute)
- `[]` attribute selector (ie.
existence of attribute)
- `[attribute=value]` attribute value is equivalent...
- `[attribute~=value]` attribute value contains word...
- `[attribute*=value]` attribute value contains string...
@ -131,7 +146,10 @@ The attribute selector evaluates the key/value pairs in `package.json` if they a
#### `Array` & `Object` Attribute Selectors
The generic `:attr()` pseudo selector standardizes a pattern which can be used for attribute selection of `Object`s, `Array`s or `Arrays` of `Object`s accessible via `Arborist`'s `Node.package` metadata. This allows for iterative attribute selection beyond top-level `String` evaluation. The last argument passed to `:attr()` must be an `attribute` selector or a nested `:attr()`. See examples below:
The generic `:attr()` pseudo selector standardizes a pattern which can be used for attribute selection of `Object`s, `Array`s or `Arrays` of `Object`s accessible via `Arborist`'s `Node.package` metadata.
This allows for iterative attribute selection beyond top-level `String` evaluation.
The last argument passed to `:attr()` must be an `attribute` selector or a nested `:attr()`.
See examples below:
#### `Objects`
@ -145,13 +163,14 @@ The generic `:attr()` pseudo selector standardizes a pattern which can be used f
Nested objects are expressed as sequential arguments to `:attr()`.
```css
/* return dependencies that have a testling config for opera browsers */
/* return dependencies that have a [testling config](https://ci.testling.com/guide/advanced_configuration) for opera browsers */
*:attr(testling, browsers, [~=opera])
```
#### `Arrays`
`Array`s specifically uses a special/reserved `.` character in place of a typical attribute name. `Arrays` also support exact `value` matching when a `String` is passed to the selector.
`Array`s specifically uses a special/reserved `.` character in place of a typical attribute name.
`Arrays` also support exact `value` matching when a `String` is passed to the selector.
##### Example of an `Array` Attribute Selection:
```css
@ -176,7 +195,11 @@ Nested objects are expressed as sequential arguments to `:attr()`.
### Groups
Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in `package.json`). This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost. Dependencies are allowed to be included in multiple groups (ex. a `prod` dependency may also be a `dev` dependency (in that it's also required by another `dev` dependency) & may also be `bundled` - a selector for that type of dependency would look like: `*.prod.dev.bundled`).
Dependency groups are defined by the package relationships to their ancestors (ie.
the dependency types that are defined in `package.json`).
This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost.
Dependencies are allowed to be included in multiple groups (ex.
a `prod` dependency may also be a `dev` dependency (in that it's also required by another `dev` dependency) & may also be `bundled` - a selector for that type of dependency would look like: `*.prod.dev.bundled`).
- `.prod`
- `.dev`
@ -185,7 +208,8 @@ Dependency groups are defined by the package relationships to their ancestors (i
- `.bundled`
- `.workspace`
Please note that currently `workspace` deps are always `prod` dependencies. Additionally the `.root` dependency is also considered a `prod` dependency.
Please note that currently `workspace` deps are always `prod` dependencies.
Additionally the `.root` dependency is also considered a `prod` dependency.
### Programmatic Usage

142
deps/npm/docs/content/using-npm/developers.md vendored
View File

@ -6,19 +6,16 @@ description: Developer Guide
### Description
So, you've decided to use npm to develop (and maybe publish/deploy)
your project.
So, you've decided to use npm to develop (and maybe publish/deploy) your project.
Fantastic!
There are a few things that you need to do above the simple steps
that your users will do to install your program.
There are a few things that you need to do above the simple steps that your users will do to install your program.
### About These Documents
These are man pages. If you install npm, you should be able to
then do `man npm-thing` to get the documentation on a particular
topic, or `npm help thing` to see the same information.
These are man pages.
If you install npm, you should be able to then do `man npm-thing` to get the documentation on a particular topic, or `npm help thing` to see the same information.
### What is a Package
@ -32,10 +29,7 @@ A package is:
* f) a `<name>` that has a "latest" tag satisfying (e)
* g) a `git` url that, when cloned, results in (a).
Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
perhaps if you also want to be able to easily install it elsewhere
after packing it up into a tarball (b).
Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and perhaps if you also want to be able to easily install it elsewhere after packing it up into a tarball (b).
Git urls can be of the form:
@ -46,74 +40,62 @@ git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish
```
The `commit-ish` can be any tag, sha, or branch which can be supplied as
an argument to `git checkout`. The default is whatever the repository uses
as its default branch.
The `commit-ish` can be any tag, sha, or branch which can be supplied as an argument to `git checkout`.
The default is whatever the repository uses as its default branch.
### The package.json File
You need to have a `package.json` file in the root of your project to do
much of anything with npm. That is basically the whole interface.
You need to have a `package.json` file in the root of your project to do much of anything with npm.
That is basically the whole interface.
See [`package.json`](/configuring-npm/package-json) for details about what
goes in that file. At the very least, you need:
See [`package.json`](/configuring-npm/package-json) for details about what goes in that file.
At the very least, you need:
* name: This should be a string that identifies your project. Please do
not use the name to specify that it runs on node, or is in JavaScript.
You can use the "engines" field to explicitly state the versions of node
(or whatever else) that your program requires, and it's pretty well
assumed that it's JavaScript.
* name: This should be a string that identifies your project.
Please do not use the name to specify that it runs on node, or is in JavaScript.
You can use the "engines" field to explicitly state the versions of node (or whatever else) that your program requires, and it's pretty well assumed that it's JavaScript.
It does not necessarily need to match your github repository name.
So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better.
So, `node-foo` and `bar-js` are bad names.
`foo` or `bar` are better.
* version: A semver-compatible version.
* engines: Specify the versions of node (or whatever else) that your
program runs on. The node API changes a lot, and there may be bugs or
new functionality that you depend on. Be explicit.
* engines: Specify the versions of node (or whatever else) that your program runs on.
The node API changes a lot, and there may be bugs or new functionality that you depend on.
Be explicit.
* author: Take some credit.
* scripts: If you have a special compilation or installation script, then
you should put it in the `scripts` object. You should definitely have at
least a basic smoke-test command as the "scripts.test" field. See
[scripts](/using-npm/scripts).
* scripts: If you have a special compilation or installation script, then you should put it in the `scripts` object.
You should definitely have at least a basic smoke-test command as the "scripts.test" field.
See [scripts](/using-npm/scripts).
* main: If you have a single module that serves as the entry point to your
program (like what the "foo" package gives you at require("foo")), then
you need to specify that in the "main" field.
* main: If you have a single module that serves as the entry point to your program (like what the "foo" package gives you at require("foo")), then you need to specify that in the "main" field.
* directories: This is an object mapping names to folders. The best ones
to include are "lib" and "doc", but if you use "man" to specify a folder
full of man pages, they'll get installed just like these ones.
* directories: This is an object mapping names to folders.
The best ones to include are "lib" and "doc", but if you use "man" to specify a folder full of man pages, they'll get installed just like these ones.
You can use `npm init` in the root of your package in order to get you
started with a pretty basic package.json file. See [`npm
init`](/commands/npm-init) for more info.
You can use `npm init` in the root of your package in order to get you started with a pretty basic package.json file.
See [`npm init`](/commands/npm-init) for more info.
### Keeping files *out* of your Package
Use a `.npmignore` file to keep stuff out of your package. If there's no
`.npmignore` file, but there *is* a `.gitignore` file, then npm will ignore
the stuff matched by the `.gitignore` file. If you *want* to include
something that is excluded by your `.gitignore` file, you can create an
empty `.npmignore` file to override it. Like `git`, `npm` looks for
`.npmignore` and `.gitignore` files in all subdirectories of your package,
not only the root directory.
Use a `.npmignore` file to keep stuff out of your package.
If there's no `.npmignore` file, but there *is* a `.gitignore` file, then npm will ignore the stuff matched by the `.gitignore` file.
If you *want* to include something that is excluded by your `.gitignore` file, you can create an empty `.npmignore` file to override it.
Like `git`, `npm` looks for `.npmignore` and `.gitignore` files in all subdirectories of your package, not only the root directory.
`.npmignore` files follow the [same pattern
rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
as `.gitignore` files:
`.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) as `.gitignore` files:
* Blank lines or lines starting with `#` are ignored.
* Standard glob patterns work.
* You can end patterns with a forward slash `/` to specify a directory.
* You can negate a pattern by starting it with an exclamation point `!`.
By default, some paths and files are ignored, so there's no
need to add them to `.npmignore` explicitly. Some examples are:
By default, some paths and files are ignored, so there's no need to add them to `.npmignore` explicitly.
Some examples are:
* `.*.swp`
* `._*`
@ -130,39 +112,28 @@ need to add them to `.npmignore` explicitly. Some examples are:
* `CVS`
* `npm-debug.log`
Additionally, everything in `node_modules` is ignored, except for
bundled dependencies. npm automatically handles this for you, so don't
bother adding `node_modules` to `.npmignore`.
Additionally, everything in `node_modules` is ignored, except for bundled dependencies.
npm automatically handles this for you, so don't bother adding `node_modules` to `.npmignore`.
The following paths and files are never ignored, so adding them to
`.npmignore` is pointless:
The following paths and files are never ignored, so adding them to `.npmignore` is pointless:
* `package.json`
* `README` (and its variants)
* `LICENSE` / `LICENCE`
If, given the structure of your project, you find `.npmignore` to be a
maintenance headache, you might instead try populating the `files`
property of `package.json`, which is an array of file or directory names
that should be included in your package. Sometimes manually picking
which items to allow is easier to manage than building a block list.
If, given the structure of your project, you find `.npmignore` to be a maintenance headache, you might instead try populating the `files` property of `package.json`, which is an array of file or directory names that should be included in your package.
Sometimes manually picking which items to allow is easier to manage than building a block list.
See [`package.json`](/configuring-npm/package-json) for more info on
what can and can't be ignored.
See [`package.json`](/configuring-npm/package-json) for more info on what can and can't be ignored.
#### Testing whether your `.npmignore` or `files` config works
If you want to double check that your package will include only the files
you intend it to when published, you can run the `npm pack` command locally
which will generate a tarball in the working directory, the same way it
does for publishing.
If you want to double check that your package will include only the files you intend it to when published, you can run the `npm pack` command locally which will generate a tarball in the working directory, the same way it does for publishing.
### Link Packages
`npm link` is designed to install a development package and see the
changes in real time without having to keep re-installing it. (You do
need to either re-link or `npm rebuild -g` to update compiled packages,
of course.)
`npm link` is designed to install a development package and see the changes in real time without having to keep re-installing it.
(You do need to either re-link or `npm rebuild -g` to update compiled packages, of course.)
More info at [`npm link`](/commands/npm-link).
@ -170,9 +141,8 @@ More info at [`npm link`](/commands/npm-link).
**This is important.**
If you can not install it locally, you'll have
problems trying to publish it. Or, worse yet, you'll be able to
publish it, but you'll be publishing a broken or pointless package.
If you cannot install it locally, you'll have problems trying to publish it.
Or, worse yet, you'll be able to publish it, but you'll be publishing a broken or pointless package.
So don't do that.
In the root of your package, do this:
@ -181,8 +151,8 @@ In the root of your package, do this:
npm install . -g
```
That'll show you that it's working. If you'd rather just create a symlink
package that points to your working directory, then do this:
That'll show you that it's working.
If you'd rather just create a symlink package that points to your working directory, then do this:
```bash
npm link
@ -199,12 +169,12 @@ npm install ../my-package
to install it locally into the node_modules folder in that other place.
Then go into the node-repl, and try using require("my-thing") to
bring in your module's main module.
Then go into the node-repl, and try using require("my-thing") to bring in your module's main module.
### Create a User Account
Create a user with the adduser command. It works like this:
Create a user with the adduser command.
It works like this:
```bash
npm adduser
@ -216,19 +186,17 @@ This is documented better in [npm adduser](/commands/npm-adduser).
### Publish your Package
This part's easy. In the root of your folder, do this:
This part's easy.
In the root of your folder, do this:
```bash
npm publish
```
You can give publish a url to a tarball, or a filename of a tarball,
or a path to a folder.
You can give publish a url to a tarball, or a filename of a tarball, or a path to a folder.
Note that pretty much **everything in that folder will be exposed**
by default. So, if you have secret stuff in there, use a
`.npmignore` file to list out the globs to ignore, or publish
from a fresh checkout.
Note that pretty much **everything in that folder will be exposed** by default.
So, if you have secret stuff in there, use a `.npmignore` file to list out the globs to ignore, or publish from a fresh checkout.
### Brag about it

31
deps/npm/docs/content/using-npm/logging.md vendored
View File

@ -12,10 +12,11 @@ The `npm` CLI has various mechanisms for showing different levels of information
All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
The default location of the logs directory is a directory named `_logs` inside the npm cache. This can be changed with the `logs-dir` config option.
The default location of the logs directory is a directory named `_logs` inside the npm cache.
This can be changed with the `logs-dir` config option.
For example, if you wanted to write all your logs to the current working directory, you could run: `npm install --logs-dir=.`. This is especially helpful in debugging a specific `npm` issue as you can run
a command multiple times with different config values and then diff all the log files.
For example, if you wanted to write all your logs to the current working directory, you could run: `npm install --logs-dir=.`.
This is especially helpful in debugging a specific `npm` issue as you can run a command multiple times with different config values and then diff all the log files.
Log files will be removed from the `logs-dir` when the number of log files exceeds `logs-max`, with the oldest logs being deleted first.
@ -55,30 +56,31 @@ The log levels listed above have various corresponding aliases, including:
#### `foreground-scripts`
The `npm` CLI began hiding the output of lifecycle scripts for `npm install` as of `v7`. Notably, this means you will not see logs/output from packages that may be using "install scripts" to display information back to you or from your own project's scripts defined in `package.json`. If you'd like to change this behavior & log this output you can set `foreground-scripts` to `true`.
The `npm` CLI began hiding the output of lifecycle scripts for `npm install` as of `v7`.
Notably, this means you will not see logs/output from packages that may be using "install scripts" to display information back to you or from your own project's scripts defined in `package.json`.
If you'd like to change this behavior & log this output you can set `foreground-scripts` to `true`.
### Timing Information
The [`--timing` config](/using-npm/config#timing) can be set which does a few
things:
The [`--timing` config](/using-npm/config#timing) can be set which does a few things:
1. Always shows the full path to the debug log regardless of command exit status
1. Write timing information to a process specific timing file in the cache or `logs-dir`
1. Output timing information to the terminal
This file contains a `timers` object where the keys are an identifier for the
portion of the process being timed and the value is the number of milliseconds it took to complete.
This file contains a `timers` object where the keys are an identifier for the portion of the process being timed and the value is the number of milliseconds it took to complete.
Sometimes it is helpful to get timing information without outputting anything to the terminal. For
example, the performance might be affected by writing to the terminal. In this case you can use
`--timing --silent` which will still write the timing file, but not output anything to the terminal
while running.
Sometimes it is helpful to get timing information without outputting anything to the terminal.
For example, the performance might be affected by writing to the terminal.
In this case you can use
`--timing --silent` which will still write the timing file, but not output anything to the terminal while running.
### Registry Response Headers
#### `npm-notice`
The `npm` CLI reads from & logs any `npm-notice` headers that are returned from the configured registry. This mechanism can be used by third-party registries to provide useful information when network-dependent requests occur.
The `npm` CLI reads from & logs any `npm-notice` headers that are returned from the configured registry.
This mechanism can be used by third-party registries to provide useful information when network-dependent requests occur.
This header is not cached, and will not be logged if the request is served from the cache.
@ -89,7 +91,8 @@ The `npm` CLI makes a best effort to redact the following from terminal output a
- Passwords inside basic auth URLs
- npm tokens
However, this behavior should not be relied on to keep all possible sensitive information redacted. If you are concerned about secrets in your log file or terminal output, you can use `--loglevel=silent` and `--logs-max=0` to ensure no logs are written to your terminal or filesystem.
However, this behavior should not be relied on to keep all possible sensitive information redacted.
If you are concerned about secrets in your log file or terminal output, you can use `--loglevel=silent` and `--logs-max=0` to ensure no logs are written to your terminal or filesystem.
### See also

19
deps/npm/docs/content/using-npm/orgs.md vendored
View File

@ -12,11 +12,15 @@ There are three levels of org users:
2. Team admin, manages team membership & package access.
3. Developer, works on packages they are given access to.
The super admin is the only person who can add users to the org because it impacts the monthly bill. The super admin will use the website to manage membership. Every org has a `developers` team that all users are automatically added to.
The super admin is the only person who can add users to the org because it impacts the monthly bill.
The super admin will use the website to manage membership.
Every org has a `developers` team that all users are automatically added to.
The team admin is the person who manages team creation, team membership, and package access for teams. The team admin grants package access to teams, not individuals.
The team admin is the person who manages team creation, team membership, and package access for teams.
The team admin grants package access to teams, not individuals.
The developer will be able to access packages based on the teams they are on. Access is either read-write or read-only.
The developer will be able to access packages based on the teams they are on.
Access is either read-write or read-only.
There are two main commands:
@ -31,7 +35,8 @@ There are two main commands:
npm team ls <org>:developers
```
* Each org is automatically given a `developers` team, so you can see the whole list of team members in your org. This team automatically gets read-write access to all packages, but you can change that with the `access` command.
* Each org is automatically given a `developers` team, so you can see the whole list of team members in your org.
This team automatically gets read-write access to all packages, but you can change that with the `access` command.
* Create a new team:
@ -71,19 +76,19 @@ npm access revoke <org:team> [<package>]
* See what org packages a team member can access:
```bash
npm access ls-packages <org> <user>
npm access list packages <org> <user>
```
* See packages available to a specific team:
```bash
npm access ls-packages <org:team>
npm access list packages <org:team>
```
* Check which teams are collaborating on a package:
```bash
npm access ls-collaborators <pkg>
npm access list collaborators <pkg>
```
### See also

47
deps/npm/docs/content/using-npm/package-spec.md vendored
View File

@ -6,12 +6,9 @@ description: Package name specifier
### Description
Commands like `npm install` and the dependency sections in the
`package.json` use a package name specifier. This can be many different
things that all refer to a "package". Examples include a package name,
git url, tarball, or local directory. These will generally be referred
to as `<package-spec>` in the help output for the npm commands that use
this package name specifier.
Commands like `npm install` and the dependency sections in the `package.json` use a package name specifier.
This can be many different things that all refer to a "package". Examples include a package name, git url, tarball, or local directory.
These will generally be referred to as `<package-spec>` in the help output for the npm commands that use this package name specifier.
### Package name
@ -20,10 +17,8 @@ this package name specifier.
* `[<@scope>/]<pkg>@<version>`
* `[<@scope>/]<pkg>@<version range>`
Refers to a package by name, with or without a scope, and optionally
tag, version, or version range. This is typically used in combination
with the [registry](/using-npm/config#registry) config to refer to a
package in a registry.
Refers to a package by name, with or without a scope, and optionally tag, version, or version range.
This is typically used in combination with the [registry](/using-npm/config#registry) config to refer to a package in a registry.
Examples:
* `npm`
@ -36,15 +31,10 @@ Examples:
* `<alias>@npm:<name>`
Primarily used by commands like `npm install` and in the dependency
sections in the `package.json`, this refers to a package by an alias.
The `<alias>` is the name of the package as it is reified in the
`node_modules` folder, and the `<name>` refers to a package name as
found in the configured registry.
Primarily used by commands like `npm install` and in the dependency sections in the `package.json`, this refers to a package by an alias.
The `<alias>` is the name of the package as it is reified in the `node_modules` folder, and the `<name>` refers to a package name as found in the configured registry.
See `Package name` above for more info on referring to a package by
name, and [registry](/using-npm/config#registry) for configuring which
registry is used when referring to a package by name.
See `Package name` above for more info on referring to a package by name, and [registry](/using-npm/config#registry) for configuring which registry is used when referring to a package by name.
Examples:
* `semver:@npm:@npmcli/semver-with-patch`
@ -55,12 +45,10 @@ Examples:
* `<folder>`
This refers to a package on the local filesystem. Specifically this is
a folder with a `package.json` file in it. This *should* always be
prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion.
npm currently will parse a string with more than one `/` in it as a
folder, but this is legacy behavior that may be removed in a future
version.
This refers to a package on the local filesystem.
Specifically this is a folder with a `package.json` file in it.
This *should* always be prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion.
npm currently will parse a string with more than one `/` in it as a folder, but this is legacy behavior that may be removed in a future version.
Examples:
@ -77,18 +65,17 @@ Examples:
* `./my-package.tgz`
* `https://registry.npmjs.org/semver/-/semver-1.0.0.tgz`
Refers to a package in a tarball format, either on the local filesystem
or remotely via url. This is the format that packages exist in when
uploaded to a registry.
Refers to a package in a tarball format, either on the local filesystem or remotely via url.
This is the format that packages exist in when uploaded to a registry.
### git urls
* `<git:// url>`
* `<github username>/<github project>`
Refers to a package in a git repo. This can be a full git url, git
shorthand, or a username/package on GitHub. You can specify a
git tag, branch, or other git ref by appending `#ref`.
Refers to a package in a git repo.
This can be a full git url, git shorthand, or a username/package on GitHub.
You can specify a git tag, branch, or other git ref by appending `#ref`.
Examples:

66
deps/npm/docs/content/using-npm/registry.md vendored
View File

@ -6,66 +6,44 @@ description: The JavaScript Package Registry
### Description
To resolve packages by name and version, npm talks to a registry website
that implements the CommonJS Package Registry specification for reading
package info.
To resolve packages by name and version, npm talks to a registry website that implements the CommonJS Package Registry specification for reading package info.
npm is configured to use the **npm public registry** at
<https://registry.npmjs.org> by default. Use of the npm public registry is
subject to terms of use available at <https://docs.npmjs.com/policies/terms>.
<https://registry.npmjs.org> by default.
Use of the npm public registry is subject to terms of use available at <https://docs.npmjs.com/policies/terms>.
You can configure npm to use any compatible registry you like, and even run
your own registry. Use of someone else's registry may be governed by their
terms of use.
You can configure npm to use any compatible registry you like, and even run your own registry.
Use of someone else's registry may be governed by their terms of use.
npm's package registry implementation supports several
write APIs as well, to allow for publishing packages and managing user
account information.
npm's package registry implementation supports several write APIs as well, to allow for publishing packages and managing user account information.
The registry URL used is determined by the scope of the package (see
[`scope`](/using-npm/scope). If no scope is specified, the default registry is
used, which is supplied by the [`registry` config](/using-npm/config#registry)
parameter. See [`npm config`](/commands/npm-config),
[`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on
managing npm's configuration.
Authentication configuration such as auth tokens and certificates are configured
specifically scoped to an individual registry. See
[Auth Related Configuration](/configuring-npm/npmrc#auth-related-configuration)
The registry URL used is determined by the scope of the package (see [`scope`](/using-npm/scope).
If no scope is specified, the default registry is used, which is supplied by the [`registry` config](/using-npm/config#registry) parameter.
See [`npm config`](/commands/npm-config), [`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on managing npm's configuration.
Authentication configuration such as auth tokens and certificates are configured specifically scoped to an individual registry.
See [Auth Related Configuration](/configuring-npm/npmrc#auth-related-configuration)
When the default registry is used in a package-lock or shrinkwrap it has the
special meaning of "the currently configured registry". If you create a lock
file while using the default registry you can switch to another registry and
npm will install packages from the new registry, but if you create a lock
file while using a custom registry packages will be installed from that
registry even after you change to another registry.
When the default registry is used in a package-lock or shrinkwrap it has the special meaning of "the currently configured registry". If you create a lock file while using the default registry you can switch to another registry and npm will install packages from the new registry, but if you create a lock file while using a custom registry packages will be installed from that registry even after you change to another registry.
### Does npm send any information about me back to the registry?
Yes.
When making requests of the registry npm adds two headers with information
about your environment:
When making requests of the registry npm adds two headers with information about your environment:
* `Npm-Scope` – If your project is scoped, this header will contain its
scope. In the future npm hopes to build registry features that use this
information to allow you to customize your experience for your
organization.
* `Npm-In-CI` – Set to "true" if npm believes this install is running in a
continuous integration environment, "false" otherwise. This is detected by
looking for the following environment variables: `CI`, `TDDIUM`,
`JENKINS_URL`, `bamboo.buildKey`. If you'd like to learn more you may find
the [original PR](https://github.com/npm/npm-registry-client/pull/129)
interesting.
This is used to gather better metrics on how npm is used by humans, versus
build farms.
* `Npm-Scope` – If your project is scoped, this header will contain its scope.
In the future npm hopes to build registry features that use this information to allow you to customize your experience for your organization.
* `Npm-In-CI` – Set to "true" if npm believes this install is running in a continuous integration environment, "false" otherwise.
This is detected by looking for the following environment variables: `CI`, `TDDIUM`,
`JENKINS_URL`, `bamboo.buildKey`.
If you'd like to learn more you may find the [original PR](https://github.com/npm/npm-registry-client/pull/129) interesting.
This is used to gather better metrics on how npm is used by humans, versus build farms.
The npm registry does not try to correlate the information in these headers
with any authenticated accounts that may be used in the same requests.
The npm registry does not try to correlate the information in these headers with any authenticated accounts that may be used in the same requests.
### How can I prevent my package from being published in the official registry?
Set `"private": true` in your `package.json` to prevent it from being
published at all, or
Set `"private": true` in your `package.json` to prevent it from being published at all, or
`"publishConfig":{"registry":"http://my-internal-registry.local"}`
to force it to be published only to your internal/private registry.

29
deps/npm/docs/content/using-npm/removal.md vendored
View File

@ -16,20 +16,17 @@ Or, if that fails, please proceed to more severe uninstalling methods.
### More Severe Uninstalling
Usually, the above instructions are sufficient. That will remove
npm, but leave behind anything you've installed.
Usually, the above instructions are sufficient.
That will remove npm, but leave behind anything you've installed.
If that doesn't work, or if you require more drastic measures,
continue reading.
If that doesn't work, or if you require more drastic measures, continue reading.
Note that this is only necessary for globally-installed packages. Local
installs are completely contained within a project's `node_modules`
folder. Delete that folder, and everything is gone unless a package's
install script is particularly ill-behaved.
Note that this is only necessary for globally-installed packages.
Local installs are completely contained within a project's `node_modules` folder.
Delete that folder, and everything is gone unless a package's install script is particularly ill-behaved.
This assumes that you installed node and npm in the default place. If
you configured node with a different `--prefix`, or installed npm with a
different prefix setting, then adjust the paths accordingly, replacing
This assumes that you installed node and npm in the default place.
If you configured node with a different `--prefix`, or installed npm with a different prefix setting, then adjust the paths accordingly, replacing
`/usr/local` with your install prefix.
To remove everything npm-related manually:
@ -38,17 +35,15 @@ To remove everything npm-related manually:
rm -rf /usr/local/{lib/node{,/.npm,_modules},bin,share/man}/npm*
```
If you installed things *with* npm, then your best bet is to uninstall
them with npm first, and then install them again once you have a
proper install. This can help find any symlinks that are lying
around:
If you installed things *with* npm, then your best bet is to uninstall them with npm first, and then install them again once you have a proper install.
This can help find any symlinks that are lying around:
```bash
ls -laF /usr/local/{lib/node{,/.npm},bin,share/man} | grep npm
```
Prior to version 0.3, npm used shim files for executables and node
modules. To track those down, you can do the following:
Prior to version 0.3, npm used shim files for executables and node modules.
To track those down, you can do the following:
```bash
find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ;

86
deps/npm/docs/content/using-npm/scope.md vendored
View File

@ -6,35 +6,29 @@ description: Scoped packages
### Description
All npm packages have a name. Some package names also have a scope. A scope
follows the usual rules for package names (URL-safe characters, no leading dots
or underscores). When used in package names, scopes are preceded by an `@` symbol
and followed by a slash, e.g.
All npm packages have a name.
Some package names also have a scope.
A scope follows the usual rules for package names (URL-safe characters, no leading dots or underscores).
When used in package names, scopes are preceded by an `@` symbol and followed by a slash, e.g.
```bash
@somescope/somepackagename
```
Scopes are a way of grouping related packages together, and also affect a few
things about the way npm treats the package.
Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package.
Each npm user/organization has their own scope, and only you can add packages
in your scope. This means you don't have to worry about someone taking your
package name ahead of you. Thus it is also a good way to signal official packages
for organizations.
Each npm user/organization has their own scope, and only you can add packages in your scope.
This means you don't have to worry about someone taking your package name ahead of you.
Thus it is also a good way to signal official packages for organizations.
Scoped packages can be published and installed as of `npm@2` and are supported
by the primary npm registry. Unscoped packages can depend on scoped packages and
vice versa. The npm client is backwards-compatible with unscoped registries,
so it can be used to work with scoped and unscoped registries at the same time.
Scoped packages can be published and installed as of `npm@2` and are supported by the primary npm registry.
Unscoped packages can depend on scoped packages and vice versa.
The npm client is backwards-compatible with unscoped registries, so it can be used to work with scoped and unscoped registries at the same time.
### Installing scoped packages
Scoped packages are installed to a sub-folder of the regular installation
folder, e.g. if your other packages are installed in `node_modules/packagename`,
scoped modules will be installed in `node_modules/@myorg/packagename`. The scope
folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can
contain any number of scoped packages.
Scoped packages are installed to a sub-folder of the regular installation folder, e.g. if your other packages are installed in `node_modules/packagename`, scoped modules will be installed in `node_modules/@myorg/packagename`.
The scope folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can contain any number of scoped packages.
A scoped package is installed by referencing it by name, preceded by an
`@` symbol, in `npm install`:
@ -51,26 +45,22 @@ Or in `package.json`:
}
```
Note that if the `@` symbol is omitted, in either case, npm will instead attempt to
install from GitHub; see [`npm install`](/commands/npm-install).
Note that if the `@` symbol is omitted, in either case, npm will instead attempt to install from GitHub; see [`npm install`](/commands/npm-install).
### Requiring scoped packages
Because scoped packages are installed into a scope folder, you have to
include the name of the scope when requiring them in your code, e.g.
Because scoped packages are installed into a scope folder, you have to include the name of the scope when requiring them in your code, e.g.
```javascript
require('@myorg/mypackage')
```
There is nothing special about the way Node treats scope folders. This
simply requires the `mypackage` module in the folder named `@myorg`.
There is nothing special about the way Node treats scope folders.
This simply requires the `mypackage` module in the folder named `@myorg`.
### Publishing scoped packages
Scoped packages can be published from the CLI as of `npm@2` and can be
published to any registry that supports them, including the primary npm
registry.
Scoped packages can be published from the CLI as of `npm@2` and can be published to any registry that supports them, including the primary npm registry.
(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry
**does** support scoped packages.)
@ -84,36 +74,27 @@ Publishing to a scope, you have two options:
- Publishing to your user scope (example: `@username/module`)
- Publishing to an organization scope (example: `@org/module`)
If publishing a public module to an organization scope, you must
first either create an organization with the name of the scope
that you'd like to publish to or be added to an existing organization
with the appropriate permissions. For example, if you'd like to
publish to `@org`, you would need to create the `org` organization
on npmjs.com prior to trying to publish.
If publishing a public module to an organization scope, you must first either create an organization with the name of the scope that you'd like to publish to or be added to an existing organization with the appropriate permissions.
For example, if you'd like to publish to `@org`, you would need to create the `org` organization on npmjs.com prior to trying to publish.
Scoped packages are not public by default. You will need to specify
`--access public` with the initial `npm publish` command. This will publish
the package and set access to `public` as if you had run `npm access public`
after publishing. You do not need to do this when publishing new versions of
an existing scoped package.
Scoped packages are not public by default.
You will need to specify
`--access public` with the initial `npm publish` command.
This will publish the package and set access to `public` as if you had run `npm access public` after publishing.
You do not need to do this when publishing new versions of an existing scoped package.
#### Publishing private scoped packages to the npm registry
To publish a private scoped package to the npm registry, you must have
an [npm Private Modules](https://docs.npmjs.com/private-modules/intro)
account.
To publish a private scoped package to the npm registry, you must have an [npm Private Modules](https://docs.npmjs.com/private-modules/intro) account.
You can then publish the module with `npm publish` or `npm publish
--access restricted`, and it will be present in the npm registry, with
restricted access. You can then change the access permissions, if
desired, with `npm access` or on the npmjs.com website.
--access restricted`, and it will be present in the npm registry, with restricted access.
You can then change the access permissions, if desired, with `npm access` or on the npmjs.com website.
### Associating a scope with a registry
Scopes can be associated with a separate registry. This allows you to
seamlessly use a mix of packages from the primary npm registry and one or more
private registries, such as [GitHub Packages](https://github.com/features/packages) or the open source [Verdaccio](https://verdaccio.org)
project.
Scopes can be associated with a separate registry.
This allows you to seamlessly use a mix of packages from the primary npm registry and one or more private registries, such as [GitHub Packages](https://github.com/features/packages) or the open source [Verdaccio](https://verdaccio.org) project.
You can associate a scope with a registry at login, e.g.
@ -121,8 +102,7 @@ You can associate a scope with a registry at login, e.g.
npm login --registry=http://reg.example.com --scope=@myco
```
Scopes have a many-to-one relationship with registries: one registry can
host multiple scopes, but a scope only ever points to one registry.
Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry.
You can also associate a scope with a registry using `npm config`:
@ -130,8 +110,8 @@ You can also associate a scope with a registry using `npm config`:
npm config set @myco:registry=http://reg.example.com
```
Once a scope is associated with a registry, any `npm install` for a package
with that scope will request packages from that registry instead. Any
Once a scope is associated with a registry, any `npm install` for a package with that scope will request packages from that registry instead.
Any
`npm publish` for a package name that contains the scope will be published to
that registry instead.

173
deps/npm/docs/content/using-npm/scripts.md vendored
View File

@ -6,13 +6,12 @@ description: How npm handles the "scripts" field
### Description
The `"scripts"` property of your `package.json` file supports a number
of built-in scripts and their preset life cycle events as well as
arbitrary scripts. These all can be executed by running
`npm run <stage>`. *Pre* and *post*
commands with matching names will be run for those as well (e.g. `premyscript`,
`myscript`, `postmyscript`). Scripts from dependencies can be run with
`npm explore <pkg> -- npm run <stage>`.
The `"scripts"` property of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts.
These all can be executed by running `npm run <stage>`.
*Pre* and *post* commands with matching names will be run for those as well (e.g.
`premyscript`,
`myscript`, `postmyscript`).
Scripts from dependencies can be run with `npm explore <pkg> -- npm run <stage>`.
### Pre & Post Scripts
@ -30,35 +29,31 @@ To create "pre" or "post" scripts for any scripts defined in the
}
```
In this example `npm run compress` would execute these scripts as
described.
In this example `npm run compress` would execute these scripts as described.
### Life Cycle Scripts
There are some special life cycle scripts that happen only in certain
situations. These scripts happen in addition to the `pre<event>`, `post<event>`, and
There are some special life cycle scripts that happen only in certain situations.
These scripts happen in addition to the `pre<event>`, `post<event>`, and
`<event>` scripts.
* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`, `dependencies`
**prepare** (since `npm@4.0.0`)
* Runs BEFORE the package is packed, i.e. during `npm publish`
and `npm pack`
* Runs BEFORE the package is packed, i.e.
during `npm publish` and `npm pack`
* Runs on local `npm install` without any arguments
* Runs AFTER `prepublish`, but BEFORE `prepublishOnly`
* Runs for a package if it's being installed as a link through `npm install <folder>`
* NOTE: If a package being installed through git contains a `prepare`
script, its `dependencies` and `devDependencies` will be installed, and
the prepare script will be run, before the package is packaged and
installed.
* NOTE: If a package being installed through git contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed.
* As of `npm@7` these scripts run in the background.
To see the output, run with: `--foreground-scripts`.
**prepublish** (DEPRECATED)
* Does not run during `npm publish`, but does run during `npm ci`
and `npm install`. See below for more info.
* Does not run during `npm publish`, but does run during `npm ci` and `npm install`.
See below for more info.
**prepublishOnly**
* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
@ -78,30 +73,33 @@ situations. These scripts happen in addition to the `pre<event>`, `post<event>`,
**Deprecation Note: prepublish**
Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape).
Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below).
It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074).
As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior.
A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape).
See <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change.
**Use Cases**
If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as:
If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script.
This includes tasks such as:
* Compiling CoffeeScript source code into JavaScript.
* Creating minified versions of JavaScript source code.
* Fetching remote resources that your package will use.
The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:
The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability.
Additionally, this means that:
* You can depend on `coffee-script` as a `devDependency`, and thus
your users don't need to have it installed.
* You don't need to include minifiers in your package, reducing
the size for your users.
* You don't need to rely on your users having `curl` or `wget` or
other system tools on the target machines.
* You can depend on `coffee-script` as a `devDependency`, and thus your users don't need to have it installed.
* You don't need to include minifiers in your package, reducing the size for your users.
* You don't need to rely on your users having `curl` or `wget` or other system tools on the target machines.
#### Dependencies
The `dependencies` script is run any time an `npm` command causes changes to the `node_modules` directory. It is run AFTER the changes have been applied and the `package.json` and `package-lock.json` files have been updated.
The `dependencies` script is run any time an `npm` command causes changes to the `node_modules` directory.
It is run AFTER the changes have been applied and the `package.json` and `package-lock.json` files have been updated.
### Life Cycle Operation Order
@ -138,10 +136,7 @@ These also run when you run `npm install -g <pkg-name>`
* `prepare`
* `postprepare`
If there is a `binding.gyp` file in the root of your package and you
haven't defined your own `install` or `preinstall` scripts, npm will
default the `install` command to compile using node-gyp via `node-gyp
rebuild`
If there is a `binding.gyp` file in the root of your package and you haven't defined your own `install` or `preinstall` scripts, npm will default the `install` command to compile using node-gyp via `node-gyp rebuild`
These are run from the scripts of `<pkg-name>`
@ -167,14 +162,13 @@ These are run from the scripts of `<pkg-name>`
* `postinstall`
* `prepare`
`prepare` is only run if the current directory is a symlink (e.g. with
linked packages)
`prepare` is only run if the current directory is a symlink (e.g.
with linked packages)
#### [`npm restart`](/commands/npm-restart)
If there is a `restart` script defined, these events are run, otherwise
`stop` and `start` are both run if present, including their `pre` and
`post` iterations)
If there is a `restart` script defined, these events are run; otherwise,
`stop` and `start` are both run if present, including their `pre` and `post` iterations)
* `prerestart`
* `restart`
@ -192,9 +186,8 @@ If there is a `restart` script defined, these events are run, otherwise
* `start`
* `poststart`
If there is a `server.js` file in the root of your package, then npm
will default the `start` command to `node server.js`. `prestart` and
`poststart` will still run in this case.
If there is a `server.js` file in the root of your package, then npm will default the `start` command to `node server.js`.
`prestart` and `poststart` will still run in this case.
#### [`npm stop`](/commands/npm-stop)
@ -216,13 +209,15 @@ will default the `start` command to `node server.js`. `prestart` and
#### A Note on a lack of [`npm uninstall`](/commands/npm-uninstall) scripts
While npm v6 had `uninstall` lifecycle scripts, npm v7 does not. Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful.
While npm v6 had `uninstall` lifecycle scripts, npm v7 does not.
Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful.
Reasons for a package removal include:
* a user directly uninstalled this package
* a user uninstalled a dependant package and so this dependency is being uninstalled
* a user uninstalled a dependant package but another package also depends on this version
* a user uninstalled a dependent package and so this dependency is being uninstalled
* a user uninstalled a dependent package but another package also depends on this version
* this version has been merged as a duplicate with another version
* etc.
@ -230,13 +225,15 @@ Due to the lack of necessary context, `uninstall` lifecycle scripts are not impl
### Working Directory for Scripts
Scripts are always run from the root of the package folder, regardless of what the current working directory is when `npm` is invoked. This means your scripts can reliably assume they are running in the package root.
Scripts are always run from the root of the package folder, regardless of what the current working directory is when `npm` is invoked.
This means your scripts can reliably assume they are running in the package root.
If you want your script to behave differently based on the directory you were in when you ran `npm`, you can use the `INIT_CWD` environment variable, which holds the full path you were in when you ran `npm run`.
#### Historical Behavior in Older npm Versions
For npm v6 and earlier, scripts were generally run from the root of the package, but there were rare cases and bugs in older versions where this was not guaranteed. If your package must support very old npm versions, you may wish to add a safeguard in your scripts (for example, by checking process.cwd()).
For npm v6 and earlier, scripts were generally run from the root of the package, but there were rare cases and bugs in older versions where this was not guaranteed.
If your package must support very old npm versions, you may wish to add a safeguard in your scripts (for example, by checking process.cwd()).
For more details, see:
- [npm v7 release notes](https://github.com/npm/cli/releases/tag/v7.0.0)
@ -244,20 +241,16 @@ For more details, see:
### User
When npm is run as root, scripts are always run with the effective uid
and gid of the working directory owner.
When npm is run as root, scripts are always run with the effective uid and gid of the working directory owner.
### Environment
Package scripts run in an environment where many pieces of information
are made available regarding the setup of npm and the current state of
the process.
Package scripts run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process.
#### path
If you depend on modules that define executable scripts, like test
suites, then those executables will be added to the `PATH` for
executing the scripts. So, if your package.json has this:
If you depend on modules that define executable scripts, like test suites, then those executables will be added to the `PATH` for executing the scripts.
So, if your package.json has this:
```json
{
@ -271,31 +264,22 @@ executing the scripts. So, if your package.json has this:
}
```
then you could run `npm start` to execute the `bar` script, which is
exported into the `node_modules/.bin` directory on `npm install`.
then you could run `npm start` to execute the `bar` script, which is exported into the `node_modules/.bin` directory on `npm install`.
#### package.json vars
The package.json fields are tacked onto the `npm_package_` prefix. So,
for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your
package.json file, then your package scripts would have the
`npm_package_name` environment variable set to "foo", and the
`npm_package_version` set to "1.2.5". You can access these variables
in your code with `process.env.npm_package_name` and
`process.env.npm_package_version`, and so on for other fields.
The package.json fields are tacked onto the `npm_package_` prefix.
So, for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then your package scripts would have the `npm_package_name` environment variable set to "foo", and the `npm_package_version` set to "1.2.5". You can access these variables in your code with `process.env.npm_package_name` and `process.env.npm_package_version`, and so on for other fields.
See [`package.json`](/configuring-npm/package-json) for more on package configs.
#### current lifecycle event
Lastly, the `npm_lifecycle_event` environment variable is set to
whichever stage of the cycle is being executed. So, you could have a
single script used for different parts of the process which switches
based on what's currently happening.
Lastly, the `npm_lifecycle_event` environment variable is set to whichever stage of the cycle is being executed.
So, you could have a single script used for different parts of the process which switches based on what's currently happening.
Objects are flattened following this format, so if you had
`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd
see this in the script:
`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this in the script:
```bash
process.env.npm_package_scripts_install === "foo.js"
@ -314,13 +298,12 @@ For example, if your package.json contains this:
}
```
then `scripts/install.js` will be called for the install and post-install
stages of the lifecycle. Since `scripts/install.js` is running for two
different phases, it would be wise in this case to look at the
then `scripts/install.js` will be called for the install and post-install stages of the lifecycle.
Since `scripts/install.js` is running for two different phases, it would be wise in this case to look at the
`npm_lifecycle_event` environment variable.
If you want to run a make command, you can do so. This works just
fine:
If you want to run a make command, you can do so.
This works just fine:
```json
{
@ -334,36 +317,30 @@ fine:
### Exiting
Scripts are run by passing the line as a script argument to `/bin/sh` on POSIX systems or `cmd.exe` on Windows. You can control which shell is used by setting the [`script-shell`](/using-npm/config#script-shell) configuration option.
Scripts are run by passing the line as a script argument to `/bin/sh` on POSIX systems or `cmd.exe` on Windows.
You can control which shell is used by setting the [`script-shell`](/using-npm/config#script-shell) configuration option.
If the script exits with a code other than 0, then this will abort the
process.
If the script exits with a code other than 0, then this will abort the process.
Note that these script files don't have to be Node.js or even
JavaScript programs. They just have to be some kind of executable
file.
Note that these script files don't have to be Node.js or even JavaScript programs.
They just have to be some kind of executable file.
### Best Practices
* Don't exit with a non-zero error code unless you *really* mean it.
If the failure is minor or only will prevent some optional features, then
it's better to just print a warning and exit successfully.
* Try not to use scripts to do what npm can do for you. Read through
[`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable
by simply describing your package appropriately. In general, this
will lead to a more robust and consistent state.
* Inspect the env to determine where to put things. For instance, if
the `npm_config_binroot` environment variable is set to `/home/user/bin`, then
don't try to install executables into `/usr/local/bin`. The user
probably set it up that way for a reason.
* Don't prefix your script commands with "sudo". If root permissions
are required for some reason, then it'll fail with that error, and
the user will sudo the npm command in question.
* Don't use `install`. Use a `.gyp` file for compilation, and `prepare`
for anything else. You should almost never have to explicitly set a
preinstall or install script. If you are doing this, please consider if
there is another option. The only valid use of `install` or `preinstall`
scripts is for compilation which must be done on the target architecture.
If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully.
* Try not to use scripts to do what npm can do for you.
Read through [`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable by simply describing your package appropriately.
In general, this will lead to a more robust and consistent state.
* Inspect the env to determine where to put things.
For instance, if the `npm_config_binroot` environment variable is set to `/home/user/bin`, then don't try to install executables into `/usr/local/bin`.
The user probably set it up that way for a reason.
* Don't prefix your script commands with "sudo". If root permissions are required for some reason, then it'll fail with that error, and the user will sudo the npm command in question.
* Don't use `install`.
Use a `.gyp` file for compilation, and `prepare` for anything else.
You should almost never have to explicitly set a preinstall or install script.
If you are doing this, please consider if there is another option.
The only valid use of `install` or `preinstall` scripts is for compilation which must be done on the target architecture.
### See Also

80
deps/npm/docs/content/using-npm/workspaces.md vendored
View File

@ -6,25 +6,17 @@ description: Working with workspaces
### Description
**Workspaces** is a generic term that refers to the set of features in the
npm cli that provides support for managing multiple packages from your local
file system from within a singular top-level, root package.
**Workspaces** is a generic term that refers to the set of features in the npm cli that provides support for managing multiple packages from your local file system from within a singular top-level, root package.
This set of features makes up for a much more streamlined workflow handling
linked packages from the local file system. It automates the linking process
as part of `npm install` and removes the need to manually use `npm link` in
order to add references to packages that should be symlinked into the current
`node_modules` folder.
This set of features makes up for a much more streamlined workflow handling linked packages from the local file system.
It automates the linking process as part of `npm install` and removes the need to manually use `npm link` in order to add references to packages that should be symlinked into the current `node_modules` folder.
We also refer to these packages being auto-symlinked during `npm install` as a
single **workspace**, meaning it's a nested package within the current local
file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
We also refer to these packages being auto-symlinked during `npm install` as a single **workspace**, meaning it's a nested package within the current local file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
`workspaces` configuration.
### Defining workspaces
Workspaces are usually defined via the `workspaces` property of the
[`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
Workspaces are usually defined via the `workspaces` property of the [`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
```json
{
@ -35,9 +27,7 @@ Workspaces are usually defined via the `workspaces` property of the
}
```
Given the above `package.json` example living at a current working
directory `.` that contains a folder named `packages/a` that itself contains
a `package.json` inside it, defining a Node.js package, e.g:
Given the above `package.json` example living at a current working directory `.` that contains a folder named `packages/a` that itself contains a `package.json` inside it, defining a Node.js package, e.g:
```
.
@ -47,12 +37,9 @@ a `package.json` inside it, defining a Node.js package, e.g:
| `-- package.json
```
The expected result once running `npm install` in this current working
directory `.` is that the folder `packages/a` will get symlinked to the
`node_modules` folder of the current working dir.
The expected result once running `npm install` in this current working directory `.` is that the folder `packages/a` will get symlinked to the `node_modules` folder of the current working dir.
Below is a post `npm install` example, given that same previous example
structure of files and folders:
Below is a post `npm install` example, given that same previous example structure of files and folders:
```
.
@ -67,22 +54,19 @@ structure of files and folders:
### Getting started with workspaces
You may automate the required steps to define a new workspace using
[npm init](/commands/npm-init). For example in a project that already has a
`package.json` defined you can run:
You may automate the required steps to define a new workspace using [npm init](/commands/npm-init).
For example in a project that already has a `package.json` defined you can run:
```
npm init -w ./packages/a
```
This command will create the missing folders and a new `package.json`
file (if needed) while also making sure to properly configure the
This command will create the missing folders and a new `package.json` file (if needed) while also making sure to properly configure the
`"workspaces"` property of your root project `package.json`.
### Adding dependencies to a workspace
It's possible to directly add/remove/update dependencies of your workspaces
using the [`workspace` config](/using-npm/config#workspace).
It's possible to directly add/remove/update dependencies of your workspaces using the [`workspace` config](/using-npm/config#workspace).
For example, assuming the following structure:
@ -96,24 +80,18 @@ For example, assuming the following structure:
`-- package.json
```
If you want to add a dependency named `abbrev` from the registry as a
dependency of your workspace **a**, you may use the workspace config to tell
the npm installer that package should be added as a dependency of the provided
workspace:
If you want to add a dependency named `abbrev` from the registry as a dependency of your workspace **a**, you may use the workspace config to tell the npm installer that package should be added as a dependency of the provided workspace:
```
npm install abbrev -w a
```
Note: other installing commands such as `uninstall`, `ci`, etc will also
respect the provided `workspace` configuration.
Note: other installing commands such as `uninstall`, `ci`, etc will also respect the provided `workspace` configuration.
### Using workspaces
Given the [specifics of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace
by its declared `package.json` `name`. Continuing from the example defined
above, let's also create a Node.js script that will require the workspace `a`
example module, e.g:
Given the [specifics of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace by its declared `package.json` `name`.
Continuing from the example defined above, let's also create a Node.js script that will require the workspace `a` example module, e.g:
```
// ./packages/a/index.js
@ -129,19 +107,15 @@ When running it with:
`node lib/index.js`
This demonstrates how the nature of `node_modules` resolution allows for
**workspaces** to enable a portable workflow for requiring each **workspace**
in such a way that is also easy to [publish](/commands/npm-publish) these
nested workspaces to be consumed elsewhere.
**workspaces** to enable a portable workflow for requiring each **workspace** in such a way that is also easy to [publish](/commands/npm-publish) these nested workspaces to be consumed elsewhere.
### Running commands in the context of workspaces
You can use the `workspace` configuration option to run commands in the context
of a configured workspace.
Additionally, if your current directory is in a workspace, the `workspace`
configuration is implicitly set, and `prefix` is set to the root workspace.
You can use the `workspace` configuration option to run commands in the context of a configured workspace.
Additionally, if your current directory is in a workspace, the `workspace` configuration is implicitly set, and `prefix` is set to the root workspace.
Following is a quick example on how to use the `npm run` command in the context
of nested workspaces. For a project containing multiple workspaces, e.g:
Following is a quick example on how to use the `npm run` command in the context of nested workspaces.
For a project containing multiple workspaces, e.g:
```
.
@ -153,8 +127,8 @@ of nested workspaces. For a project containing multiple workspaces, e.g:
`-- package.json
```
By running a command using the `workspace` option, it's possible to run the
given command in the context of that specific workspace. e.g:
By running a command using the `workspace` option, it's possible to run the given command in the context of that specific workspace.
e.g:
```
npm run test --workspace=a
@ -169,8 +143,7 @@ cd packages/a && npm run test
Either will run the `test` script defined within the
`./packages/a/package.json` file.
Please note that you can also specify this argument multiple times in the
command-line in order to target multiple workspaces, e.g:
Please note that you can also specify this argument multiple times in the command-line in order to target multiple workspaces, e.g:
```
npm run test --workspace=a --workspace=b
@ -181,9 +154,8 @@ Or run the command for each workspace within the 'packages' folder:
npm run test --workspace=packages
```
It's also possible to use the `workspaces` (plural) configuration option to
enable the same behavior but running that command in the context of **all**
configured workspaces. e.g:
It's also possible to use the `workspaces` (plural) configuration option to enable the same behavior but running that command in the context of **all** configured workspaces.
e.g:
```
npm run test --workspaces

2
deps/npm/docs/lib/index.js vendored
View File

@ -38,7 +38,7 @@ const getCommandByDoc = (docFile, docExt) => {
// special case for `npx`:
// `npx` is not technically a command in and of itself,
// so it just needs the usage of npm exex
// so it just needs the usage of npm exec
const srcName = name === 'npx' ? 'exec' : name
const { params, usage = [''], workspaces } = require(`../../lib/commands/${srcName}`)
const usagePrefix = name === 'npx' ? 'npx' : `npm ${name}`

67
deps/npm/docs/output/commands/npm-access.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-access----1161">
<h1 id="----npm-access----1162">
<span>npm-access</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Set access level on published packages</span>
</header>
@ -165,58 +165,23 @@ npm access revoke &lt;scope:team&gt; [&lt;package&gt;]
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>Used to set access controls on private packages.</p>
<p>For all of the subcommands, <code>npm access</code> will perform actions on the packages
in the current working directory if no package name is passed to the
subcommand.</p>
<p>For all of the subcommands, <code>npm access</code> will perform actions on the packages in the current working directory if no package name is passed to the subcommand.</p>
<ul>
<li>
<p>public / restricted (deprecated):
Set a package to be either publicly accessible or restricted.</p>
</li>
<li>
<p>grant / revoke (deprecated):
Add or remove the ability of users and teams to have read-only or read-write
access to a package.</p>
</li>
<li>
<p>2fa-required / 2fa-not-required (deprecated):
Configure whether a package requires that anyone publishing it have two-factor
authentication enabled on their account.</p>
</li>
<li>
<p>ls-packages (deprecated):
Show all of the packages a user or a team is able to access, along with the
access level, except for read-only public packages (it won't print the whole
registry listing)</p>
</li>
<li>
<p>ls-collaborators (deprecated):
Show all of the access privileges for a package. Will only show permissions
for packages to which you have at least read access. If <code>&lt;user&gt;</code> is passed in,
the list is filtered only to teams <em>that</em> user happens to belong to.</p>
</li>
<li>
<p>edit (not implemented)</p>
</li>
<li>grant / revoke:
Add or remove the ability of users and teams to have read-only or read-write access to a package.</li>
</ul>
<h3 id="details">Details</h3>
<p><code>npm access</code> always operates directly on the current registry, configurable
from the command line using <code>--registry=&lt;registry url&gt;</code>.</p>
<p><code>npm access</code> always operates directly on the current registry, configurable from the command line using <code>--registry=&lt;registry url&gt;</code>.</p>
<p>Unscoped packages are <em>always public</em>.</p>
<p>Scoped packages <em>default to restricted</em>, but you can either publish them as
public using <code>npm publish --access=public</code>, or set their access as public using
<code>npm access public</code> after the initial publish.</p>
<p>Scoped packages <em>default to restricted</em>, but you can either publish them as public using <code>npm publish --access=public</code>, or set their access as public using <code>npm access set status=public</code> after the initial publish.</p>
<p>You must have privileges to set the access of a package:</p>
<ul>
<li>You are an owner of an unscoped or scoped package.</li>
<li>You are a member of the team that owns a scope.</li>
<li>You have been given read-write privileges for a package, either as a member
of a team or directly as an owner.</li>
<li>You have been given read-write privileges for a package, either as a member of a team or directly as an owner.</li>
</ul>
<p>If you have two-factor authentication enabled then you'll be prompted to provide a second factor, or may use the <code>--otp=...</code> option to specify it on
the command line.</p>
<p>If your account is not paid, then attempts to publish scoped packages will
fail with an HTTP 402 status code (logically enough), unless you use
<p>If you have two-factor authentication enabled then you'll be prompted to provide a second factor, or may use the <code>--otp=...</code> option to specify it on the command line.</p>
<p>If your account is not paid, then attempts to publish scoped packages will fail with an HTTP 402 status code (logically enough), unless you use
<code>--access=public</code>.</p>
<p>Management of teams and team memberships is done with the <code>npm team</code> command.</p>
<h3 id="configuration">Configuration</h3>
@ -227,8 +192,8 @@ fail with an HTTP 402 status code (logically enough), unless you use
</ul>
<p>Whether or not to output JSON data, rather than the normal output.</p>
<ul>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse() before
saving them to your <code>package.json</code>.</li>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse()
before saving them to your <code>package.json</code>.</li>
</ul>
<p>Not supported by all npm commands.</p>
<h4 id="otp"><code>otp</code></h4>
@ -236,10 +201,10 @@ saving them to your <code>package.json</code>.</li>
<li>Default: null</li>
<li>Type: null or String</li>
</ul>
<p>This is a one-time password from a two-factor authenticator. It's needed
when publishing or changing package permissions with <code>npm access</code>.</p>
<p>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.</p>
<p>This is a one-time password from a two-factor authenticator. It's
needed when publishing or changing package permissions with <code>npm access</code>.</p>
<p>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.</p>
<h4 id="registry"><code>registry</code></h4>
<ul>
<li>Default: "<a href="https://registry.npmjs.org/">https://registry.npmjs.org/</a>"</li>

19
deps/npm/docs/output/commands/npm-adduser.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-adduser----1161">
<h1 id="----npm-adduser----1162">
<span>npm-adduser</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Add a registry user account</span>
</header>
@ -160,12 +160,11 @@ alias: add-user
</code></pre>
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>Create a new user in the specified registry, and save the credentials to
the <code>.npmrc</code> file. If no registry is specified, the default registry
will be used (see <a href="../using-npm/registry.html"><code>registry</code></a>).</p>
<p>When you run <code>npm adduser</code>, the CLI automatically generates a legacy token of <code>publish</code> type. For more information, see <a href="../about-access-tokens#about-legacy-tokens.html">About legacy tokens</a>.</p>
<p>When using <code>legacy</code> for your <code>auth-type</code>, the username, password, and
email are read in from prompts.</p>
<p>Create a new user in the specified registry, and save the credentials to the <code>.npmrc</code> file.
If no registry is specified, the default registry will be used (see <a href="../using-npm/registry.html"><code>registry</code></a>).</p>
<p>When you run <code>npm adduser</code>, the CLI automatically generates a legacy token of <code>publish</code> type.
For more information, see <a href="../about-access-tokens#about-legacy-tokens.html">About legacy tokens</a>.</p>
<p>When using <code>legacy</code> for your <code>auth-type</code>, the username, password, and email are read in from prompts.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="registry"><code>registry</code></h4>
<ul>
@ -199,8 +198,8 @@ npm init --scope=@foo --yes
<li>Default: "web"</li>
<li>Type: "legacy" or "web"</li>
</ul>
<p>What authentication strategy to use with <code>login</code>. Note that if an <code>otp</code>
config is given, this value will always be set to <code>legacy</code>.</p>
<p>What authentication strategy to use with <code>login</code>. Note that if an
<code>otp</code> config is given, this value will always be set to <code>legacy</code>.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../using-npm/registry.html">npm registry</a></li>

268
deps/npm/docs/output/commands/npm-audit.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-audit----1161">
<h1 id="----npm-audit----1162">
<span>npm-audit</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Run a security audit</span>
</header>
@ -157,37 +157,26 @@ npm command-line interface
<pre><code class="language-bash">npm audit [fix|signatures]
</code></pre>
<h3 id="description">Description</h3>
<p>The audit command submits a description of the dependencies configured in
your project to your default registry and asks for a report of known
vulnerabilities. If any vulnerabilities are found, then the impact and
appropriate remediation will be calculated. If the <code>fix</code> argument is
provided, then remediations will be applied to the package tree.</p>
<p>The audit command submits a description of the dependencies configured in your project to your default registry and asks for a report of known vulnerabilities.
If any vulnerabilities are found, then the impact and appropriate remediation will be calculated.
If the <code>fix</code> argument is provided, then remediations will be applied to the package tree.</p>
<p>The command will exit with a 0 exit code if no vulnerabilities were found.</p>
<p>Note that some vulnerabilities cannot be fixed automatically and will
require manual intervention or review. Also note that since <code>npm audit fix</code> runs a full-fledged <code>npm install</code> under the hood, all configs that
apply to the installer will also apply to <code>npm install</code> -- so things like
<code>npm audit fix --package-lock-only</code> will work as expected.</p>
<p>By default, the audit command will exit with a non-zero code if any
vulnerability is found. It may be useful in CI environments to include the
<code>--audit-level</code> parameter to specify the minimum vulnerability level that
will cause the command to fail. This option does not filter the report
output, it simply changes the command's failure threshold.</p>
<p>Note that some vulnerabilities cannot be fixed automatically and will require manual intervention or review.
Also note that since <code>npm audit fix</code> runs a full-fledged <code>npm install</code> under the hood, all configs that apply to the installer will also apply to <code>npm install</code> -- so things like <code>npm audit fix --package-lock-only</code> will work as expected.</p>
<p>By default, the audit command will exit with a non-zero code if any vulnerability is found.
It may be useful in CI environments to include the <code>--audit-level</code> parameter to specify the minimum vulnerability level that will cause the command to fail.
This option does not filter the report output, it simply changes the command's failure threshold.</p>
<h3 id="package-lock">Package lock</h3>
<p>By default npm requires a package-lock or shrinkwrap in order to run the
audit. You can bypass the package lock with <code>--no-package-lock</code> but be
aware the results may be different with every run, since npm will
re-build the dependency tree each time.</p>
<p>By default npm requires a package-lock or shrinkwrap in order to run the audit.
You can bypass the package lock with <code>--no-package-lock</code> but be aware the results may be different with every run, since npm will re-build the dependency tree each time.</p>
<h3 id="audit-signatures">Audit Signatures</h3>
<p>To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.</p>
<p>Registry signatures can be verified using the following <code>audit</code> command:</p>
<pre><code class="language-bash">$ npm audit signatures
</code></pre>
<p>The <code>audit signatures</code> command will also verify the provenance attestations of
downloaded packages. Because provenance attestations are such a new feature,
security features may be added to (or changed in) the attestation format over
time. To ensure that you're always able to verify attestation signatures check
that you're running the latest version of the npm CLI. Please note this often
means updating npm beyond the version that ships with Node.js.</p>
<p>The <code>audit signatures</code> command will also verify the provenance attestations of downloaded packages.
Because provenance attestations are such a new feature, security features may be added to (or changed in) the attestation format over time.
To ensure that you're always able to verify attestation signatures check that you're running the latest version of the npm CLI. Please note this often means updating npm beyond the version that ships with Node.js.</p>
<p>The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:</p>
<ol>
<li>Signatures are provided in the package's <code>packument</code> in each published version within the <code>dist</code> object:</li>
@ -218,39 +207,26 @@ means updating npm beyond the version that ships with Node.js.</p>
<p>Keys response:</p>
<ul>
<li><code>expires</code>: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601 format</a>: <code>YYYY-MM-DDTHH:mm:ss.sssZ</code></li>
<li><code>keydid</code>: sha256 fingerprint of the public key</li>
<li><code>keyid</code>: sha256 fingerprint of the public key</li>
<li><code>keytype</code>: only <code>ecdsa-sha2-nistp256</code> is currently supported by the npm CLI</li>
<li><code>scheme</code>: only <code>ecdsa-sha2-nistp256</code> is currently supported by the npm CLI</li>
<li><code>key</code>: base64 encoded public key</li>
</ul>
<p>See this <a href="https://registry.npmjs.org/-/npm/v1/keys">example key's response from the public npm registry</a>.</p>
<h3 id="audit-endpoints">Audit Endpoints</h3>
<p>There are two audit endpoints that npm may use to fetch vulnerability
information: the <code>Bulk Advisory</code> endpoint and the <code>Quick Audit</code> endpoint.</p>
<p>There are two audit endpoints that npm may use to fetch vulnerability information: the <code>Bulk Advisory</code> endpoint and the <code>Quick Audit</code> endpoint.</p>
<h4 id="bulk-advisory-endpoint">Bulk Advisory Endpoint</h4>
<p>As of version 7, npm uses the much faster <code>Bulk Advisory</code> endpoint to
optimize the speed of calculating audit results.</p>
<p>npm will generate a JSON payload with the name and list of versions of each
package in the tree, and POST it to the default configured registry at
the path <code>/-/npm/v1/security/advisories/bulk</code>.</p>
<p>Any packages in the tree that do not have a <code>version</code> field in their
package.json file will be ignored. If any <code>--omit</code> options are specified
(either via the <a href="../using-npm/config#omit.html"><code>--omit</code> config</a>, or one of the
shorthands such as <code>--production</code>, <code>--only=dev</code>, and so on), then packages will
be omitted from the submitted payload as appropriate.</p>
<p>If the registry responds with an error, or with an invalid response, then
npm will attempt to load advisory data from the <code>Quick Audit</code> endpoint.</p>
<p>The expected result will contain a set of advisory objects for each
dependency that matches the advisory range. Each advisory object contains
a <code>name</code>, <code>url</code>, <code>id</code>, <code>severity</code>, <code>vulnerable_versions</code>, and <code>title</code>.</p>
<p>npm then uses these advisory objects to calculate vulnerabilities and
meta-vulnerabilities of the dependencies within the tree.</p>
<p>As of version 7, npm uses the much faster <code>Bulk Advisory</code> endpoint to optimize the speed of calculating audit results.</p>
<p>npm will generate a JSON payload with the name and list of versions of each package in the tree, and POST it to the default configured registry at the path <code>/-/npm/v1/security/advisories/bulk</code>.</p>
<p>Any packages in the tree that do not have a <code>version</code> field in their package.json file will be ignored.
If any <code>--omit</code> options are specified (either via the <a href="../using-npm/config#omit.html"><code>--omit</code> config</a>, or one of the shorthands such as <code>--production</code>, <code>--only=dev</code>, and so on), then packages will be omitted from the submitted payload as appropriate.</p>
<p>If the registry responds with an error, or with an invalid response, then npm will attempt to load advisory data from the <code>Quick Audit</code> endpoint.</p>
<p>The expected result will contain a set of advisory objects for each dependency that matches the advisory range.
Each advisory object contains a <code>name</code>, <code>url</code>, <code>id</code>, <code>severity</code>, <code>vulnerable_versions</code>, and <code>title</code>.</p>
<p>npm then uses these advisory objects to calculate vulnerabilities and meta-vulnerabilities of the dependencies within the tree.</p>
<h4 id="quick-audit-endpoint">Quick Audit Endpoint</h4>
<p>If the <code>Bulk Advisory</code> endpoint returns an error, or invalid data, npm will
attempt to load advisory data from the <code>Quick Audit</code> endpoint, which is
considerably slower in most cases.</p>
<p>The full package tree as found in <code>package-lock.json</code> is submitted, along
with the following pieces of additional metadata:</p>
<p>If the <code>Bulk Advisory</code> endpoint returns an error, or invalid data, npm will attempt to load advisory data from the <code>Quick Audit</code> endpoint, which is considerably slower in most cases.</p>
<p>The full package tree as found in <code>package-lock.json</code> is submitted, along with the following pieces of additional metadata:</p>
<ul>
<li><code>npm_version</code></li>
<li><code>node_version</code></li>
@ -261,63 +237,38 @@ with the following pieces of additional metadata:</p>
<p>All packages in the tree are submitted to the Quick Audit endpoint.
Omitted dependency types are skipped when generating the report.</p>
<h4 id="scrubbing">Scrubbing</h4>
<p>Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
packages from the submitted report if their name contained a <code>/</code> character,
so as to avoid leaking the names of potentially private packages or git
URLs.</p>
<p>However, in practice, this resulted in audits often failing to properly
detect meta-vulnerabilities, because the tree would appear to be invalid
due to missing dependencies, and prevented the detection of vulnerabilities
in package trees that used git dependencies or private modules.</p>
<p>Out of an abundance of caution, npm versions 5 and 6 would "scrub" any packages from the submitted report if their name contained a <code>/</code> character, so as to avoid leaking the names of potentially private packages or git URLs.</p>
<p>However, in practice, this resulted in audits often failing to properly detect meta-vulnerabilities, because the tree would appear to be invalid due to missing dependencies, and prevented the detection of vulnerabilities in package trees that used git dependencies or private modules.</p>
<p>This scrubbing has been removed from npm as of version 7.</p>
<h4 id="calculating-meta-vulnerabilities-and-remediations">Calculating Meta-Vulnerabilities and Remediations</h4>
<p>npm uses the
<a href="http://npm.im/@npmcli/metavuln-calculator"><code>@npmcli/metavuln-calculator</code></a>
module to turn a set of security advisories into a set of "vulnerability"
objects. A "meta-vulnerability" is a dependency that is vulnerable by
virtue of dependence on vulnerable versions of a vulnerable package.</p>
<p>For example, if the package <code>foo</code> is vulnerable in the range <code>&gt;=1.0.2 &lt;2.0.0</code>, and the package <code>bar</code> depends on <code>foo@^1.1.0</code>, then that version
of <code>bar</code> can only be installed by installing a vulnerable version of <code>foo</code>.
<p>npm uses the <a href="http://npm.im/@npmcli/metavuln-calculator"><code>@npmcli/metavuln-calculator</code></a> module to turn a set of security advisories into a set of "vulnerability" objects.
A "meta-vulnerability" is a dependency that is vulnerable by virtue of dependence on vulnerable versions of a vulnerable package.</p>
<p>For example, if the package <code>foo</code> is vulnerable in the range <code>&gt;=1.0.2 &lt;2.0.0</code>, and the package <code>bar</code> depends on <code>foo@^1.1.0</code>, then that version of <code>bar</code> can only be installed by installing a vulnerable version of <code>foo</code>.
In this case, <code>bar</code> is a "metavulnerability".</p>
<p>Once metavulnerabilities for a given package are calculated, they are
cached in the <code>~/.npm</code> folder and only re-evaluated if the advisory range
changes, or a new version of the package is published (in which case, the
new version is checked for metavulnerable status as well).</p>
<p>If the chain of metavulnerabilities extends all the way to the root
project, and it cannot be updated without changing its dependency ranges,
then <code>npm audit fix</code> will require the <code>--force</code> option to apply the
remediation. If remediations do not require changes to the dependency
ranges, then all vulnerable packages will be updated to a version that does
not have an advisory or metavulnerability posted against it.</p>
<p>Once metavulnerabilities for a given package are calculated, they are cached in the <code>~/.npm</code> folder and only re-evaluated if the advisory range changes, or a new version of the package is published (in which case, the new version is checked for metavulnerable status as well).</p>
<p>If the chain of metavulnerabilities extends all the way to the root project, and it cannot be updated without changing its dependency ranges, then <code>npm audit fix</code> will require the <code>--force</code> option to apply the remediation.
If remediations do not require changes to the dependency ranges, then all vulnerable packages will be updated to a version that does not have an advisory or metavulnerability posted against it.</p>
<h3 id="exit-code">Exit Code</h3>
<p>The <code>npm audit</code> command will exit with a 0 exit code if no vulnerabilities
were found. The <code>npm audit fix</code> command will exit with 0 exit code if no
vulnerabilities are found <em>or</em> if the remediation is able to successfully
fix all vulnerabilities.</p>
<p>If vulnerabilities were found the exit code will depend on the
<a href="../using-npm/config#audit-level.html"><code>audit-level</code> config</a>.</p>
<p>The <code>npm audit</code> command will exit with a 0 exit code if no vulnerabilities were found.
The <code>npm audit fix</code> command will exit with 0 exit code if no vulnerabilities are found <em>or</em> if the remediation is able to successfully fix all vulnerabilities.</p>
<p>If vulnerabilities were found the exit code will depend on the <a href="../using-npm/config#audit-level.html"><code>audit-level</code> config</a>.</p>
<h3 id="examples">Examples</h3>
<p>Scan your project for vulnerabilities and automatically install any compatible
updates to vulnerable dependencies:</p>
<p>Scan your project for vulnerabilities and automatically install any compatible updates to vulnerable dependencies:</p>
<pre><code class="language-bash">$ npm audit fix
</code></pre>
<p>Run <code>audit fix</code> without modifying <code>node_modules</code>, but still updating the
pkglock:</p>
<p>Run <code>audit fix</code> without modifying <code>node_modules</code>, but still updating the pkglock:</p>
<pre><code class="language-bash">$ npm audit fix --package-lock-only
</code></pre>
<p>Skip updating <code>devDependencies</code>:</p>
<pre><code class="language-bash">$ npm audit fix --only=prod
</code></pre>
<p>Have <code>audit fix</code> install SemVer-major updates to toplevel dependencies, not
just SemVer-compatible ones:</p>
<p>Have <code>audit fix</code> install SemVer-major updates to toplevel dependencies, not just SemVer-compatible ones:</p>
<pre><code class="language-bash">$ npm audit fix --force
</code></pre>
<p>Do a dry run to get an idea of what <code>audit fix</code> will do, and <em>also</em> output
install information in JSON format:</p>
<p>Do a dry run to get an idea of what <code>audit fix</code> will do, and <em>also</em> output install information in JSON format:</p>
<pre><code class="language-bash">$ npm audit fix --dry-run --json
</code></pre>
<p>Scan your project for vulnerabilities and just show the details, without
fixing anything:</p>
<p>Scan your project for vulnerabilities and just show the details, without fixing anything:</p>
<pre><code class="language-bash">$ npm audit
</code></pre>
<p>Get the detailed audit report in JSON format:</p>
@ -332,19 +283,20 @@ fixing anything:</p>
<li>Default: null</li>
<li>Type: null, "info", "low", "moderate", "high", "critical", or "none"</li>
</ul>
<p>The minimum level of vulnerability for <code>npm audit</code> to exit with a non-zero
exit code.</p>
<p>The minimum level of vulnerability for <code>npm audit</code> to exit with a
non-zero exit code.</p>
<h4 id="dry-run"><code>dry-run</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>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, <code>install</code>, <code>update</code>,
<code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and <code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg <code>dist-tags</code>,
<code>owner</code>, etc.</p>
<p>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,
<code>install</code>, <code>update</code>, <code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and
<code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg
<code>dist-tags</code>, <code>owner</code>, etc.</p>
<h4 id="force"><code>force</code></h4>
<ul>
<li>Default: false</li>
@ -356,14 +308,16 @@ mistakes, unnecessary performance degradation, and malicious input.</p>
<li>Allow clobbering non-npm files in global installs.</li>
<li>Allow the <code>npm version</code> command to work on an unclean git repository.</li>
<li>Allow deleting the cache folder with <code>npm cache clean</code>.</li>
<li>Allow installing packages that have an <code>engines</code> declaration requiring a
different version of npm.</li>
<li>Allow installing packages that have an <code>engines</code> declaration requiring a
different version of <code>node</code>, even if <code>--engine-strict</code> is enabled.</li>
<li>Allow <code>npm audit fix</code> to install modules outside your stated dependency
range (including SemVer-major changes).</li>
<li>Allow installing packages that have an <code>engines</code> declaration
requiring a different version of npm.</li>
<li>Allow installing packages that have an <code>engines</code> declaration
requiring a different version of <code>node</code>, even if <code>--engine-strict</code> is
enabled.</li>
<li>Allow <code>npm audit fix</code> to install modules outside your stated
dependency range (including SemVer-major changes).</li>
<li>Allow unpublishing all versions of a published package.</li>
<li>Allow conflicting peerDependencies to be installed in the root project.</li>
<li>Allow conflicting peerDependencies to be installed in the root
project.</li>
<li>Implicitly set <code>--yes</code> during <code>npm init</code>.</li>
<li>Allow clobbering existing values in <code>npm pkg</code></li>
<li>Allow unpublishing of entire packages (not just a single version).</li>
@ -377,8 +331,8 @@ recommended that you do not use this option!</p>
</ul>
<p>Whether or not to output JSON data, rather than the normal output.</p>
<ul>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse() before
saving them to your <code>package.json</code>.</li>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse()
before saving them to your <code>package.json</code>.</li>
</ul>
<p>Not supported by all npm commands.</p>
<h4 id="package-lock-only"><code>package-lock-only</code></h4>
@ -386,71 +340,77 @@ saving them to your <code>package.json</code>.</li>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If set to true, the current operation will only use the <code>package-lock.json</code>,
ignoring <code>node_modules</code>.</p>
<p>If set to true, the current operation will only use the
<code>package-lock.json</code>, ignoring <code>node_modules</code>.</p>
<p>For <code>update</code> this means only the <code>package-lock.json</code> will be updated,
instead of checking <code>node_modules</code> and downloading dependencies.</p>
<p>For <code>list</code> this means the output will be based on the tree described by the
<code>package-lock.json</code>, rather than the contents of <code>node_modules</code>.</p>
<p>For <code>list</code> this means the output will be based on the tree described
by the <code>package-lock.json</code>, rather than the contents of
<code>node_modules</code>.</p>
<h4 id="package-lock2"><code>package-lock</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>If set to false, then ignore <code>package-lock.json</code> files when installing. This
will also prevent <em>writing</em> <code>package-lock.json</code> if <code>save</code> is true.</p>
<p>If set to false, then ignore <code>package-lock.json</code> files when
installing. This will also prevent <em>writing</em> <code>package-lock.json</code> if
<code>save</code> is true.</p>
<h4 id="omit"><code>omit</code></h4>
<ul>
<li>Default: 'dev' if the <code>NODE_ENV</code> environment variable is set to
'production', otherwise empty.</li>
'production'; otherwise, empty.</li>
<li>Type: "dev", "optional", or "peer" (can be set multiple times)</li>
</ul>
<p>Dependency types to omit from the installation tree on disk.</p>
<p>Note that these dependencies <em>are</em> still resolved and added to the
<code>package-lock.json</code> or <code>npm-shrinkwrap.json</code> file. They are just not
physically installed on disk.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists, then
it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code> environment
variable will be set to <code>'production'</code> for all lifecycle scripts.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists,
then it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code>
environment variable will be set to <code>'production'</code> for all lifecycle
scripts.</p>
<h4 id="include"><code>include</code></h4>
<ul>
<li>Default:</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple times)</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)</li>
</ul>
<p>Option that allows for defining which types of dependencies to install.</p>
<p>Option that allows for defining which types of dependencies to
install.</p>
<p>This is the inverse of <code>--omit=&lt;type&gt;</code>.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted, regardless of
the order in which omit/include are specified on the command-line.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.</p>
<h4 id="foreground-scripts"><code>foreground-scripts</code></h4>
<ul>
<li>Default: <code>false</code> unless when using <code>npm pack</code> or <code>npm publish</code> where it
defaults to <code>true</code></li>
<li>Default: <code>false</code> unless when using <code>npm pack</code> or <code>npm publish</code> where
it defaults to <code>true</code></li>
<li>Type: Boolean</li>
</ul>
<p>Run all build scripts (ie, <code>preinstall</code>, <code>install</code>, and <code>postinstall</code>)
scripts for installed packages in the foreground process, sharing standard
input, output, and error with the main npm process.</p>
<p>Note that this will generally make installs run slower, and be much noisier,
but can be useful for debugging.</p>
<p>Run all build scripts (ie, <code>preinstall</code>, <code>install</code>, and
<code>postinstall</code>) scripts for installed packages in the foreground
process, sharing standard input, output, and error with the main npm
process.</p>
<p>Note that this will generally make installs run slower, and be much
noisier, but can be useful for debugging.</p>
<h4 id="ignore-scripts"><code>ignore-scripts</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If true, npm does not run scripts specified in package.json files.</p>
<p>Note that commands explicitly intended to run a particular script, such as
<code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still
run their intended script if <code>ignore-scripts</code> is set, but they will <em>not</em>
run any pre- or post-scripts.</p>
<p>Note that commands explicitly intended to run a particular script,
such as <code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still run their intended script if <code>ignore-scripts</code> is set,
but they will <em>not</em> run any pre- or post-scripts.</p>
<h4 id="workspace"><code>workspace</code></h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -458,9 +418,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -469,13 +429,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -484,18 +445,19 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="install-links"><code>install-links</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.</p>
<p>When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-install.html">npm install</a></li>

43
deps/npm/docs/output/commands/npm-bugs.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-bugs----1161">
<h1 id="----npm-bugs----1162">
<span>npm-bugs</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Report bugs for a package in a web browser</span>
</header>
@ -159,11 +159,8 @@ npm command-line interface
alias: issues
</code></pre>
<h3 id="description">Description</h3>
<p>This command tries to guess at the likely location of a package's bug
tracker URL or the <code>mailto</code> URL of the support email, and then tries to
open it using the <a href="../using-npm/config#browser.html"><code>--browser</code> config</a> param. If no
package name is provided, it will search for a <code>package.json</code> in the current
folder and use the <code>name</code> property.</p>
<p>This command tries to guess at the likely location of a package's bug tracker URL or the <code>mailto</code> URL of the support email, and then tries to open it using the <a href="../using-npm/config#browser.html"><code>--browser</code> config</a> param.
If no package name is provided, it will search for a <code>package.json</code> in the current folder and use the <code>name</code> property.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="browser"><code>browser</code></h4>
<ul>
@ -185,9 +182,9 @@ terminal.</p>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -195,9 +192,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -206,13 +203,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -221,9 +219,10 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h3 id="see-also">See Also</h3>
<ul>

25
deps/npm/docs/output/commands/npm-cache.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-cache----1161">
<h1 id="----npm-cache----1162">
<span>npm-cache</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Manipulates packages cache</span>
</header>
@ -170,11 +170,13 @@ Also used to view info about entries in the <code>npm exec</code> (aka <code>npx
<ul>
<li>
<p>add:
Add the specified packages to the local cache. This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly.</p>
Add the specified packages to the local cache.
This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly.</p>
</li>
<li>
<p>clean:
Delete a single entry or all entries out of the cache folder. Note that this is typically unnecessary, as npm's cache is self-healing and resistant to data corruption issues.</p>
Delete a single entry or all entries out of the cache folder.
Note that this is typically unnecessary, as npm's cache is self-healing and resistant to data corruption issues.</p>
</li>
<li>
<p>ls:
@ -201,12 +203,19 @@ Get detailed information about given entries in the npx cache.</p>
</li>
</ul>
<h3 id="details">Details</h3>
<p>npm stores cache data in an opaque directory within the configured <code>cache</code>, named <code>_cacache</code>. This directory is a <a href="http://npm.im/cacache"><code>cacache</code></a>-based content-addressable cache that stores all http request data as well as other package-related data. This directory is primarily accessed through <code>pacote</code>, the library responsible for all package fetching as of npm@5.</p>
<p>All data that passes through the cache is fully verified for integrity on both insertion and extraction. Cache corruption will either trigger an error, or signal to <code>pacote</code> that the data must be refetched, which it will do automatically. For this reason, it should never be necessary to clear the cache for any reason other than reclaiming disk space, thus why <code>clean</code> now requires <code>--force</code> to run.</p>
<p>There is currently no method exposed through npm to inspect or directly manage the contents of this cache. In order to access it, <code>cacache</code> must be used directly.</p>
<p>npm stores cache data in an opaque directory within the configured <code>cache</code>, named <code>_cacache</code>.
This directory is a <a href="http://npm.im/cacache"><code>cacache</code></a>-based content-addressable cache that stores all http request data as well as other package-related data.
This directory is primarily accessed through <code>pacote</code>, the library responsible for all package fetching as of npm@5.</p>
<p>All data that passes through the cache is fully verified for integrity on both insertion and extraction.
Cache corruption will either trigger an error, or signal to <code>pacote</code> that the data must be refetched, which it will do automatically.
For this reason, it should never be necessary to clear the cache for any reason other than reclaiming disk space, thus why <code>clean</code> now requires <code>--force</code> to run.</p>
<p>There is currently no method exposed through npm to inspect or directly manage the contents of this cache.
In order to access it, <code>cacache</code> must be used directly.</p>
<p>npm will not remove data by itself: the cache will grow as new packages are installed.</p>
<h3 id="a-note-about-the-caches-design">A note about the cache's design</h3>
<p>The npm cache is strictly a cache: it should not be relied upon as a persistent and reliable data store for package data. npm makes no guarantee that a previously-cached piece of data will be available later, and will automatically delete corrupted contents. The primary guarantee that the cache makes is that, if it does return data, that data will be exactly the data that was inserted.</p>
<p>The npm cache is strictly a cache: it should not be relied upon as a persistent and reliable data store for package data.
npm makes no guarantee that a previously-cached piece of data will be available later, and will automatically delete corrupted contents.
The primary guarantee that the cache makes is that, if it does return data, that data will be exactly the data that was inserted.</p>
<p>To run an offline verification of existing cache contents, use <code>npm cache verify</code>.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="cache"><code>cache</code></h4>

179
deps/npm/docs/output/commands/npm-ci.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-ci----1161">
<h1 id="----npm-ci----1162">
<span>npm-ci</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Clean install a project</span>
</header>
@ -159,28 +159,21 @@ npm command-line interface
aliases: clean-install, ic, install-clean, isntall-clean
</code></pre>
<h3 id="description">Description</h3>
<p>This command is similar to <a href="../commands/npm-install.html"><code>npm install</code></a>, except
it's meant to be used in automated environments such as test platforms,
continuous integration, and deployment -- or any situation where you want
to make sure you're doing a clean install of your dependencies.</p>
<p>This command is similar to <a href="../commands/npm-install.html"><code>npm install</code></a>, except it's meant to be used in automated environments such as test platforms, continuous integration, and deployment -- or any situation where you want to make sure you're doing a clean install of your dependencies.</p>
<p>The main differences between using <code>npm install</code> and <code>npm ci</code> are:</p>
<ul>
<li>The project <strong>must</strong> have an existing <code>package-lock.json</code> or
<code>npm-shrinkwrap.json</code>.</li>
<li>If dependencies in the package lock do not match those in <code>package.json</code>,
<code>npm ci</code> will exit with an error, instead of updating the package lock.</li>
<li><code>npm ci</code> can only install entire projects at a time: individual
dependencies cannot be added with this command.</li>
<li>If a <code>node_modules</code> is already present, it will be automatically removed
before <code>npm ci</code> begins its install.</li>
<li><code>npm ci</code> can only install entire projects at a time: individual dependencies cannot be added with this command.</li>
<li>If a <code>node_modules</code> is already present, it will be automatically removed before <code>npm ci</code> begins its install.</li>
<li>It will never write to <code>package.json</code> or any of the package-locks:
installs are essentially frozen.</li>
</ul>
<p>NOTE: If you create your <code>package-lock.json</code> file by running <code>npm install</code>
with flags that can affect the shape of your dependency tree, such as
<code>--legacy-peer-deps</code> or <code>--install-links</code>, you <em>must</em> provide the same
flags to <code>npm ci</code> or you are likely to encounter errors. An easy way to do
this is to run, for example,
<p>NOTE: If you create your <code>package-lock.json</code> file by running <code>npm install</code> with flags that can affect the shape of your dependency tree, such as
<code>--legacy-peer-deps</code> or <code>--install-links</code>, you <em>must</em> provide the same flags to <code>npm ci</code> or you are likely to encounter errors.
An easy way to do this is to run, for example,
<code>npm config set legacy-peer-deps=true --location=project</code> and commit the
<code>.npmrc</code> file to your repo.</p>
<h3 id="example">Example</h3>
@ -210,11 +203,12 @@ cache:
<li>Type: "hoisted", "nested", "shallow", or "linked"</li>
</ul>
<p>Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.</p>
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.</p>
<h4 id="legacy-bundling"><code>legacy-bundling</code></h4>
<ul>
<li>Default: false</li>
@ -222,10 +216,10 @@ link in place, unhoisted.</p>
<li>DEPRECATED: This option has been deprecated in favor of
<code>--install-strategy=nested</code></li>
</ul>
<p>Instead of hoisting package installs in <code>node_modules</code>, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<p>Instead of hoisting package installs in <code>node_modules</code>, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<h4 id="global-style"><code>global-style</code></h4>
<ul>
<li>Default: false</li>
@ -233,77 +227,82 @@ de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<li>DEPRECATED: This option has been deprecated in favor of
<code>--install-strategy=shallow</code></li>
</ul>
<p>Only install direct dependencies in the top level <code>node_modules</code>, but hoist
on deeper dependencies. Sets <code>--install-strategy=shallow</code>.</p>
<p>Only install direct dependencies in the top level <code>node_modules</code>, but
hoist on deeper dependencies. Sets <code>--install-strategy=shallow</code>.</p>
<h4 id="omit"><code>omit</code></h4>
<ul>
<li>Default: 'dev' if the <code>NODE_ENV</code> environment variable is set to
'production', otherwise empty.</li>
'production'; otherwise, empty.</li>
<li>Type: "dev", "optional", or "peer" (can be set multiple times)</li>
</ul>
<p>Dependency types to omit from the installation tree on disk.</p>
<p>Note that these dependencies <em>are</em> still resolved and added to the
<code>package-lock.json</code> or <code>npm-shrinkwrap.json</code> file. They are just not
physically installed on disk.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists, then
it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code> environment
variable will be set to <code>'production'</code> for all lifecycle scripts.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists,
then it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code>
environment variable will be set to <code>'production'</code> for all lifecycle
scripts.</p>
<h4 id="include"><code>include</code></h4>
<ul>
<li>Default:</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple times)</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)</li>
</ul>
<p>Option that allows for defining which types of dependencies to install.</p>
<p>Option that allows for defining which types of dependencies to
install.</p>
<p>This is the inverse of <code>--omit=&lt;type&gt;</code>.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted, regardless of
the order in which omit/include are specified on the command-line.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.</p>
<h4 id="strict-peer-deps"><code>strict-peer-deps</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If set to <code>true</code>, and <code>--legacy-peer-deps</code> is not set, then <em>any</em>
conflicting <code>peerDependencies</code> will be treated as an install failure, even
if npm could reasonably guess the appropriate resolution based on non-peer
dependency relationships.</p>
<p>By default, conflicting <code>peerDependencies</code> 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 <code>peerDependencies</code> object.</p>
<p>When such an override is performed, a warning is printed, explaining the
conflict and the packages involved. If <code>--strict-peer-deps</code> is set, then
this warning is treated as a failure.</p>
conflicting <code>peerDependencies</code> will be treated as an install failure,
even if npm could reasonably guess the appropriate resolution based
on non-peer dependency relationships.</p>
<p>By default, conflicting <code>peerDependencies</code> 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
<code>peerDependencies</code> object.</p>
<p>When such an override is performed, a warning is printed, explaining
the conflict and the packages involved. If <code>--strict-peer-deps</code> is
set, then this warning is treated as a failure.</p>
<h4 id="foreground-scripts"><code>foreground-scripts</code></h4>
<ul>
<li>Default: <code>false</code> unless when using <code>npm pack</code> or <code>npm publish</code> where it
defaults to <code>true</code></li>
<li>Default: <code>false</code> unless when using <code>npm pack</code> or <code>npm publish</code> where
it defaults to <code>true</code></li>
<li>Type: Boolean</li>
</ul>
<p>Run all build scripts (ie, <code>preinstall</code>, <code>install</code>, and <code>postinstall</code>)
scripts for installed packages in the foreground process, sharing standard
input, output, and error with the main npm process.</p>
<p>Note that this will generally make installs run slower, and be much noisier,
but can be useful for debugging.</p>
<p>Run all build scripts (ie, <code>preinstall</code>, <code>install</code>, and
<code>postinstall</code>) scripts for installed packages in the foreground
process, sharing standard input, output, and error with the main npm
process.</p>
<p>Note that this will generally make installs run slower, and be much
noisier, but can be useful for debugging.</p>
<h4 id="ignore-scripts"><code>ignore-scripts</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If true, npm does not run scripts specified in package.json files.</p>
<p>Note that commands explicitly intended to run a particular script, such as
<code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still
run their intended script if <code>ignore-scripts</code> is set, but they will <em>not</em>
run any pre- or post-scripts.</p>
<p>Note that commands explicitly intended to run a particular script,
such as <code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still run their intended script if <code>ignore-scripts</code> is set,
but they will <em>not</em> run any pre- or post-scripts.</p>
<h4 id="audit"><code>audit</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for <a href="../commands/npm-audit.html"><code>npm audit</code></a> for details on what is
submitted.</p>
<p>When "true" submit audit reports alongside the current npm command to
the default registry and all registries configured for scopes. See
the documentation for <a href="../commands/npm-audit.html"><code>npm audit</code></a> for details
on what is submitted.</p>
<h4 id="bin-links"><code>bin-links</code></h4>
<ul>
<li>Default: true</li>
@ -311,35 +310,37 @@ submitted.</p>
</ul>
<p>Tells npm to create symlinks (or <code>.cmd</code> shims on Windows) for package
executables.</p>
<p>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.</p>
<p>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.</p>
<h4 id="fund"><code>fund</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>When "true" displays the message at the end of each <code>npm install</code>
acknowledging the number of dependencies looking for funding. See <a href="../commands/npm-fund.html"><code>npm fund</code></a> for details.</p>
acknowledging the number of dependencies looking for funding. See
<a href="../commands/npm-fund.html"><code>npm fund</code></a> for details.</p>
<h4 id="dry-run"><code>dry-run</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>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, <code>install</code>, <code>update</code>,
<code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and <code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg <code>dist-tags</code>,
<code>owner</code>, etc.</p>
<p>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,
<code>install</code>, <code>update</code>, <code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and
<code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg
<code>dist-tags</code>, <code>owner</code>, etc.</p>
<h4 id="workspace"><code>workspace</code></h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -347,9 +348,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -358,13 +359,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -373,18 +375,19 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="install-links"><code>install-links</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.</p>
<p>When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-install.html">npm install</a></li>

17
deps/npm/docs/output/commands/npm-completion.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-completion----1161">
<h1 id="----npm-completion----1162">
<span>npm-completion</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Tab Completion for npm</span>
</header>
@ -159,20 +159,15 @@ npm command-line interface
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>Enables tab-completion in all npm commands.</p>
<p>The synopsis above
loads the completions into your current shell. Adding it to
your ~/.bashrc or ~/.zshrc will make the completions available
everywhere:</p>
<p>The synopsis above loads the completions into your current shell.
Adding it to your ~/.bashrc or ~/.zshrc will make the completions available everywhere:</p>
<pre><code class="language-bash">npm completion &gt;&gt; ~/.bashrc
npm completion &gt;&gt; ~/.zshrc
</code></pre>
<p>You may of course also pipe the output of <code>npm completion</code> to a file
such as <code>/usr/local/etc/bash_completion.d/npm</code> or
<p>You may of course also pipe the output of <code>npm completion</code> to a file such as <code>/usr/local/etc/bash_completion.d/npm</code> or
<code>/etc/bash_completion.d/npm</code> if you have a system that will read
that file for you.</p>
<p>When <code>COMP_CWORD</code>, <code>COMP_LINE</code>, and <code>COMP_POINT</code> are defined in the
environment, <code>npm completion</code> acts in "plumbing mode", and outputs
completions based on the arguments.</p>
<p>When <code>COMP_CWORD</code>, <code>COMP_LINE</code>, and <code>COMP_POINT</code> are defined in the environment, <code>npm completion</code> acts in "plumbing mode", and outputs completions based on the arguments.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../using-npm/developers.html">npm developers</a></li>

71
deps/npm/docs/output/commands/npm-config.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-config----1161">
<h1 id="----npm-config----1162">
<span>npm-config</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Manage the npm configuration files</span>
</header>
@ -165,38 +165,33 @@ alias: c
</code></pre>
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>npm gets its config settings from the command line, environment
variables, <code>npmrc</code> files, and in some cases, the <code>package.json</code> file.</p>
<p>See <a href="../configuring-npm/npmrc.html">npmrc</a> for more information about the npmrc
files.</p>
<p>See <a href="../using-npm/config.html">config</a> for a more thorough explanation of the
mechanisms involved, and a full list of config options available.</p>
<p>The <code>npm config</code> command can be used to update and edit the contents
of the user and global npmrc files.</p>
<p>npm gets its config settings from the command line, environment variables, <code>npmrc</code> files, and in some cases, the <code>package.json</code> file.</p>
<p>See <a href="../configuring-npm/npmrc.html">npmrc</a> for more information about the npmrc files.</p>
<p>See <a href="../using-npm/config.html">config</a> for a more thorough explanation of the mechanisms involved, and a full list of config options available.</p>
<p>The <code>npm config</code> command can be used to update and edit the contents of the user and global npmrc files.</p>
<h3 id="sub-commands">Sub-commands</h3>
<p>Config supports the following sub-commands:</p>
<h4 id="set">set</h4>
<pre><code class="language-bash">npm config set key=value [key=value...]
npm set key=value [key=value...]
</code></pre>
<p>Sets each of the config keys to the value provided. Modifies the user configuration
file unless <a href="../commands/npm-config#location.html"><code>location</code></a> is passed.</p>
<p>Sets each of the config keys to the value provided.
Modifies the user configuration file unless <a href="../commands/npm-config#location.html"><code>location</code></a> is passed.</p>
<p>If value is omitted, the key will be removed from your config file entirely.</p>
<p>Note: for backwards compatibility, <code>npm config set key value</code> is supported
as an alias for <code>npm config set key=value</code>.</p>
<p>Note: for backwards compatibility, <code>npm config set key value</code> is supported as an alias for <code>npm config set key=value</code>.</p>
<h4 id="get">get</h4>
<pre><code class="language-bash">npm config get [key ...]
npm get [key ...]
</code></pre>
<p>Echo the config value(s) to stdout.</p>
<p>If multiple keys are provided, then the values will be prefixed with the
key names.</p>
<p>If multiple keys are provided, then the values will be prefixed with the key names.</p>
<p>If no keys are provided, then this command behaves the same as <code>npm config list</code>.</p>
<h4 id="list">list</h4>
<pre><code class="language-bash">npm config list
</code></pre>
<p>Show all the config settings. Use <code>-l</code> to also show defaults. Use <code>--json</code>
to show the settings in json format.</p>
<p>Show all the config settings.
Use <code>-l</code> to also show defaults.
Use <code>--json</code> to show the settings in json format.</p>
<h4 id="delete">delete</h4>
<pre><code class="language-bash">npm config delete key [key ...]
</code></pre>
@ -204,14 +199,14 @@ to show the settings in json format.</p>
<h4 id="edit2">edit</h4>
<pre><code class="language-bash">npm config edit
</code></pre>
<p>Opens the config file in an editor. Use the <code>--global</code> flag to edit the
global config.</p>
<p>Opens the config file in an editor.
Use the <code>--global</code> flag to edit the global config.</p>
<h4 id="fix">fix</h4>
<pre><code class="language-bash">npm config fix
</code></pre>
<p>Attempts to repair invalid configuration items. Usually this means
attaching authentication config (i.e. <code>_auth</code>, <code>_authToken</code>) to the
configured <code>registry</code>.</p>
<p>Attempts to repair invalid configuration items.
Usually this means attaching authentication config (i.e.
<code>_auth</code>, <code>_authToken</code>) to the configured <code>registry</code>.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="json"><code>json</code></h4>
<ul>
@ -220,8 +215,8 @@ configured <code>registry</code>.</p>
</ul>
<p>Whether or not to output JSON data, rather than the normal output.</p>
<ul>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse() before
saving them to your <code>package.json</code>.</li>
<li>In <code>npm pkg set</code> it enables parsing set values with JSON.parse()
before saving them to your <code>package.json</code>.</li>
</ul>
<p>Not supported by all npm commands.</p>
<h4 id="global"><code>global</code></h4>
@ -229,12 +224,13 @@ saving them to your <code>package.json</code>.</li>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>Operates in "global" mode, so that packages are installed into the <code>prefix</code>
folder instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in behavior.</p>
<p>Operates in "global" mode, so that packages are installed into the
<code>prefix</code> folder instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in
behavior.</p>
<ul>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder, instead
of the current working directory.</li>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder,
instead of the current working directory.</li>
<li>bin files are linked to <code>{prefix}/bin</code></li>
<li>man pages are linked to <code>{prefix}/share/man</code></li>
</ul>
@ -247,17 +243,18 @@ of the current working directory.</li>
<p>The command to run for <code>npm edit</code> and <code>npm config edit</code>.</p>
<h4 id="location"><code>location</code></h4>
<ul>
<li>Default: "user" unless <code>--global</code> is passed, which will also set this value
to "global"</li>
<li>Default: "user" unless <code>--global</code> is passed, which will also set this
value to "global"</li>
<li>Type: "global", "user", or "project"</li>
</ul>
<p>When passed to <code>npm config</code> this refers to which config file to use.</p>
<p>When set to "global" mode, packages are installed into the <code>prefix</code> folder
instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in behavior.</p>
<p>When set to "global" mode, packages are installed into the <code>prefix</code>
folder instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in
behavior.</p>
<ul>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder, instead
of the current working directory.</li>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder,
instead of the current working directory.</li>
<li>bin files are linked to <code>{prefix}/bin</code></li>
<li>man pages are linked to <code>{prefix}/share/man</code></li>
</ul>

182
deps/npm/docs/output/commands/npm-dedupe.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-dedupe----1161">
<h1 id="----npm-dedupe----1162">
<span>npm-dedupe</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Reduce duplication in the package tree</span>
</header>
@ -159,9 +159,7 @@ npm command-line interface
alias: ddp
</code></pre>
<h3 id="description">Description</h3>
<p>Searches the local package tree and attempts to simplify the overall
structure by moving dependencies further up the tree, where they can
be more effectively shared by multiple dependent packages.</p>
<p>Searches the local package tree and attempts to simplify the overall structure by moving dependencies further up the tree, where they can be more effectively shared by multiple dependent packages.</p>
<p>For example, consider this dependency graph:</p>
<pre><code>a
+-- b &lt;-- depends on c@1.0.x
@ -175,9 +173,7 @@ be more effectively shared by multiple dependent packages.</p>
+-- d
`-- c@1.0.10
</code></pre>
<p>Because of the hierarchical nature of node's module lookup, b and d
will both get their dependency met by the single c package at the root
level of the tree.</p>
<p>Because of the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree.</p>
<p>In some cases, you may have a dependency graph like this:</p>
<pre><code>a
+-- b &lt;-- depends on c@1.0.x
@ -185,23 +181,15 @@ level of the tree.</p>
`-- d &lt;-- depends on c@1.x
`-- c@1.9.9
</code></pre>
<p>During the installation process, the <code>c@1.0.3</code> dependency for <code>b</code> was
placed in the root of the tree. Though <code>d</code>'s dependency on <code>c@1.x</code> could
have been satisfied by <code>c@1.0.3</code>, the newer <code>c@1.9.0</code> dependency was used,
because npm favors updates by default, even when doing so causes
duplication.</p>
<p>Running <code>npm dedupe</code> will cause npm to note the duplication and
re-evaluate, deleting the nested <code>c</code> module, because the one in the root is
sufficient.</p>
<p>To prefer deduplication over novelty during the installation process, run
<code>npm install --prefer-dedupe</code> or <code>npm config set prefer-dedupe true</code>.</p>
<p>Arguments are ignored. Dedupe always acts on the entire tree.</p>
<p>Note that this operation transforms the dependency tree, but will never
result in new modules being installed.</p>
<p>During the installation process, the <code>c@1.0.3</code> dependency for <code>b</code> was placed in the root of the tree.
Though <code>d</code>'s dependency on <code>c@1.x</code> could have been satisfied by <code>c@1.0.3</code>, the newer <code>c@1.9.0</code> dependency was used, because npm favors updates by default, even when doing so causes duplication.</p>
<p>Running <code>npm dedupe</code> will cause npm to note the duplication and re-evaluate, deleting the nested <code>c</code> module, because the one in the root is sufficient.</p>
<p>To prefer deduplication over novelty during the installation process, run <code>npm install --prefer-dedupe</code> or <code>npm config set prefer-dedupe true</code>.</p>
<p>Arguments are ignored.
Dedupe always acts on the entire tree.</p>
<p>Note that this operation transforms the dependency tree, but will never result in new modules being installed.</p>
<p>Using <code>npm find-dupes</code> will run the command in <code>--dry-run</code> mode.</p>
<p>Note: <code>npm dedupe</code> will never update the semver values of direct
dependencies in your project <code>package.json</code>, if you want to update
values in <code>package.json</code> you can run: <code>npm update --save</code> instead.</p>
<p>Note: <code>npm dedupe</code> will never update the semver values of direct dependencies in your project <code>package.json</code>, if you want to update values in <code>package.json</code> you can run: <code>npm update --save</code> instead.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="install-strategy"><code>install-strategy</code></h4>
<ul>
@ -209,11 +197,12 @@ values in <code>package.json</code> you can run: <code>npm update --save</code>
<li>Type: "hoisted", "nested", "shallow", or "linked"</li>
</ul>
<p>Sets the strategy for installing packages in node_modules. hoisted
(default): Install non-duplicated in top-level, and duplicated as necessary
within directory structure. nested: (formerly --legacy-bundling) install in
place, no hoisting. shallow (formerly --global-style) only install direct
deps at top-level. linked: (experimental) install in node_modules/.store,
link in place, unhoisted.</p>
(default): Install non-duplicated in top-level, and duplicated as
necessary within directory structure. nested: (formerly
--legacy-bundling) install in place, no hoisting. shallow (formerly
--global-style) only install direct deps at top-level. linked:
(experimental) install in node_modules/.store, link in place,
unhoisted.</p>
<h4 id="legacy-bundling"><code>legacy-bundling</code></h4>
<ul>
<li>Default: false</li>
@ -221,10 +210,10 @@ link in place, unhoisted.</p>
<li>DEPRECATED: This option has been deprecated in favor of
<code>--install-strategy=nested</code></li>
</ul>
<p>Instead of hoisting package installs in <code>node_modules</code>, install packages in
the same manner that they are depended on. This may cause very deep
directory structures and duplicate package installs as there is no
de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<p>Instead of hoisting package installs in <code>node_modules</code>, install
packages in the same manner that they are depended on. This may cause
very deep directory structures and duplicate package installs as
there is no de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<h4 id="global-style"><code>global-style</code></h4>
<ul>
<li>Default: false</li>
@ -232,73 +221,78 @@ de-duplicating. Sets <code>--install-strategy=nested</code>.</p>
<li>DEPRECATED: This option has been deprecated in favor of
<code>--install-strategy=shallow</code></li>
</ul>
<p>Only install direct dependencies in the top level <code>node_modules</code>, but hoist
on deeper dependencies. Sets <code>--install-strategy=shallow</code>.</p>
<p>Only install direct dependencies in the top level <code>node_modules</code>, but
hoist on deeper dependencies. Sets <code>--install-strategy=shallow</code>.</p>
<h4 id="strict-peer-deps"><code>strict-peer-deps</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If set to <code>true</code>, and <code>--legacy-peer-deps</code> is not set, then <em>any</em>
conflicting <code>peerDependencies</code> will be treated as an install failure, even
if npm could reasonably guess the appropriate resolution based on non-peer
dependency relationships.</p>
<p>By default, conflicting <code>peerDependencies</code> 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 <code>peerDependencies</code> object.</p>
<p>When such an override is performed, a warning is printed, explaining the
conflict and the packages involved. If <code>--strict-peer-deps</code> is set, then
this warning is treated as a failure.</p>
conflicting <code>peerDependencies</code> will be treated as an install failure,
even if npm could reasonably guess the appropriate resolution based
on non-peer dependency relationships.</p>
<p>By default, conflicting <code>peerDependencies</code> 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
<code>peerDependencies</code> object.</p>
<p>When such an override is performed, a warning is printed, explaining
the conflict and the packages involved. If <code>--strict-peer-deps</code> is
set, then this warning is treated as a failure.</p>
<h4 id="package-lock"><code>package-lock</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>If set to false, then ignore <code>package-lock.json</code> files when installing. This
will also prevent <em>writing</em> <code>package-lock.json</code> if <code>save</code> is true.</p>
<p>If set to false, then ignore <code>package-lock.json</code> files when
installing. This will also prevent <em>writing</em> <code>package-lock.json</code> if
<code>save</code> is true.</p>
<h4 id="omit"><code>omit</code></h4>
<ul>
<li>Default: 'dev' if the <code>NODE_ENV</code> environment variable is set to
'production', otherwise empty.</li>
'production'; otherwise, empty.</li>
<li>Type: "dev", "optional", or "peer" (can be set multiple times)</li>
</ul>
<p>Dependency types to omit from the installation tree on disk.</p>
<p>Note that these dependencies <em>are</em> still resolved and added to the
<code>package-lock.json</code> or <code>npm-shrinkwrap.json</code> file. They are just not
physically installed on disk.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists, then
it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code> environment
variable will be set to <code>'production'</code> for all lifecycle scripts.</p>
<p>If a package type appears in both the <code>--include</code> and <code>--omit</code> lists,
then it will be included.</p>
<p>If the resulting omit list includes <code>'dev'</code>, then the <code>NODE_ENV</code>
environment variable will be set to <code>'production'</code> for all lifecycle
scripts.</p>
<h4 id="include"><code>include</code></h4>
<ul>
<li>Default:</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple times)</li>
<li>Type: "prod", "dev", "optional", or "peer" (can be set multiple
times)</li>
</ul>
<p>Option that allows for defining which types of dependencies to install.</p>
<p>Option that allows for defining which types of dependencies to
install.</p>
<p>This is the inverse of <code>--omit=&lt;type&gt;</code>.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted, regardless of
the order in which omit/include are specified on the command-line.</p>
<p>Dependency types specified in <code>--include</code> will not be omitted,
regardless of the order in which omit/include are specified on the
command-line.</p>
<h4 id="ignore-scripts"><code>ignore-scripts</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>If true, npm does not run scripts specified in package.json files.</p>
<p>Note that commands explicitly intended to run a particular script, such as
<code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still
run their intended script if <code>ignore-scripts</code> is set, but they will <em>not</em>
run any pre- or post-scripts.</p>
<p>Note that commands explicitly intended to run a particular script,
such as <code>npm start</code>, <code>npm stop</code>, <code>npm restart</code>, <code>npm test</code>, and <code>npm run</code> will still run their intended script if <code>ignore-scripts</code> is set,
but they will <em>not</em> run any pre- or post-scripts.</p>
<h4 id="audit"><code>audit</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>When "true" submit audit reports alongside the current npm command to the
default registry and all registries configured for scopes. See the
documentation for <a href="../commands/npm-audit.html"><code>npm audit</code></a> for details on what is
submitted.</p>
<p>When "true" submit audit reports alongside the current npm command to
the default registry and all registries configured for scopes. See
the documentation for <a href="../commands/npm-audit.html"><code>npm audit</code></a> for details
on what is submitted.</p>
<h4 id="bin-links"><code>bin-links</code></h4>
<ul>
<li>Default: true</li>
@ -306,35 +300,37 @@ submitted.</p>
</ul>
<p>Tells npm to create symlinks (or <code>.cmd</code> shims on Windows) for package
executables.</p>
<p>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.</p>
<p>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.</p>
<h4 id="fund"><code>fund</code></h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>When "true" displays the message at the end of each <code>npm install</code>
acknowledging the number of dependencies looking for funding. See <a href="../commands/npm-fund.html"><code>npm fund</code></a> for details.</p>
acknowledging the number of dependencies looking for funding. See
<a href="../commands/npm-fund.html"><code>npm fund</code></a> for details.</p>
<h4 id="dry-run"><code>dry-run</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>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, <code>install</code>, <code>update</code>,
<code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and <code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg <code>dist-tags</code>,
<code>owner</code>, etc.</p>
<p>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,
<code>install</code>, <code>update</code>, <code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and
<code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg
<code>dist-tags</code>, <code>owner</code>, etc.</p>
<h4 id="workspace"><code>workspace</code></h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -342,9 +338,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -353,13 +349,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -368,18 +365,19 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="install-links"><code>install-links</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>When set file: protocol dependencies will be packed and installed as regular
dependencies instead of creating a symlink. This option has no effect on
workspaces.</p>
<p>When set file: protocol dependencies will be packed and installed as
regular dependencies instead of creating a symlink. This option has
no effect on workspaces.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-find-dupes.html">npm find-dupes</a></li>

44
deps/npm/docs/output/commands/npm-deprecate.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-deprecate----1161">
<h1 id="----npm-deprecate----1162">
<span>npm-deprecate</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Deprecate a version of a package</span>
</header>
@ -158,22 +158,19 @@ npm command-line interface
</code></pre>
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>This command will update the npm registry entry for a package, providing a
deprecation warning to all who attempt to install it.</p>
<p>It works on <a href="https://semver.npmjs.com/">version ranges</a> as well as specific
versions, so you can do something like this:</p>
<p>This command will update the npm registry entry for a package, providing a deprecation warning to all who attempt to install it.</p>
<p>It works on <a href="https://semver.npmjs.com/">version ranges</a> as well as specific versions, so you can do something like this:</p>
<pre><code class="language-bash">npm deprecate my-thing@"&lt; 0.2.3" "critical bug fixed in v0.2.3"
</code></pre>
<p>SemVer ranges passed to this command are interpreted such that they <em>do</em>
include prerelease versions. For example:</p>
<p>SemVer ranges passed to this command are interpreted such that they <em>do</em> include prerelease versions.
For example:</p>
<pre><code class="language-bash">npm deprecate my-thing@1.x "1.x is no longer supported"
</code></pre>
<p>In this case, a version <code>my-thing@1.0.0-beta.0</code> will also be deprecated.</p>
<p>You must be the package owner to deprecate something. See the <code>owner</code> and
<code>adduser</code> help topics.</p>
<p>To un-deprecate a package, specify an empty string (<code>""</code>) for the <code>message</code>
argument. Note that you must use double quotes with no space between them to
format an empty string.</p>
<p>You must be the package owner to deprecate something.
See the <code>owner</code> and <code>adduser</code> help topics.</p>
<p>To un-deprecate a package, specify an empty string (<code>""</code>) for the <code>message</code> argument.
Note that you must use double quotes with no space between them to format an empty string.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="registry"><code>registry</code></h4>
<ul>
@ -186,21 +183,22 @@ format an empty string.</p>
<li>Default: null</li>
<li>Type: null or String</li>
</ul>
<p>This is a one-time password from a two-factor authenticator. It's needed
when publishing or changing package permissions with <code>npm access</code>.</p>
<p>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.</p>
<p>This is a one-time password from a two-factor authenticator. It's
needed when publishing or changing package permissions with <code>npm access</code>.</p>
<p>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.</p>
<h4 id="dry-run"><code>dry-run</code></h4>
<ul>
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>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, <code>install</code>, <code>update</code>,
<code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and <code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg <code>dist-tags</code>,
<code>owner</code>, etc.</p>
<p>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,
<code>install</code>, <code>update</code>, <code>dedupe</code>, <code>uninstall</code>, as well as <code>pack</code> and
<code>publish</code>.</p>
<p>Note: This is NOT honored by other network related commands, eg
<code>dist-tags</code>, <code>owner</code>, etc.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../using-npm/package-spec.html">package spec</a></li>

138
deps/npm/docs/output/commands/npm-diff.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-diff----1161">
<h1 id="----npm-diff----1162">
<span>npm-diff</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">The registry diff command</span>
</header>
@ -157,20 +157,14 @@ npm command-line interface
<pre><code class="language-bash">npm diff [...&lt;paths&gt;]
</code></pre>
<h3 id="description">Description</h3>
<p>Similar to its <code>git diff</code> counterpart, this command will print diff patches
of files for packages published to the npm registry.</p>
<p>Similar to its <code>git diff</code> counterpart, this command will print diff patches of files for packages published to the npm registry.</p>
<ul>
<li>
<p><code>npm diff --diff=&lt;spec-a&gt; --diff=&lt;spec-b&gt;</code></p>
<p>Compares two package versions using their registry specifiers, e.g:
<code>npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0</code>. It's also possible to
compare across forks of any package,
e.g: <code>npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0</code>.</p>
<p>Any valid spec can be used, so that it's also possible to compare
directories or git repositories,
e.g: <code>npm diff --diff=pkg@latest --diff=./packages/pkg</code></p>
<p>Here's an example comparing two different versions of a package named
<code>abbrev</code> from the registry:</p>
<p>Compares two package versions using their registry specifiers, e.g: <code>npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0</code>.
It's also possible to compare across forks of any package, e.g: <code>npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0</code>.</p>
<p>Any valid spec can be used, so that it's also possible to compare directories or git repositories, e.g: <code>npm diff --diff=pkg@latest --diff=./packages/pkg</code></p>
<p>Here's an example comparing two different versions of a package named <code>abbrev</code> from the registry:</p>
<pre><code class="language-bash">npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1
</code></pre>
<p>On success, output looks like:</p>
@ -187,50 +181,29 @@ index v1.1.0..v1.1.1 100644
"author": "Isaac Z. Schlueter &lt;i@izs.me&gt;",
"main": "abbrev.js",
</code></pre>
<p>Given the flexible nature of npm specs, you can also target local
directories or git repos just like when using <code>npm install</code>:</p>
<p>Given the flexible nature of npm specs, you can also target local directories or git repos just like when using <code>npm install</code>:</p>
<pre><code class="language-bash">npm diff --diff=https://github.com/npm/libnpmdiff --diff=./local-path
</code></pre>
<p>In the example above we can compare the contents from the package installed
from the git repo at <code>github.com/npm/libnpmdiff</code> with the contents of the
<code>./local-path</code> that contains a valid package, such as a modified copy of
the original.</p>
<p>In the example above we can compare the contents from the package installed from the git repo at <code>github.com/npm/libnpmdiff</code> with the contents of the <code>./local-path</code> that contains a valid package, such as a modified copy of the original.</p>
</li>
<li>
<p><code>npm diff</code> (in a package directory, no arguments):</p>
<p>If the package is published to the registry, <code>npm diff</code> will fetch the
tarball version tagged as <code>latest</code> (this value can be configured using the
<code>tag</code> option) and proceed to compare the contents of files present in that
tarball, with the current files in your local file system.</p>
<p>This workflow provides a handy way for package authors to see what
package-tracked files have been changed in comparison with the latest
published version of that package.</p>
<p>If the package is published to the registry, <code>npm diff</code> will fetch the tarball version tagged as <code>latest</code> (this value can be configured using the <code>tag</code> option) and proceed to compare the contents of files present in that tarball, with the current files in your local file system.</p>
<p>This workflow provides a handy way for package authors to see what package-tracked files have been changed in comparison with the latest published version of that package.</p>
</li>
<li>
<p><code>npm diff --diff=&lt;pkg-name&gt;</code> (in a package directory):</p>
<p>When using a single package name (with no version or tag specifier) as an
argument, <code>npm diff</code> will work in a similar way to
<a href="npm-outdated"><code>npm-outdated</code></a> and reach for the registry to figure out
what current published version of the package named <code>&lt;pkg-name&gt;</code>
will satisfy its dependent declared semver-range. Once that specific
version is known <code>npm diff</code> will print diff patches comparing the
current version of <code>&lt;pkg-name&gt;</code> found in the local file system with
that specific version returned by the registry.</p>
<p>When using a single package name (with no version or tag specifier) as an argument, <code>npm diff</code> will work in a similar way to <a href="npm-outdated"><code>npm-outdated</code></a> and reach for the registry to figure out what current published version of the package named <code>&lt;pkg-name&gt;</code> will satisfy its dependent declared semver-range.
Once that specific version is known <code>npm diff</code> will print diff patches comparing the current version of <code>&lt;pkg-name&gt;</code> found in the local file system with that specific version returned by the registry.</p>
<p>Given a package named <code>abbrev</code> that is currently installed:</p>
<pre><code class="language-bash">npm diff --diff=abbrev
</code></pre>
<p>That will request from the registry its most up to date version and
will print a diff output comparing the currently installed version to this
newer one if the version numbers are not the same.</p>
<p>That will request from the registry its most up to date version and will print a diff output comparing the currently installed version to this newer one if the version numbers are not the same.</p>
</li>
<li>
<p><code>npm diff --diff=&lt;spec-a&gt;</code> (in a package directory):</p>
<p>Similar to using only a single package name, it's also possible to declare
a full registry specifier version if you wish to compare the local version
of an installed package with the specific version/tag/semver-range provided
in <code>&lt;spec-a&gt;</code>.</p>
<p>An example: assuming <code>pkg@1.0.0</code> is installed in the current <code>node_modules</code>
folder, running:</p>
<p>Similar to using only a single package name, it's also possible to declare a full registry specifier version if you wish to compare the local version of an installed package with the specific version/tag/semver-range provided in <code>&lt;spec-a&gt;</code>.</p>
<p>An example: assuming <code>pkg@1.0.0</code> is installed in the current <code>node_modules</code> folder, running:</p>
<pre><code class="language-bash">npm diff --diff=pkg@2.0.0
</code></pre>
<p>It will effectively be an alias to
@ -238,30 +211,20 @@ folder, running:</p>
</li>
<li>
<p><code>npm diff --diff=&lt;semver-a&gt; [--diff=&lt;semver-b&gt;]</code> (in a package directory):</p>
<p>Using <code>npm diff</code> along with semver-valid version numbers is a shorthand
to compare different versions of the current package.</p>
<p>It needs to be run from a package directory, such that for a package named
<code>pkg</code> running <code>npm diff --diff=1.0.0 --diff=1.0.1</code> is the same as running
<code>npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1</code>.</p>
<p>If only a single argument <code>&lt;version-a&gt;</code> is provided, then the current local
file system is going to be compared against that version.</p>
<p>Here's an example comparing two specific versions (published to the
configured registry) of the current project directory:</p>
<p>Using <code>npm diff</code> along with semver-valid version numbers is a shorthand to compare different versions of the current package.</p>
<p>It needs to be run from a package directory, such that for a package named <code>pkg</code> running <code>npm diff --diff=1.0.0 --diff=1.0.1</code> is the same as running <code>npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1</code>.</p>
<p>If only a single argument <code>&lt;version-a&gt;</code> is provided, then the current local file system is going to be compared against that version.</p>
<p>Here's an example comparing two specific versions (published to the configured registry) of the current project directory:</p>
<pre><code class="language-bash">npm diff --diff=1.0.0 --diff=1.1.0
</code></pre>
</li>
</ul>
<p>Note that tag names are not valid <code>--diff</code> argument values, if you wish to
compare to a published tag, you must use the <code>pkg@tagname</code> syntax.</p>
<p>Note that tag names are not valid <code>--diff</code> argument values, if you wish to compare to a published tag, you must use the <code>pkg@tagname</code> syntax.</p>
<h4 id="filtering-files">Filtering files</h4>
<p>It's possible to also specify positional arguments using file names or globs
pattern matching in order to limit the result of diff patches to only a subset
of files for a given package, e.g:</p>
<p>It's possible to also specify positional arguments using file names or globs pattern matching in order to limit the result of diff patches to only a subset of files for a given package, e.g:</p>
<pre><code class="language-bash">npm diff --diff=pkg@2 ./lib/ CHANGELOG.md
</code></pre>
<p>In the example above the diff output is only going to print contents of files
located within the folder <code>./lib/</code> and changed lines of code within the
<code>CHANGELOG.md</code> file.</p>
<p>In the example above the diff output is only going to print contents of files located within the folder <code>./lib/</code> and changed lines of code within the <code>CHANGELOG.md</code> file.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="diff"><code>diff</code></h4>
<ul>
@ -318,12 +281,13 @@ located within the folder <code>./lib/</code> and changed lines of code within t
<li>Default: false</li>
<li>Type: Boolean</li>
</ul>
<p>Operates in "global" mode, so that packages are installed into the <code>prefix</code>
folder instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in behavior.</p>
<p>Operates in "global" mode, so that packages are installed into the
<code>prefix</code> folder instead of the current working directory. See
<a href="../configuring-npm/folders.html">folders</a> for more on the differences in
behavior.</p>
<ul>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder, instead
of the current working directory.</li>
<li>packages are installed into the <code>{prefix}/lib/node_modules</code> folder,
instead of the current working directory.</li>
<li>bin files are linked to <code>{prefix}/bin</code></li>
<li>man pages are linked to <code>{prefix}/share/man</code></li>
</ul>
@ -332,21 +296,21 @@ of the current working directory.</li>
<li>Default: "latest"</li>
<li>Type: String</li>
</ul>
<p>If you ask npm to install a package and don't tell it a specific version,
then it will install the specified tag.</p>
<p>If you ask npm to install a package and don't tell it a specific
version, then it will install the specified tag.</p>
<p>It is the tag added to the package@version specified in the <code>npm dist-tag add</code> command, if no explicit tag is given.</p>
<p>When used by the <code>npm diff</code> command, this is the tag used to fetch the
tarball that will be compared with the local files by default.</p>
<p>If used in the <code>npm publish</code> command, this is the tag that will be added to
the package submitted to the registry.</p>
<p>When used by the <code>npm diff</code> command, this is the tag used to fetch
the tarball that will be compared with the local files by default.</p>
<p>If used in the <code>npm publish</code> command, this is the tag that will be
added to the package submitted to the registry.</p>
<h4 id="workspace"><code>workspace</code></h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -354,9 +318,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -365,13 +329,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -380,9 +345,10 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h2 id="see-also">See Also</h2>
<ul>

92
deps/npm/docs/output/commands/npm-dist-tag.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-dist-tag----1161">
<h1 id="----npm-dist-tag----1162">
<span>npm-dist-tag</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Modify package distribution tags</span>
</header>
@ -164,68 +164,52 @@ alias: dist-tags
<p>Add, remove, and enumerate distribution tags on a package:</p>
<ul>
<li>
<p>add: Tags the specified version of the package with the specified tag,
or the <a href="../using-npm/config#tag.html"><code>--tag</code> config</a> if not specified. If you have
two-factor authentication on auth-and-writes then you’ll need to include a
one-time password on the command line with
<code>--otp &lt;one-time password&gt;</code>, or go through a second factor flow based on your <code>authtype</code>.</p>
<p>add: Tags the specified version of the package with the specified tag, or the <a href="../using-npm/config#tag.html"><code>--tag</code> config</a> if not specified.
If you have two-factor authentication on auth-and-writes then you’ll need to include a one-time password on the command line with <code>--otp &lt;one-time password&gt;</code>, or go through a second factor flow based on your <code>authtype</code>.</p>
</li>
<li>
<p>rm: Clear a tag that is no longer in use from the package. If you have
two-factor authentication on auth-and-writes then you’ll need to include
a one-time password on the command line with <code>--otp &lt;one-time password&gt;</code>,
or go through a second factor flow based on your <code>authtype</code></p>
<p>rm: Clear a tag that is no longer in use from the package.
If you have two-factor authentication on auth-and-writes then you’ll need to include a one-time password on the command line with <code>--otp &lt;one-time password&gt;</code>, or go through a second factor flow based on your <code>authtype</code></p>
</li>
<li>
<p>ls: Show all of the dist-tags for a package, defaulting to the package in
the current prefix. This is the default action if none is specified.</p>
<p>ls: Show all of the dist-tags for a package, defaulting to the package in the current prefix.
This is the default action if none is specified.</p>
</li>
</ul>
<p>A tag can be used when installing packages as a reference to a version instead
of using a specific version number:</p>
<p>A tag can be used when installing packages as a reference to a version instead of using a specific version number:</p>
<pre><code class="language-bash">npm install &lt;name&gt;@&lt;tag&gt;
</code></pre>
<p>When installing dependencies, a preferred tagged version may be specified:</p>
<pre><code class="language-bash">npm install --tag &lt;tag&gt;
</code></pre>
<p>(This also applies to any other commands that resolve and install
dependencies, such as <code>npm dedupe</code>, <code>npm update</code>, and <code>npm audit fix</code>.)</p>
<p>Publishing a package sets the <code>latest</code> tag to the published version unless the
<code>--tag</code> option is used. For example, <code>npm publish --tag=beta</code>.</p>
<p>By default, <code>npm install &lt;pkg&gt;</code> (without any <code>@&lt;version&gt;</code> or <code>@&lt;tag&gt;</code>
specifier) installs the <code>latest</code> tag.</p>
<p>(This also applies to any other commands that resolve and install dependencies, such as <code>npm dedupe</code>, <code>npm update</code>, and <code>npm audit fix</code>.)</p>
<p>Publishing a package sets the <code>latest</code> tag to the published version unless the <code>--tag</code> option is used.
For example, <code>npm publish --tag=beta</code>.</p>
<p>By default, <code>npm install &lt;pkg&gt;</code> (without any <code>@&lt;version&gt;</code> or <code>@&lt;tag&gt;</code> specifier) installs the <code>latest</code> tag.</p>
<h3 id="purpose">Purpose</h3>
<p>Tags can be used to provide an alias instead of version numbers.</p>
<p>For example, a project might choose to have multiple streams of development
and use a different tag for each stream, e.g., <code>stable</code>, <code>beta</code>, <code>dev</code>,
<p>For example, a project might choose to have multiple streams of development and use a different tag for each stream, e.g., <code>stable</code>, <code>beta</code>, <code>dev</code>,
<code>canary</code>.</p>
<p>By default, the <code>latest</code> tag is used by npm to identify the current version
of a package, and <code>npm install &lt;pkg&gt;</code> (without any <code>@&lt;version&gt;</code> or <code>@&lt;tag&gt;</code>
specifier) installs the <code>latest</code> tag. Typically, projects only use the
<code>latest</code> tag for stable release versions, and use other tags for unstable
versions such as prereleases.</p>
<p>By default, the <code>latest</code> tag is used by npm to identify the current version of a package, and <code>npm install &lt;pkg&gt;</code> (without any <code>@&lt;version&gt;</code> or <code>@&lt;tag&gt;</code> specifier) installs the <code>latest</code> tag.
Typically, projects only use the <code>latest</code> tag for stable release versions, and use other tags for unstable versions such as prereleases.</p>
<p>The <code>next</code> tag is used by some projects to identify the upcoming version.</p>
<p>Other than <code>latest</code>, no tag has any special significance to npm itself.</p>
<h3 id="caveats">Caveats</h3>
<p>This command used to be known as <code>npm tag</code>, which only created new tags,
and so had a different syntax.</p>
<p>Tags must share a namespace with version numbers, because they are
specified in the same slot: <code>npm install &lt;pkg&gt;@&lt;version&gt;</code> vs
<code>npm install &lt;pkg&gt;@&lt;tag&gt;</code>.</p>
<p>Tags that can be interpreted as valid semver ranges will be rejected. For
example, <code>v1.4</code> cannot be used as a tag, because it is interpreted by
semver as <code>&gt;=1.4.0 &lt;1.5.0</code>. See <a href="https://github.com/npm/npm/issues/6082">https://github.com/npm/npm/issues/6082</a>.</p>
<p>The simplest way to avoid semver problems with tags is to use tags that do
not begin with a number or the letter <code>v</code>.</p>
<p>This command used to be known as <code>npm tag</code>, which only created new tags, and so had a different syntax.</p>
<p>Tags must share a namespace with version numbers, because they are specified in the same slot: <code>npm install &lt;pkg&gt;@&lt;version&gt;</code> vs <code>npm install &lt;pkg&gt;@&lt;tag&gt;</code>.</p>
<p>Tags that can be interpreted as valid semver ranges will be rejected.
For example, <code>v1.4</code> cannot be used as a tag, because it is interpreted by semver as <code>&gt;=1.4.0 &lt;1.5.0</code>.
See <a href="https://github.com/npm/npm/issues/6082">https://github.com/npm/npm/issues/6082</a>.</p>
<p>The simplest way to avoid semver problems with tags is to use tags that do not begin with a number or the letter <code>v</code>.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="workspace"><code>workspace</code></h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -233,9 +217,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -244,13 +228,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -259,9 +244,10 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h3 id="see-also">See Also</h3>
<ul>

44
deps/npm/docs/output/commands/npm-docs.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-docs----1161">
<h1 id="----npm-docs----1162">
<span>npm-docs</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Open documentation for a package in a web browser</span>
</header>
@ -159,11 +159,9 @@ npm command-line interface
alias: home
</code></pre>
<h3 id="description">Description</h3>
<p>This command tries to guess at the likely location of a package's
documentation URL, and then tries to open it using the
<a href="../using-npm/config#browser.html"><code>--browser</code> config</a> param. You can pass multiple
package names at once. If no package name is provided, it will search for a
<code>package.json</code> in the current folder and use the <code>name</code> property.</p>
<p>This command tries to guess at the likely location of a package's documentation URL, and then tries to open it using the <a href="../using-npm/config#browser.html"><code>--browser</code> config</a> param.
You can pass multiple package names at once.
If no package name is provided, it will search for a <code>package.json</code> in the current folder and use the <code>name</code> property.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="browser"><code>browser</code></h4>
<ul>
@ -185,9 +183,9 @@ terminal.</p>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -195,9 +193,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -206,13 +204,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -221,9 +220,10 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h3 id="see-also">See Also</h3>
<ul>

95
deps/npm/docs/output/commands/npm-doctor.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-doctor----1161">
<h1 id="----npm-doctor----1162">
<span>npm-doctor</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Check the health of your npm environment</span>
</header>
@ -158,81 +158,56 @@ npm command-line interface
</code></pre>
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p><code>npm doctor</code> runs a set of checks to ensure that your npm installation has
what it needs to manage your JavaScript packages. npm is mostly a
standalone tool, but it does have some basic requirements that must be met:</p>
<p><code>npm doctor</code> runs a set of checks to ensure that your npm installation has what it needs to manage your JavaScript packages.
npm is mostly a standalone tool, but it does have some basic requirements that must be met:</p>
<ul>
<li>Node.js and git must be executable by npm.</li>
<li>The primary npm registry, <code>registry.npmjs.com</code>, or another service that
uses the registry API, is available.</li>
<li>The directories that npm uses, <code>node_modules</code> (both locally and
globally), exist and can be written by the current user.</li>
<li>The primary npm registry, <code>registry.npmjs.com</code>, or another service that uses the registry API, is available.</li>
<li>The directories that npm uses, <code>node_modules</code> (both locally and globally), exist and can be written by the current user.</li>
<li>The npm cache exists, and the package tarballs within it aren't corrupt.</li>
</ul>
<p>Without all of these working properly, npm may not work properly. Many
issues are often attributable to things that are outside npm's code base,
so <code>npm doctor</code> confirms that the npm installation is in a good state.</p>
<p>Also, in addition to this, there are also very many issue reports due to
using old versions of npm. Since npm is constantly improving, running
<code>npm@latest</code> is better than an old version.</p>
<p><code>npm doctor</code> verifies the following items in your environment, and if
there are any recommended changes, it will display them. By default npm
runs all of these checks. You can limit what checks are ran by
specifying them as extra arguments.</p>
<p>Without all of these working properly, npm may not work properly.
Many issues are often attributable to things that are outside npm's code base, so <code>npm doctor</code> confirms that the npm installation is in a good state.</p>
<p>Also, in addition to this, there are also very many issue reports due to using old versions of npm.
Since npm is constantly improving, running <code>npm@latest</code> is better than an old version.</p>
<p><code>npm doctor</code> verifies the following items in your environment, and if there are any recommended changes, it will display them.
By default npm runs all of these checks.
You can limit what checks are ran by specifying them as extra arguments.</p>
<h4 id="connecting-to-the-registry"><code>Connecting to the registry</code></h4>
<p>By default, npm installs from the primary npm registry,
<code>registry.npmjs.org</code>. <code>npm doctor</code> hits a special connection testing
endpoint within the registry. This can also be checked with <code>npm ping</code>.
If this check fails, you may be using a proxy that needs to be
configured, or may need to talk to your IT staff to get access over
HTTPS to <code>registry.npmjs.org</code>.</p>
<p>This check is done against whichever registry you've configured (you can
see what that is by running <code>npm config get registry</code>), and if you're using
a private registry that doesn't support the <code>/whoami</code> endpoint supported by
the primary registry, this check may fail.</p>
<code>registry.npmjs.org</code>.
<code>npm doctor</code> hits a special connection testing endpoint within the registry.
This can also be checked with <code>npm ping</code>.
If this check fails, you may be using a proxy that needs to be configured, or may need to talk to your IT staff to get access over HTTPS to <code>registry.npmjs.org</code>.</p>
<p>This check is done against whichever registry you've configured (you can see what that is by running <code>npm config get registry</code>), and if you're using a private registry that doesn't support the <code>/whoami</code> endpoint supported by the primary registry, this check may fail.</p>
<h4 id="checking-npm-version"><code>Checking npm version</code></h4>
<p>While Node.js may come bundled with a particular version of npm, it's the
policy of the CLI team that we recommend all users run <code>npm@latest</code> if they
can. As the CLI is maintained by a small team of contributors, there are
only resources for a single line of development, so npm's own long-term
support releases typically only receive critical security and regression
fixes. The team believes that the latest tested version of npm is almost
always likely to be the most functional and defect-free version of npm.</p>
<p>While Node.js may come bundled with a particular version of npm, it's the policy of the CLI team that we recommend all users run <code>npm@latest</code> if they can.
As the CLI is maintained by a small team of contributors, there are only resources for a single line of development, so npm's own long-term support releases typically only receive critical security and regression fixes.
The team believes that the latest tested version of npm is almost always likely to be the most functional and defect-free version of npm.</p>
<h4 id="checking-node-version"><code>Checking node version</code></h4>
<p>For most users, in most circumstances, the best version of Node will be the
latest long-term support (LTS) release. Those of you who want access to new
ECMAscript features or bleeding-edge changes to Node's standard library may
be running a newer version, and some may be required to run an older
version of Node because of enterprise change control policies. That's OK!
<p>For most users, in most circumstances, the best version of Node will be the latest long-term support (LTS) release.
Those of you who want access to new ECMAscript features or bleeding-edge changes to Node's standard library may be running a newer version, and some may be required to run an older version of Node because of enterprise change control policies.
That's OK!
But in general, the npm team recommends that most users run Node.js LTS.</p>
<h4 id="checking-configured-npm-registry"><code>Checking configured npm registry</code></h4>
<p>You may be installing from private package registries for your project or
company. That's great! Others may be following tutorials or StackOverflow
questions in an effort to troubleshoot problems you may be having.
Sometimes, this may entail changing the registry you're pointing at. This
part of <code>npm doctor</code> just lets you, and maybe whoever's helping you with
support, know that you're not using the default registry.</p>
<p>You may be installing from private package registries for your project or company.
That's great! Others may be following tutorials or StackOverflow questions in an effort to troubleshoot problems you may be having.
Sometimes, this may entail changing the registry you're pointing at.
This part of <code>npm doctor</code> just lets you, and maybe whoever's helping you with support, know that you're not using the default registry.</p>
<h4 id="checking-for-git-executable-in-path"><code>Checking for git executable in PATH</code></h4>
<p>While it's documented in the README, it may not be obvious that npm needs
Git installed to do many of the things that it does. Also, in some cases
–&nbsp;especially on Windows –&nbsp;you may have Git set up in such a way that it's
not accessible via your <code>PATH</code> so that npm can find it. This check ensures
that Git is available.</p>
<p>While it's documented in the README, it may not be obvious that npm needs Git installed to do many of the things that it does.
Also, in some cases –&nbsp;especially on Windows –&nbsp;you may have Git set up in such a way that it's not accessible via your <code>PATH</code> so that npm can find it.
This check ensures that Git is available.</p>
<h4 id="permissions-checks">Permissions checks</h4>
<ul>
<li>Your cache must be readable and writable by the user running npm.</li>
<li>Global package binaries must be writable by the user running npm.</li>
<li>Your local <code>node_modules</code> path, if you're running <code>npm doctor</code> with a
project directory, must be readable and writable by the user running npm.</li>
<li>Your local <code>node_modules</code> path, if you're running <code>npm doctor</code> with a project directory, must be readable and writable by the user running npm.</li>
</ul>
<h4 id="validate-the-checksums-of-cached-packages">Validate the checksums of cached packages</h4>
<p>When an npm package is published, the publishing process generates a
checksum that npm uses at install time to verify that the package didn't
get corrupted in transit. <code>npm doctor</code> uses these checksums to validate the
package tarballs in your local cache (you can see where that cache is
located with <code>npm config get cache</code>). In the event that there are corrupt
packages in your cache, you should probably run <code>npm cache clean -f</code> and
reset the cache.</p>
<p>When an npm package is published, the publishing process generates a checksum that npm uses at install time to verify that the package didn't get corrupted in transit.
<code>npm doctor</code> uses these checksums to validate the package tarballs in your local cache (you can see where that cache is located with <code>npm config get cache</code>).
In the event that there are corrupt packages in your cache, you should probably run <code>npm cache clean -f</code> and reset the cache.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="registry"><code>registry</code></h4>
<ul>

15
deps/npm/docs/output/commands/npm-edit.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-edit----1161">
<h1 id="----npm-edit----1162">
<span>npm-edit</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Edit an installed package</span>
</header>
@ -158,14 +158,9 @@ npm command-line interface
</code></pre>
<p>Note: This command is unaware of workspaces.</p>
<h3 id="description">Description</h3>
<p>Selects a dependency in the current project and opens the package folder in
the default editor (or whatever you've configured as the npm <code>editor</code>
config -- see <a href="npm-config"><code>npm-config</code></a>.)</p>
<p>After it has been edited, the package is rebuilt so as to pick up any
changes in compiled packages.</p>
<p>For instance, you can do <code>npm install connect</code> to install connect
into your package, and then <code>npm edit connect</code> to make a few
changes to your locally installed copy.</p>
<p>Selects a dependency in the current project and opens the package folder in the default editor (or whatever you've configured as the npm <code>editor</code> config -- see <a href="npm-config"><code>npm-config</code></a>.)</p>
<p>After it has been edited, the package is rebuilt so as to pick up any changes in compiled packages.</p>
<p>For instance, you can do <code>npm install connect</code> to install connect into your package, and then <code>npm edit connect</code> to make a few changes to your locally installed copy.</p>
<h3 id="configuration">Configuration</h3>
<h4 id="editor"><code>editor</code></h4>
<ul>

209
deps/npm/docs/output/commands/npm-exec.html vendored
View File

@ -141,9 +141,9 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="----npm-exec----1161">
<h1 id="----npm-exec----1162">
<span>npm-exec</span>
<span class="version">@11.6.1</span>
<span class="version">@11.6.2</span>
</h1>
<span class="description">Run a command from a local or remote npm package</span>
</header>
@ -162,72 +162,43 @@ npm exec --package=foo -c '&lt;cmd&gt; [args...]'
alias: x
</code></pre>
<h3 id="description">Description</h3>
<p>This command allows you to run an arbitrary command from an npm package
(either one installed locally, or fetched remotely), in a similar context
as running it via <code>npm run</code>.</p>
<p>Run without positional arguments or <code>--call</code>, this allows you to
interactively run commands in the same sort of shell environment that
<code>package.json</code> scripts are run. Interactive mode is not supported in CI
environments when standard input is a TTY, to prevent hangs.</p>
<p>Whatever packages are specified by the <code>--package</code> option will be
provided in the <code>PATH</code> of the executed command, along with any locally
installed package executables. The <code>--package</code> option may be
specified multiple times, to execute the supplied command in an environment
where all specified packages are available.</p>
<p>If any requested packages are not present in the local project
dependencies, then a prompt is printed, which can be suppressed by
providing either <code>--yes</code> or <code>--no</code>. When standard input is not a TTY or a
CI environment is detected, <code>--yes</code> is assumed. The requested packages are
installed to a folder in the npm cache, which is added to the <code>PATH</code>
environment variable in the executed process.</p>
<p>Package names provided without a specifier will be matched with whatever
version exists in the local project. Package names with a specifier will
only be considered a match if they have the exact same name and version as
the local dependency.</p>
<p>If no <code>-c</code> or <code>--call</code> option is provided, then the positional arguments
are used to generate the command string. If no <code>--package</code> options
are provided, then npm will attempt to determine the executable name from
the package specifier provided as the first positional argument according
to the following heuristic:</p>
<p>This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via <code>npm run</code>.</p>
<p>Run without positional arguments or <code>--call</code>, this allows you to interactively run commands in the same sort of shell environment that <code>package.json</code> scripts are run.
Interactive mode is not supported in CI environments when standard input is a TTY, to prevent hangs.</p>
<p>Whatever packages are specified by the <code>--package</code> option will be provided in the <code>PATH</code> of the executed command, along with any locally installed package executables.
The <code>--package</code> option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.</p>
<p>If any requested packages are not present in the local project dependencies, then a prompt is printed, which can be suppressed by providing either <code>--yes</code> or <code>--no</code>.
When standard input is not a TTY or a CI environment is detected, <code>--yes</code> is assumed.
The requested packages are installed to a folder in the npm cache, which is added to the <code>PATH</code> environment variable in the executed process.</p>
<p>Package names provided without a specifier will be matched with whatever version exists in the local project.
Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.</p>
<p>If no <code>-c</code> or <code>--call</code> option is provided, then the positional arguments are used to generate the command string.
If no <code>--package</code> options are provided, then npm will attempt to determine the executable name from the package specifier provided as the first positional argument according to the following heuristic:</p>
<ul>
<li>If the package has a single entry in its <code>bin</code> field in <code>package.json</code>,
or if all entries are aliases of the same command, then that command
will be used.</li>
<li>If the package has multiple <code>bin</code> entries, and one of them matches the
unscoped portion of the <code>name</code> field, then that command will be used.</li>
<li>If this does not result in exactly one option (either because there are
no bin entries, or none of them match the <code>name</code> of the package), then
<code>npm exec</code> exits with an error.</li>
<li>If the package has a single entry in its <code>bin</code> field in <code>package.json</code>, or if all entries are aliases of the same command, then that command will be used.</li>
<li>If the package has multiple <code>bin</code> entries, and one of them matches the unscoped portion of the <code>name</code> field, then that command will be used.</li>
<li>If this does not result in exactly one option (either because there are no bin entries, or none of them match the <code>name</code> of the package), then <code>npm exec</code> exits with an error.</li>
</ul>
<p>To run a binary <em>other than</em> the named binary, specify one or more
<code>--package</code> options, which will prevent npm from inferring the package from
the first command argument.</p>
<p>To run a binary <em>other than</em> the named binary, specify one or more <code>--package</code> options, which will prevent npm from inferring the package from the first command argument.</p>
<h3 id="npx-vs-npm-exec"><code>npx</code> vs <code>npm exec</code></h3>
<p>When run via the <code>npx</code> binary, all flags and options <em>must</em> be set prior to
any positional arguments. When run via <code>npm exec</code>, a double-hyphen <code>--</code>
flag can be used to suppress npm's parsing of switches and options that
should be sent to the executed command.</p>
<p>When run via the <code>npx</code> binary, all flags and options <em>must</em> be set prior to any positional arguments.
When run via <code>npm exec</code>, a double-hyphen <code>--</code> flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command.</p>
<p>For example:</p>
<pre><code>$ npx foo@latest bar --package=@npmcli/foo
</code></pre>
<p>In this case, npm will resolve the <code>foo</code> package name, and run the
following command:</p>
<p>In this case, npm will resolve the <code>foo</code> package name, and run the following command:</p>
<pre><code>$ foo bar --package=@npmcli/foo
</code></pre>
<p>Since the <code>--package</code> option comes <em>after</em> the positional arguments, it is
treated as an argument to the executed command.</p>
<p>In contrast, due to npm's argument parsing logic, running this command is
different:</p>
<p>Since the <code>--package</code> option comes <em>after</em> the positional arguments, it is treated as an argument to the executed command.</p>
<p>In contrast, due to npm's argument parsing logic, running this command is different:</p>
<pre><code>$ npm exec foo@latest bar --package=@npmcli/foo
</code></pre>
<p>In this case, npm will parse the <code>--package</code> option first, resolving the
<code>@npmcli/foo</code> package. Then, it will execute the following command in that
context:</p>
<p>In this case, npm will parse the <code>--package</code> option first, resolving the <code>@npmcli/foo</code> package.
Then, it will execute the following command in that context:</p>
<pre><code>$ foo@latest bar
</code></pre>
<p>The double-hyphen character is recommended to explicitly tell npm to stop
parsing command line options and switches. The following command would
thus be equivalent to the <code>npx</code> command above:</p>
<p>The double-hyphen character is recommended to explicitly tell npm to stop parsing command line options and switches.
The following command would thus be equivalent to the <code>npx</code> command above:</p>
<pre><code>$ npm exec -- foo@latest bar --package=@npmcli/foo
</code></pre>
<h3 id="configuration">Configuration</h3>
@ -242,8 +213,9 @@ thus be equivalent to the <code>npx</code> command above:</p>
<li>Default: ""</li>
<li>Type: String</li>
</ul>
<p>Optional companion option for <code>npm exec</code>, <code>npx</code> that allows for specifying a
custom command to be run along with the installed packages.</p>
<p>Optional companion option for <code>npm exec</code>, <code>npx</code> that allows for
specifying a custom command to be run along with the installed
packages.</p>
<pre><code class="language-bash">npm exec --package yo --package generator-node --call "yo node"
</code></pre>
<h4 id="workspace"><code>workspace</code></h4>
@ -251,9 +223,9 @@ custom command to be run along with the installed packages.</p>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
@ -261,9 +233,9 @@ this configuration option.</p>
<li>Path to a parent workspace directory (will result in selecting all
workspaces within that folder)</li>
</ul>
<p>When set for the <code>npm init</code> 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.</p>
<p>When set for the <code>npm init</code> 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.</p>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces"><code>workspaces</code></h4>
<ul>
@ -272,13 +244,14 @@ brand new workspace within the project.</p>
</ul>
<p>Set to true to run the command in the context of <strong>all</strong> configured
workspaces.</p>
<p>Explicitly setting this to false will cause commands like <code>install</code> to
ignore workspaces altogether. When not set explicitly:</p>
<p>Explicitly setting this to false will cause commands like <code>install</code>
to ignore workspaces altogether. When not set explicitly:</p>
<ul>
<li>Commands that operate on the <code>node_modules</code> tree (install, update, etc.)
will link workspaces into the <code>node_modules</code> folder. - Commands that do
other things (test, exec, publish, etc.) will operate on the root project,
<em>unless</em> one or more workspaces are specified in the <code>workspace</code> config.</li>
<li>Commands that operate on the <code>node_modules</code> tree (install, update,
etc.) will link workspaces into the <code>node_modules</code> folder. - Commands
that do other things (test, exec, publish, etc.) will operate on the
root project, <em>unless</em> one or more workspaces are specified in the
<code>workspace</code> config.</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="include-workspace-root"><code>include-workspace-root</code></h4>
@ -287,18 +260,17 @@ other things (test, exec, publish, etc.) will operate on the root project,
<li>Type: Boolean</li>
</ul>
<p>Include the workspace root when workspaces are enabled for a command.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code> config, or
all workspaces via the <code>workspaces</code> flag, will cause npm to operate only on
the specified workspaces, and not on the root project.</p>
<p>When false, specifying individual workspaces via the <code>workspace</code>
config, or all workspaces via the <code>workspaces</code> flag, will cause npm
to operate only on the specified workspaces, and not on the root
project.</p>
<p>This value is not exported to the environment for child processes.</p>
<h3 id="examples">Examples</h3>
<p>Run the version of <code>tap</code> in the local dependencies, with the provided
arguments:</p>
<p>Run the version of <code>tap</code> in the local dependencies, with the provided arguments:</p>
<pre><code>$ npm exec -- tap --bail test/foo.js
$ npx tap --bail test/foo.js
</code></pre>
<p>Run a command <em>other than</em> the command whose name matches the package name
by specifying a <code>--package</code> option:</p>
<p>Run a command <em>other than</em> the command whose name matches the package name by specifying a <code>--package</code> option:</p>
<pre><code>$ npm exec --package=foo -- bar --bar-argument
# ~ or ~
$ npx --package=foo bar --bar-argument
@ -308,13 +280,8 @@ $ npx --package=foo bar --bar-argument
$ npx -c 'eslint &amp;&amp; say "hooray, lint passed"'
</code></pre>
<h3 id="workspaces-support">Workspaces support</h3>
<p>You may use the <a href="../using-npm/config#workspace.html"><code>workspace</code></a> or
<a href="../using-npm/config#workspaces.html"><code>workspaces</code></a> configs in order to run an
arbitrary command from an npm package (either one installed locally, or fetched
remotely) in the context of the specified workspaces.
If no positional argument or <code>--call</code> option is provided, it will open an
interactive subshell in the context of each of these configured workspaces one
at a time.</p>
<p>You may use the <a href="../using-npm/config#workspace.html"><code>workspace</code></a> or <a href="../using-npm/config#workspaces.html"><code>workspaces</code></a> configs in order to run an arbitrary command from an npm package (either one installed locally, or fetched remotely) in the context of the specified workspaces.
If no positional argument or <code>--call</code> option is provided, it will open an interactive subshell in the context of each of these configured workspaces one at a time.</p>
<p>Given a project with configured workspaces, e.g:</p>
<pre><code>.
+-- package.json
@ -326,85 +293,70 @@ at a time.</p>
`-- c
`-- package.json
</code></pre>
<p>Assuming the workspace configuration is properly set up at the root level
<code>package.json</code> file. e.g:</p>
<p>Assuming the workspace configuration is properly set up at the root level <code>package.json</code> file.
e.g:</p>
<pre><code>{
"workspaces": [ "./packages/*" ]
}
</code></pre>
<p>You can execute an arbitrary command from a package in the context of each of
the configured workspaces when using the
<a href="../using-npm/config#workspace.html"><code>workspaces</code> config options</a>, in this example
we're using <strong>eslint</strong> to lint any js file found within each workspace folder:</p>
<p>You can execute an arbitrary command from a package in the context of each of the configured workspaces when using the <a href="../using-npm/config#workspace.html"><code>workspaces</code> config options</a>, in this example we're using <strong>eslint</strong> to lint any js file found within each workspace folder:</p>
<pre><code>npm exec --ws -- eslint ./*.js
</code></pre>
<h4 id="filtering-workspaces">Filtering workspaces</h4>
<p>It's also possible to execute a command in a single workspace using the
<code>workspace</code> config along with a name or directory path:</p>
<p>It's also possible to execute a command in a single workspace using the <code>workspace</code> config along with a name or directory path:</p>
<pre><code>npm exec --workspace=a -- eslint ./*.js
</code></pre>
<p>The <code>workspace</code> config can also be specified multiple times in order to run a
specific script in the context of multiple workspaces. When defining values for
the <code>workspace</code> config in the command line, it also possible to use <code>-w</code> as a
shorthand, e.g:</p>
<p>The <code>workspace</code> config can also be specified multiple times in order to run a specific script in the context of multiple workspaces.
When defining values for the <code>workspace</code> config in the command line, it also possible to use <code>-w</code> as a shorthand, e.g:</p>
<pre><code>npm exec -w a -w b -- eslint ./*.js
</code></pre>
<p>This last command will run the <code>eslint</code> command in both <code>./packages/a</code> and
<code>./packages/b</code> folders.</p>
<h3 id="compatibility-with-older-npx-versions">Compatibility with Older npx Versions</h3>
<p>The <code>npx</code> binary was rewritten in npm v7.0.0, and the standalone <code>npx</code>
package deprecated at that time. <code>npx</code> uses the <code>npm exec</code>
command instead of a separate argument parser and install process, with
some affordances to maintain backwards compatibility with the arguments it
accepted in previous versions.</p>
<p>The <code>npx</code> binary was rewritten in npm v7.0.0, and the standalone <code>npx</code> package deprecated at that time.
<code>npx</code> uses the <code>npm exec</code> command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions.</p>
<p>This resulted in some shifts in its functionality:</p>
<ul>
<li>Any <code>npm</code> config value may be provided.</li>
<li>To prevent security and user-experience problems from mistyping package
names, <code>npx</code> prompts before installing anything. Suppress this
prompt with the <code>-y</code> or <code>--yes</code> option.</li>
names, <code>npx</code> prompts before installing anything.
Suppress this prompt with the <code>-y</code> or <code>--yes</code> option.</li>
<li>The <code>--no-install</code> option is deprecated, and will be converted to <code>--no</code>.</li>
<li>Shell fallback functionality is removed, as it is not advisable.</li>
<li>The <code>-p</code> argument is a shorthand for <code>--parseable</code> in npm, but shorthand
for <code>--package</code> in npx. This is maintained, but only for the <code>npx</code>
executable.</li>
<li>The <code>--ignore-existing</code> option is removed. Locally installed bins are
always present in the executed process <code>PATH</code>.</li>
<li>The <code>--npm</code> option is removed. <code>npx</code> will always use the <code>npm</code> it ships
with.</li>
<li>The <code>-p</code> argument is a shorthand for <code>--parseable</code> in npm, but shorthand for <code>--package</code> in npx.
This is maintained, but only for the <code>npx</code> executable.</li>
<li>The <code>--ignore-existing</code> option is removed.
Locally installed bins are always present in the executed process <code>PATH</code>.</li>
<li>The <code>--npm</code> option is removed.
<code>npx</code> will always use the <code>npm</code> it ships with.</li>
<li>The <code>--node-arg</code> and <code>-n</code> options are removed.</li>
<li>The <code>--always-spawn</code> option is redundant, and thus removed.</li>
<li>The <code>--shell</code> option is replaced with <code>--script-shell</code>, but maintained
in the <code>npx</code> executable for backwards compatibility.</li>
<li>The <code>--shell</code> option is replaced with <code>--script-shell</code>, but maintained in the <code>npx</code> executable for backwards compatibility.</li>
</ul>
<h3 id="a-note-on-caching">A note on caching</h3>
<p>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 <a href="../commands/npm-cache.html"><code>npm cache</code></a> for more on
how the cache works.</p>
<p>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 <a href="../commands/npm-cache.html"><code>npm cache</code></a> for more on how the cache works.</p>
<h4 id="prefer-online">prefer-online</h4>
<p>Forces staleness checks for packages, making the cli look for updates
immediately even if the package is already in the cache.</p>
<p>Forces staleness checks for packages, making the cli look for updates immediately even if the package is already in the cache.</p>
<h4 id="prefer-offline">prefer-offline</h4>
<p>Bypasses staleness checks for packages. Missing data will still be
requested from the server. To force full offline mode, use <code>offline</code>.</p>
<p>Bypasses staleness checks for packages.
Missing data will still be requested from the server.
To force full offline mode, use <code>offline</code>.</p>
<h4 id="offline">offline</h4>
<p>Forces full offline mode. Any packages not locally cached will result in
an error.</p>
<p>Forces full offline mode.
Any packages not locally cached will result in an error.</p>
<h4 id="workspace2">workspace</h4>
<ul>
<li>Default:</li>
<li>Type: String (can be set multiple times)</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>Valid values for the <code>workspace</code> config are either:</p>
<ul>
<li>Workspace names</li>
<li>Path to a workspace directory</li>
<li>Path to a parent workspace directory (will result to selecting all of the
nested workspaces)</li>
<li>Path to a parent workspace directory (will result to selecting all of the nested workspaces)</li>
</ul>
<p>This value is not exported to the environment for child processes.</p>
<h4 id="workspaces2">workspaces</h4>
@ -413,8 +365,7 @@ nested workspaces)</li>
<li>Type: Boolean</li>
<li>Default: <code>false</code></li>
</ul>
<p>Run scripts in the context of all configured workspaces for the current
project.</p>
<p>Run scripts in the context of all configured workspaces for the current project.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-run.html">npm run</a></li>

Some files were not shown because too many files have changed in this diff Show More