BackPup/node
1
0 Fork 0
mirror of https://github.com/nodejs/node.git synced 2026-10-14 10:26:26 -04:00
Code Issues Packages Projects Releases Wiki Activity

deps: upgrade npm to 7.4.2

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/36953
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
This commit is contained in:
Ruy Adorno authored and Antoine du Hamel committed 2021-01-18 12:10:57 +01:00
1 parent f8ab632d56
commit 1f287b04a2
93 files changed
+3747 -2433
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

deps/npm/AUTHORS
Vendored
+1
View File
@@ -746,3 +746,4 @@ fuhao.xu <fuhao.xu@yitu-inc.com>
marsonya <16393876+marsonya@users.noreply.github.com>
Jeff Griffiths <jeff@eko-recordings.ca>
Michael Garvin <gar+gh@danger.computer>
Gar <gar+gh@danger.computer>
deps/npm/CHANGELOG.md
Vendored
+75
View File
@@ -1,3 +1,78 @@
## v7.4.2 (2021-01-15)
### DEPENDENCIES
* [`e5ce6bbba`](https://github.com/npm/cli/commit/e5ce6bbbad82b85c8e74a4558503513e4f337476)
* `@npmcli/arborist@2.0.5`
* fix creating missing dirs when using --prefix and --global
* fix omit types of deps in global installs
* fix prioritizing npm-shrinkwrap.json over package-lock.json
* better cache system for packuments
* improves audit performance
## v7.4.1 (2021-01-14)
### BUG FIXES
* [`23df96d33`](https://github.com/npm/cli/commit/23df96d3394ba0b69a37f416d7f0c26bb9354975)
[#2486](https://github.com/npm/cli/issues/2486)
npm link no longer deletes entire project when global prefix is a symlink
([@nlf](https://github.com/nlf))
### DOCUMENTATION
* [`7dd0dfc59`](https://github.com/npm/cli/commit/7dd0dfc59c861e7d3e30a86a8e6db10872fc6b44)
[#2459](https://github.com/npm/cli/issues/2459)
fix(docs): clean up `npm start` docs
([@wraithgar](https://github.com/wraithgar))
* [`307b3bd9f`](https://github.com/npm/cli/commit/307b3bd9f90e96fcc8805a1d5ddec80787a3d3a7)
[#2460](https://github.com/npm/cli/issues/2460)
fix(docs): clean up `npm stop` docs
([@wraithgar](https://github.com/wraithgar))
* [`23f01b739`](https://github.com/npm/cli/commit/23f01b739d7a01a7dc3672322e14eb76ff33d712)
[#2462](https://github.com/npm/cli/issues/2462)
fix(docs): clean up `npm test` docs
([@wraithgar](https://github.com/wraithgar))
* [`4b43656fc`](https://github.com/npm/cli/commit/4b43656fc608783a29ccf8495dc305459abc5cc7)
[#2463](https://github.com/npm/cli/issues/2463)
fix(docs): clean up `npm prefix` docs
([@wraithgar](https://github.com/wraithgar))
* [`1135539ba`](https://github.com/npm/cli/commit/1135539bac9f98bb1a5d5ed05227a8ecd19493d3)
[`a07bb8e69`](https://github.com/npm/cli/commit/a07bb8e692a85b55d51850534c09fa58224c2285)
[`9b55b798e`](https://github.com/npm/cli/commit/9b55b798ed8f2b9be7b3199a1bfc23b1cd89c4cd)
[`cd5eeaaa0`](https://github.com/npm/cli/commit/cd5eeaaa08eabb505b65747a428c3c59159663dc)
[`6df69ce10`](https://github.com/npm/cli/commit/6df69ce107912f8429665eb851825d2acebc8575)
[`dc6b2a8b0`](https://github.com/npm/cli/commit/dc6b2a8b032d118be3566ce0fa7c67c171c8d2cb)
[`a3c127446`](https://github.com/npm/cli/commit/a3c1274460e16d1edbdca6a0cee86ef313fdd961)
[#2464](https://github.com/npm/cli/issues/2464)
fix(docs): clean up `npm uninstall` docs
([@wraithgar](https://github.com/wraithgar))
* [`cfdcf32fd`](https://github.com/npm/cli/commit/cfdcf32fd7628501712b8cad4a541c6b8e7b66bc)
[#2474](https://github.com/npm/cli/issues/2474)
fix(docs): clean up `npm unpublish` docs
([@wraithgar](https://github.com/wraithgar))
* [`acd5b062a`](https://github.com/npm/cli/commit/acd5b062a811fcd98849df908ce26855823ca671)
[#2475](https://github.com/npm/cli/issues/2475)
fix(docs): update `package-lock.json` docs
([@isaacs](https://github.com/isaacs))
* [`b0b0edf6d`](https://github.com/npm/cli/commit/b0b0edf6de1678de7f4a000700c88daa5f7194ef)
[#2482](https://github.com/npm/cli/issues/2482)
fix(docs): clean up `npm token` docs
([@wraithgar](https://github.com/wraithgar))
* [`35559201a`](https://github.com/npm/cli/commit/35559201a4a0a5b111ce58d6824e5b4030eb4496)
[#2487](https://github.com/npm/cli/issues/2487)
fix(docs): clean up `npm search` docs
([@wraithgar](https://github.com/wraithgar))
### DEPENDENCIES
* [`ea8c02169`](https://github.com/npm/cli/commit/ea8c02169cfbf0484d67db7c0e7a6ec8aecb7210)
`@npmcli/arborist@2.0.5`
* [`fb6f2c313`](https://github.com/npm/cli/commit/fb6f2c313d1d9770cc7d02a3900c7945df3cb661)
`pacote@11.2.1`
* [`c549b7657`](https://github.com/npm/cli/commit/c549b76573b1835a63e1e5898e9c16860079d84e)
`make-fetch-happen@8.0.13`
## v7.4.0 (2021-01-07)
### FEATURES
deps/npm/docs/content/commands/npm-audit.md
Vendored
-1
View File
@@ -190,5 +190,4 @@ $ npm audit --audit-level=moderate
### See Also
* [npm install](/commands/npm-install)
* [package-locks](/configuring-npm/package-locks)
* [config](/using-npm/config)
deps/npm/docs/content/commands/npm-ci.md
Vendored
+1 -1
View File
@@ -68,4 +68,4 @@ cache:
### See Also
* [npm install](/commands/npm-install)
* [package-locks](/configuring-npm/package-locks)
* [package-lock.json](/configuring-npm/package-lock-json)
deps/npm/docs/content/commands/npm-prefix.md
Vendored
+13 -1
View File
@@ -12,13 +12,25 @@ npm prefix [-g]
### Description
Print the local prefix to standard out. This is the closest parent directory
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.
### Example
```bash
npm prefix
/usr/local/projects/foo
```
```bash
npm prefix -g
/usr/local
```
### See Also
* [npm root](/commands/npm-root)
deps/npm/docs/content/commands/npm-search.md
Vendored
+54 -31
View File
@@ -16,35 +16,42 @@ aliases: s, se, find
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 color is enabled, it will further
highlight the matches in the results.
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 respectively 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 can be used for more
fine-grained filtering. Additionally, both of these can be added to `.npmrc` for
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 `=`.
If a term starts with `/`, then it's interpreted as a regular expression and
supports standard JavaScript RegExp syntax. A trailing `/` will be ignored in
this case. (Note that many regular expression characters must be escaped or
quoted in most shells.)
### A Note on caching
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
All of the following can be defined in a `.npmrc` file, or passed as
parameters to the cli prefixed with `--` (e.g. `--json`)
#### description
* Default: true
* Type: Boolean
Used as `--no-description`, disables search matching in package descriptions and
suppresses display of that field in results.
#### color
* Default: true
* Type: Boolean
Used as `--no-color`, disables color highlighting of matches in the
results.
#### json
@@ -66,9 +73,9 @@ Output search results as lines with tab-separated columns.
* Type: Boolean
Display full package descriptions and other long text across multiple
lines. When disabled (default) search results are truncated to fit
neatly on a single line. Modules with extremely long names will
fall on multiple lines.
lines. When disabled (which is the default) the output will
truncate search results to fit neatly on a single line. Modules with
extremely long names will fall on multiple lines.
#### searchopts
@@ -84,23 +91,37 @@ Space-separated options that are always passed to search.
Space-separated options that limit the results from search.
#### searchstaleness
* Default: 900 (15 minutes)
* Type: Number
The age of the cache, in seconds, before another registry request is made.
#### registry
* Default: https://registry.npmjs.org/
* Type: url
Search the specified registry for modules. If you have configured npm to point
to a different default registry, such as your internal private module
repository, `npm search` will default to that registry when searching. Pass a
different registry url such as the default above in order to override this
setting.
Search the specified registry for modules. If you have configured npm to
point to a different default registry (such as your internal private
module repository), `npm search` will also default to that registry when
searching.
### A note on caching
The npm cli caches search results with the same terms and options
locally in its cache. You can use the following to change how and when
the cli uses this cache. See [`npm cache`](/commands/npm-cache) for more
on how the cache works.
#### prefer-online
Forced staleness checks for cached searches, making the cli look for
updates immediately even for fresh search results.
#### prefer-offline
Bypasses staleness checks for cached. Missing data will still be
requested from the server. To force full offline mode, use `offline`.
#### offline
Forces full offline mode. Any searches not locally cached will result in
an error.
### See Also
@@ -108,3 +129,5 @@ setting.
* [npm config](/commands/npm-config)
* [npmrc](/configuring-npm/npmrc)
* [npm view](/commands/npm-view)
* [npm cache](/commands/npm-cache)
* https://npm.im/npm-registry-fetch
deps/npm/docs/content/commands/npm-shrinkwrap.md
Vendored
+7 -7
View File
@@ -13,18 +13,18 @@ npm shrinkwrap
### 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-locks](/configuring-npm/package-locks).
`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
* [npm install](/commands/npm-install)
* [npm run-script](/commands/npm-run-script)
* [npm scripts](/using-npm/scripts)
* [package.js](/configuring-npm/package-json)
* [package-locks](/configuring-npm/package-locks)
* [package.json](/configuring-npm/package-json)
* [package-lock.json](/configuring-npm/package-lock-json)
* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
* [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json)
* [npm ls](/commands/npm-ls)
deps/npm/docs/content/commands/npm-start.md
Vendored
+29 -3
View File
@@ -12,13 +12,39 @@ npm start [-- <args>]
### Description
This runs an arbitrary command specified in the package's `"start"` property of
its `"scripts"` object. If no `"start"` property is specified on the
`"scripts"` object, it will run `node server.js`.
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`.
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-script`](/commands/npm-run-script) for more details.
### Example
```json
{
"scripts": {
"start": "node foo.js"
}
}
```
```bash
npm start
> npm@x.x.x start
> node foo.js
(foo.js output would be here)
```
### See Also
* [npm run-script](/commands/npm-run-script)
deps/npm/docs/content/commands/npm-stop.md
Vendored
+25 -1
View File
@@ -12,7 +12,31 @@ npm stop [-- <args>]
### Description
This runs a package's "stop" script, if one was provided.
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.
### Example
```json
{
"scripts": {
"stop": "node bar.js"
}
}
```
```bash
npm stop
> npm@x.x.x stop
> node bar.js
(bar.js output would be here)
```
### See Also
deps/npm/docs/content/commands/npm-test.md
Vendored
+22 -1
View File
@@ -14,7 +14,28 @@ aliases: t, tst
### Description
This runs a package's "test" script, if one was provided.
This runs a predefined command specified in the `"test"` property of
a package's `"scripts"` object.
### Example
```json
{
"scripts": {
"test": "node test.js"
}
}
```
```bash
npm test
> npm@x.x.x test
> node test.js
(test.js output would be here)
```
### See Also
deps/npm/docs/content/commands/npm-token.md
Vendored
+19 -10
View File
@@ -16,8 +16,8 @@ description: Manage your authentication tokens
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`.
```bash
+--------+---------+------------+----------+----------------+
@@ -40,10 +40,17 @@ This lets you list, create and revoke authentication tokens.
```
* `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 to
limit use of this token to. 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.
```bash
+----------------+--------------------------------------+
@@ -58,7 +65,9 @@ This lets you list, create and revoke authentication tokens.
```
* `npm token revoke <token|id>`:
This removes an authentication token, making it immediately unusable. This can accept
both complete tokens (as you get back from `npm token create` and will
find in your `.npmrc`) and ids as seen in the `npm token list` output.
This will NOT accept the truncated token found in `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.
deps/npm/docs/content/commands/npm-uninstall.md
Vendored
+28 -25
View File
@@ -7,7 +7,7 @@ description: Remove a package
### Synopsis
```bash
npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|-D|--save-dev|-O|--save-optional|--no-save]
npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]
aliases: remove, rm, r, un, unlink
```
@@ -17,40 +17,43 @@ aliases: remove, rm, r, un, unlink
This uninstalls a package, completely removing everything npm installed
on its behalf.
Example:
It also removes the package from the `dependencies`, `devDependencies`,
`optionalDependencies`, and `peerDependencies` objects in your
`package.json`.
Futher, 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.
`--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.
`--no-save` is ignored in this case.
Scope is optional and follows the usual rules for [`scope`](/using-npm/scope).
### Examples
```bash
npm uninstall sax
```
In global mode (ie, with `-g` or `--global` appended to the command),
it uninstalls the current package context as a global package.
`sax` will no longer be in your `package.json`, `npm-shrinkwrap.json`, or
`package-lock.json` files.
`npm uninstall` takes 3 exclusive, optional flags which save or update
the package version in your main package.json:
* `-S, --save`: Package will be removed from your `dependencies`.
* `-D, --save-dev`: Package will be removed from your `devDependencies`.
* `-O, --save-optional`: Package will be removed from your `optionalDependencies`.
* `--no-save`: Package will not be removed from your `package.json` file.
Further, if you have an `npm-shrinkwrap.json` then it will be updated as
well.
Scope is optional and follows the usual rules for [`scope`](/using-npm/scope).
Examples:
```bash
npm uninstall sax --save
npm uninstall @myorg/privatepackage --save
npm uninstall node-tap --save-dev
npm uninstall dtrace-provider --save-optional
npm uninstall lodash --no-save
```
`lodash` will not be removed from your `package.json`,
`npm-shrinkwrap.json`, or `package-lock.json` files.
### See Also
* [npm prune](/commands/npm-prune)
deps/npm/docs/content/commands/npm-unpublish.md
Vendored
+19 -10
View File
@@ -6,6 +6,10 @@ description: Remove a package from the registry
### Synopsis
To learn more about how the npm registry treats unpublish, see our <a
href="https://www.npmjs.com/policies/unpublish" target="_blank"
rel="noopener noreferrer"> unpublish policies</a>
#### Unpublishing a single version of a package
```bash
@@ -20,22 +24,26 @@ npm unpublish [<@scope>/]<pkg> --force
### Warning
Consider using the `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.
If no version is specified, or if all versions are removed then
the root package entry is removed from the registry entirely.
The npm registry will return an error if you are not [logged
in](/commands/npm-login).
Even if a package version is unpublished, that specific name and
version combination can never be reused. In order to publish the
package again, a new version number must be used. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.
To learn more about how unpublish is treated on the npm registry, see our <a href="https://www.npmjs.com/policies/unpublish" target="_blank" rel="noopener noreferrer"> unpublish policies</a>.
If you 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.
### See Also
@@ -44,3 +52,4 @@ To learn more about how unpublish is treated on the npm registry, see our <a hre
* [npm registry](/using-npm/registry)
* [npm adduser](/commands/npm-adduser)
* [npm owner](/commands/npm-owner)
* [npm login](/commands/npm-login)
deps/npm/docs/content/configuring-npm/install.md
Vendored
+37 -16
View File
@@ -6,17 +6,27 @@ 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-node-js)
- [Using a Node version manager to install Node.js and npm](#using-a-node-version-manager-to-install-node-js-and-npm)
- [Using a Node installer to install Node.js and npm](#using-a-node-installer-to-install-node-js-and-npm)
- [Checking your version of npm and
Node.js](#checking-your-version-of-npm-and-node-js)
- [Using a Node version manager to install Node.js and
npm](#using-a-node-version-manager-to-install-node-js-and-npm)
- [Using a Node installer to install Node.js and
npm](#using-a-node-installer-to-install-node-js-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
@@ -25,7 +35,10 @@ 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.
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.
#### OSX or Linux Node version managers
@@ -39,28 +52,36 @@ Node version managers allow you to install and switch between multiple versions
### 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.
#### OS X or Windows Node installers
If you're using OS X 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 OS X 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/)
Or see [this page](https://nodejs.org/en/download/package-manager/) to install npm for Linux in the way many Linux developers prefer.
- [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.
#### Less-common operating systems
For more information on installing Node.js on a variety of operating systems, see [this page][pkg-mgr].
For more information on installing Node.js on a variety of operating
systems, see [this page][pkg-mgr].
[pkg-mgr]: https://nodejs.org/en/download/package-manager/
deps/npm/docs/content/configuring-npm/shrinkwrap-json.md → deps/npm/docs/content/configuring-npm/npm-shrinkwrap-json.md
Vendored
+12 -8
View File
@@ -1,26 +1,30 @@
---
title: shrinkwrap.json
title: npm-shrinkwrap.json
section: 5
description: A publishable lockfile
---
### Description
`npm-shrinkwrap.json` is a file created by [`npm shrinkwrap`](/commands/npm-shrinkwrap). It is identical to
`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.
strongly discouraged for library authors to publish this file, since that
would prevent end users from having control over transitive dependency
updates.
Additionally, if both `package-lock.json` and `npm-shrinkwrap.json` are present
in a package root, `package-lock.json` will be ignored in favor of this 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
deps/npm/docs/content/configuring-npm/npmrc.md
Vendored
+27 -26
View File
@@ -6,13 +6,14 @@ 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
@@ -23,20 +24,19 @@ The four relevant files are:
* global config file ($PREFIX/etc/npmrc)
* 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}`. For example:
All npm config files are an ini-formatted list of `key = value` parameters.
Environment variables can be replaced using `${VARIABLE_NAME}`. For
example:
```bash
prefix = ${HOME}/.npm-packages
```
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"
@@ -45,7 +45,9 @@ key[] = "second value"
#### Comments
Lines in `.npmrc` files are interpreted as comments when they begin with a `;` or `#` character. `.npmrc` files are parsed by [npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
Lines in `.npmrc` files are interpreted as comments when they begin with a
`;` or `#` character. `.npmrc` files are parsed by
[npm/ini](https://github.com/npm/ini), which specifies this comment syntax.
For example:
@@ -61,24 +63,24 @@ 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`.
#### 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
@@ -86,9 +88,8 @@ Environment variables can be replaced as above.
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.
script that comes with npm. This is primarily for distribution maintainers
to override default configs in a standard and consistent manner.
### See also
deps/npm/docs/content/configuring-npm/package-json.md
Vendored
+408 -335
View File
File diff suppressed because it is too large. Load diff
deps/npm/docs/content/configuring-npm/package-lock-json.md
Vendored
+182 -91
View File
@@ -14,132 +14,223 @@ generate identical trees, regardless of intermediate dependency updates.
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.
* To facilitate greater visibility of tree changes through readable source control diffs.
* Facilitate greater visibility of tree changes through readable source
control diffs.
* And 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.
One key detail about `package-lock.json` is that it cannot be published, and it
will be ignored if found in any place other than the toplevel package. It shares
a format with [npm-shrinkwrap.json](/configuring-npm/shrinkwrap-json), which is essentially the same file, but
allows publication. This is not recommended unless deploying a CLI tool or
otherwise using the publication process for producing production 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.
If both `package-lock.json` and `npm-shrinkwrap.json` are present in the root of
a package, `package-lock.json` will be completely ignored.
### `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.
The difference is that `package-lock.json` is that it 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.
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:
- 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.
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`.
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.
### File Format
#### name
#### `name`
The name of the package this is a package-lock for. This must 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
#### `version`
The version of the package this is a package-lock for. This must 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
#### `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`.
#### packageIntegrity
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`.
This is a [subresource
integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) value
created from the `package.json`. No preprocessing of the `package.json` should
be done. Subresource integrity strings can be produced by modules like
[`ssri`](https://www.npmjs.com/package/ssri).
* 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, which is backwards compatible
to v1 lockfiles.
* `3`: The lockfile version used by npm v7, _without_ backwards
compatibility affordances. This is used for the hidden lockfile at
`node_modules/.package-lock.json`, and will likely be used in a future
version of npm, once support for npm v6 is no longer relevant.
#### preserveSymlinks
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.
Indicates that the install was done with the environment variable
`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of
this property match that environment variable.
#### `packages`
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.
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.
* 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.
* 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.)
* 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.
* hasShrinkwrap: A flag to indicate that the package has an
`npm-shrinkwrap.json` file.
* bin, license, engines, dependencies, optionalDependencies: fields from
`package.json`
#### dependencies
A mapping of package name to dependency object. Dependency objects have the
following properties:
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.
##### version
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.
This is a specifier that uniquely identifies this package and should be
usable in fetching a new copy of it.
Dependency objects have the following fields:
* 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`)
* version: a specifier that varies depending on the nature of the package,
and is usable in fetching a new copy of it.
##### integrity
* 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`)
This is a [Standard Subresource
Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for this
resource.
* 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.
* For bundled dependencies this is not included, regardless of source.
* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
* For git sources this is the specific commit hash we cloned from.
* For remote tarball sources this is an integrity based on a SHA512 of
the file.
* For local tarball sources: This is an integrity field based on the SHA512 of the file.
* 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.
##### resolved
* 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.
* For bundled dependencies this is not included, regardless of source.
* 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.
* 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.
##### bundled
* 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.
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.
* 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.
##### 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.
All optional dependencies should be included even if they're uninstallable
on the current platform.
##### 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
* [npm shrinkwrap](/commands/npm-shrinkwrap)
* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
* [package-locks](/configuring-npm/package-locks)
* [npm-shrinkwrap.json](/configuring-npm/npm-shrinkwrap-json)
* [package.json](/configuring-npm/package-json)
* [npm install](/commands/npm-install)
deps/npm/docs/content/configuring-npm/package-locks.md
Vendored
-178
View File
@@ -1,178 +0,0 @@
---
title: package-locks
section: 5
description: An explanation of npm lockfiles
---
### Description
Conceptually, the "input" to [`npm install`](/commands/npm-install) is a [package.json](/configuring-npm/package-json), while its
"output" is a fully-formed `node_modules` tree: a representation of the
dependencies you declared. In an ideal world, npm would work like a pure
function: the same `package.json` should produce the exact same `node_modules`
tree, any time. In some cases, this is indeed true. But in many others, npm is
unable to do this. There are multiple reasons for this:
* different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
* a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
* A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`)
* The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
As an example, consider package A:
```json
{
"name": "A",
"version": "0.1.0",
"dependencies": {
"B": "<0.1.0"
}
}
```
package B:
```json
{
"name": "B",
"version": "0.0.1",
"dependencies": {
"C": "<0.1.0"
}
}
```
and package C:
```json
{
"name": "C",
"version": "0.0.1"
}
```
If these are the only versions of A, B, and C available in the
registry, then a normal `npm install A` will install:
```json
A@0.1.0
`-- B@0.0.1
`-- C@0.0.1
```
However, if B@0.0.2 is published, then a fresh `npm install A` will
install:
```bash
A@0.1.0
`-- B@0.0.2
`-- C@0.0.1
```
assuming the new version did not modify B's dependencies. Of course,
the new version of B could include a new version of C and any number
of new dependencies. If such changes are undesirable, the author of A
could specify a dependency on B@0.0.1. However, if A's author and B's
author are not the same person, there's no way for A's author to say
that he or she does not want to pull in newly published versions of C
when B hasn't changed at all.
To prevent this potential issue, npm uses [package-lock.json](/configuring-npm/package-lock-json) or, if present, [npm-shrinkwrap.json](/configuring-npm/shrinkwrap-json). These files are called package locks, or lockfiles.
Whenever you run `npm install`, npm generates or updates your package lock,
which will look something like this:
```json
{
"name": "A",
"version": "0.1.0",
...metadata fields...
"dependencies": {
"B": {
"version": "0.0.1",
"resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
"integrity": "sha512-DeAdb33F+"
"dependencies": {
"C": {
"version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
}
}
}
}
}
```
This file describes an *exact*, and more importantly *reproducible*
`node_modules` tree. Once it's present, any future installation will base its
work off this file, instead of recalculating dependency versions off
[package.json](/configuring-npm/package-json).
The presence of a package lock changes the installation behavior such that:
1. The module tree described by the package lock is reproduced. This means
reproducing the structure described in the file, using the specific files
referenced in "resolved" if available, falling back to normal package resolution
using "version" if one isn't.
2. The tree is walked and any missing dependencies are installed in the usual
fashion.
If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts`
property of the `package.json`, they will be executed in order. `preshrinkwrap`
and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
executed afterwards. These scripts run for both `package-lock.json` and
`npm-shrinkwrap.json`. For example to run some postprocessing on the generated
file:
```json
"scripts": {
"postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
}
```
#### Using locked packages
Using a locked package is no different than using any package without a package
lock: any commands that update `node_modules` and/or `package.json`'s
dependencies will automatically sync the existing lockfile. This includes `npm
install`, `npm rm`, `npm update`, etc. To prevent this update from happening,
you can use the `--no-save` option to prevent saving altogether, or
`--no-shrinkwrap` to allow `package.json` to be updated while leaving
`package-lock.json` or `npm-shrinkwrap.json` intact.
It is highly recommended you commit the generated package lock to source
control: this will allow anyone else on your team, your deployments, your
CI/continuous integration, and anyone else who runs `npm install` in your
package source to get the exact same dependency tree that you were developing
on. Additionally, the diffs from these changes are human-readable and will
inform you of any changes npm has made to your `node_modules`, so you can notice
if any transitive dependencies were updated, hoisted, etc.
#### Resolving lockfile conflicts
Occasionally, two separate npm install will create package locks that cause
merge conflicts in source control systems. As of `npm@5.7.0`, these conflicts
can be resolved by manually fixing any `package.json` conflicts, and then
running `npm install [--package-lock-only]` again. npm will automatically
resolve any conflicts for you and write a merged package lock that includes all
the dependencies from both branches in a reasonable tree. If
`--package-lock-only` is provided, it will do this without also modifying your
local `node_modules/`.
To make this process seamless on git, consider installing
[`npm-merge-driver`](https://npm.im/npm-merge-driver), which will teach git how
to do this itself without any user interaction. In short: `$ npx
npm-merge-driver install -g` will let you do this, and even works with
pre-`npm@5.7.0` versions of npm 5, albeit a bit more noisily. Note that if
`package.json` itself conflicts, you will have to resolve that by hand and run
`npm install` manually, even with the merge driver.
### See Also
* https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
* [package.json](/configuring-npm/package-json)
* [package-lock.json](/configuring-npm/package-lock-json)
* [shrinkwrap.json](/configuring-npm/shrinkwrap-json)
* [npm shrinkwrap](/commands/npm-shrinkwrap)
deps/npm/docs/output/commands/npm-audit.html
Vendored
-1
View File
@@ -271,7 +271,6 @@ fixing anything:</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-install.html">npm install</a></li>
<li><a href="../configuring-npm/package-locks.html">package-locks</a></li>
<li><a href="../using-npm/config.html">config</a></li>
</ul>
</div>
deps/npm/docs/output/commands/npm-ci.html
Vendored
+1 -1
View File
@@ -193,7 +193,7 @@ cache:
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-install.html">npm install</a></li>
<li><a href="../configuring-npm/package-locks.html">package-locks</a></li>
<li><a href="../configuring-npm/package-lock-json.html">package-lock.json</a></li>
</ul>
</div>
deps/npm/docs/output/commands/npm-ls.html
Vendored
+1 -1
View File
@@ -159,7 +159,7 @@ tree at all, use <a href="../commands/npm-explain.html"><code>npm explain</code>
the results to only the paths to the packages named. Note that nested
packages will <em>also</em> show the paths to the specified packages. For
example, running <code>npm ls promzard</code> in npm’s source tree will show:</p>
<pre lang="bash"><code>npm@7.4.0 /path/to/npm
<pre lang="bash"><code>npm@7.4.2 /path/to/npm
└─┬ init-package-json@0.0.4
└── promzard@0.1.5
</code></pre>
deps/npm/docs/output/commands/npm-prefix.html
Vendored
+9 -2
View File
@@ -141,18 +141,25 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#example">Example</a></li><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
<pre lang="bash"><code>npm prefix [-g]
</code></pre>
<h3 id="description">Description</h3>
<p>Print the local prefix to standard out. This is the closest parent directory
<p>Print the local prefix to standard output. This is the closest parent directory
to contain a <code>package.json</code> file or <code>node_modules</code> directory, unless <code>-g</code> is
also specified.</p>
<p>If <code>-g</code> is specified, this will be the value of the global prefix. See
<a href="../commands/npm-config.html"><code>npm config</code></a> for more detail.</p>
<h3 id="example">Example</h3>
<pre lang="bash"><code>npm prefix
/usr/local/projects/foo
</code></pre>
<pre lang="bash"><code>npm prefix -g
/usr/local
</code></pre>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-root.html">npm root</a></li>
deps/npm/docs/output/commands/npm-search.html
Vendored
+46 -30
View File
@@ -141,7 +141,7 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#a-note-on-caching">A Note on caching</a></li><li><a href="#configuration">Configuration</a></li><ul><li><a href="#description2">description</a></li><li><a href="#json">json</a></li><li><a href="#parseable">parseable</a></li><li><a href="#long">long</a></li><li><a href="#searchopts">searchopts</a></li><li><a href="#searchexclude">searchexclude</a></li><li><a href="#searchstaleness">searchstaleness</a></li><li><a href="#registry">registry</a></li></ul><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#configuration">Configuration</a></li><ul><li><a href="#description2">description</a></li><li><a href="#color">color</a></li><li><a href="#json">json</a></li><li><a href="#parseable">parseable</a></li><li><a href="#long">long</a></li><li><a href="#searchopts">searchopts</a></li><li><a href="#searchexclude">searchexclude</a></li><li><a href="#registry">registry</a></li></ul><li><a href="#a-note-on-caching">A note on caching</a></li><ul><li><a href="#prefer-online">prefer-online</a></li><li><a href="#prefer-offline">prefer-offline</a></li><li><a href="#offline">offline</a></li></ul><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
@@ -152,29 +152,36 @@ aliases: s, se, find
<h3 id="description">Description</h3>
<p>Search the registry for packages matching the search terms. <code>npm search</code>
performs a linear, incremental, lexically-ordered search through package
metadata for all files in the registry. If color is enabled, it will further
highlight the matches in the results.</p>
<p>Additionally, using the <code>--searchopts</code> and <code>--searchexclude</code> options paired with
more search terms will respectively include and exclude further patterns. The
main difference between <code>--searchopts</code> and the standard search terms is that the
former does not highlight results in the output and can be used for more
fine-grained filtering. Additionally, both of these can be added to <code>.npmrc</code> for
default search filtering behavior.</p>
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 <code>color</code></p>
<p>Additionally, using the <code>--searchopts</code> and <code>--searchexclude</code> options
paired with more search terms will include and exclude further patterns.
The main difference between <code>--searchopts</code> 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.</p>
<p>Search also allows targeting of maintainers in search results, by prefixing
their npm username with <code>=</code>.</p>
<p>If a term starts with <code>/</code>, then it’s interpreted as a regular expression and
supports standard JavaScript RegExp syntax. A trailing <code>/</code> will be ignored in
this case. (Note that many regular expression characters must be escaped or
quoted in most shells.)</p>
<h3 id="a-note-on-caching">A Note on caching</h3>
<p>If a term starts with <code>/</code>, then it’s interpreted as a regular expression
and supports standard JavaScript RegExp syntax. In this case search will
ignore a trailing <code>/</code> . (Note you must escape or quote many regular
expression characters in most shells.)</p>
<h3 id="configuration">Configuration</h3>
<p>All of the following can be defined in a <code>.npmrc</code> file, or passed as
parameters to the cli prefixed with <code>--</code> (e.g. <code>--json</code>)</p>
<h4 id="description2">description</h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>Used as <code>--no-description</code>, disables search matching in package descriptions and
suppresses display of that field in results.</p>
<h4 id="color">color</h4>
<ul>
<li>Default: true</li>
<li>Type: Boolean</li>
</ul>
<p>Used as <code>--no-color</code>, disables color highlighting of matches in the
results.</p>
<h4 id="json">json</h4>
<ul>
<li>Default: false</li>
@@ -193,9 +200,9 @@ suppresses display of that field in results.</p>
<li>Type: Boolean</li>
</ul>
<p>Display full package descriptions and other long text across multiple
lines. When disabled (default) search results are truncated to fit
neatly on a single line. Modules with extremely long names will
fall on multiple lines.</p>
lines. When disabled (which is the default) the output will
truncate search results to fit neatly on a single line. Modules with
extremely long names will fall on multiple lines.</p>
<h4 id="searchopts">searchopts</h4>
<ul>
<li>Default: “”</li>
@@ -208,28 +215,37 @@ fall on multiple lines.</p>
<li>Type: String</li>
</ul>
<p>Space-separated options that limit the results from search.</p>
<h4 id="searchstaleness">searchstaleness</h4>
<ul>
<li>Default: 900 (15 minutes)</li>
<li>Type: Number</li>
</ul>
<p>The age of the cache, in seconds, before another registry request is made.</p>
<h4 id="registry">registry</h4>
<ul>
<li>Default: <a href="https://registry.npmjs.org/">https://registry.npmjs.org/</a></li>
<li>Type: url</li>
</ul>
<p>Search the specified registry for modules. If you have configured npm to point
to a different default registry, such as your internal private module
repository, <code>npm search</code> will default to that registry when searching. Pass a
different registry url such as the default above in order to override this
setting.</p>
<p>Search the specified registry for modules. If you have configured npm to
point to a different default registry (such as your internal private
module repository), <code>npm search</code> will also default to that registry when
searching.</p>
<h3 id="a-note-on-caching">A note on caching</h3>
<p>The npm cli caches search results with the same terms and options
locally in its cache. You can use the following to change how and when
the cli uses this cache. See <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>Forced staleness checks for cached searches, making the cli look for
updates immediately even for fresh search results.</p>
<h4 id="prefer-offline">prefer-offline</h4>
<p>Bypasses staleness checks for cached. 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 searches not locally cached will result in
an error.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../using-npm/registry.html">npm registry</a></li>
<li><a href="../commands/npm-config.html">npm config</a></li>
<li><a href="../configuring-npm/npmrc.html">npmrc</a></li>
<li><a href="../commands/npm-view.html">npm view</a></li>
<li><a href="../commands/npm-cache.html">npm cache</a></li>
<li><a href="https://npm.im/npm-registry-fetch">https://npm.im/npm-registry-fetch</a></li>
</ul>
</div>
deps/npm/docs/output/commands/npm-shrinkwrap.html
Vendored
+7 -7
View File
@@ -149,19 +149,19 @@ npm command-line interface
</code></pre>
<h3 id="description">Description</h3>
<p>This command repurposes <code>package-lock.json</code> into a publishable
<code>npm-shrinkwrap.json</code> or simply creates a new one. The file created and updated
by this command will then take precedence over any other existing or future
<code>package-lock.json</code> files. For a detailed explanation of the design and purpose
of package locks in npm, see <a href="../configuring-npm/package-locks.html">package-locks</a>.</p>
<code>npm-shrinkwrap.json</code> or simply creates a new one. The file created and
updated by this command will then take precedence over any other existing
or future <code>package-lock.json</code> files. For a detailed explanation of the
design and purpose of package locks in npm, see
<a href="../configuring-npm/package-lock-json.html">package-lock-json</a>.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-install.html">npm install</a></li>
<li><a href="../commands/npm-run-script.html">npm run-script</a></li>
<li><a href="../using-npm/scripts.html">npm scripts</a></li>
<li><a href="../configuring-npm/package-json.html">package.js</a></li>
<li><a href="../configuring-npm/package-locks.html">package-locks</a></li>
<li><a href="../configuring-npm/package-json.html">package.json</a></li>
<li><a href="../configuring-npm/package-lock-json.html">package-lock.json</a></li>
<li><a href="../configuring-npm/shrinkwrap-json.html">shrinkwrap.json</a></li>
<li><a href="../configuring-npm/npm-shrinkwrap-json.html">npm-shrinkwrap.json</a></li>
<li><a href="../commands/npm-ls.html">npm ls</a></li>
</ul>
</div>
deps/npm/docs/output/commands/npm-start.html
Vendored
+23 -4
View File
@@ -141,18 +141,37 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#example">Example</a></li><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
<pre lang="bash"><code>npm start [-- &lt;args&gt;]
</code></pre>
<h3 id="description">Description</h3>
<p>This runs an arbitrary command specified in the package’s <code>"start"</code> property of
its <code>"scripts"</code> object. If no <code>"start"</code> property is specified on the
<code>"scripts"</code> object, it will run <code>node server.js</code>.</p>
<p>This runs a predefined command specified in the <code>"start"</code> property of
a package’s <code>"scripts"</code> object.</p>
<p>If the <code>"scripts"</code> object does not define a <code>"start"</code> property, npm
will run <code>node server.js</code>.</p>
<p>Note that this is different from the default node behavior of running
the file specified in a package’s <code>"main"</code> attribute when evoking with
<code>node .</code></p>
<p>As of <a href="https://blog.npmjs.org/post/98131109725/npm-2-0-0"><code>npm@2.0.0</code></a>, you can
use custom arguments when executing scripts. Refer to <a href="../commands/npm-run-script.html"><code>npm run-script</code></a> for more details.</p>
<h3 id="example">Example</h3>
<pre lang="json"><code>{
"scripts": {
"start": "node foo.js"
}
}
</code></pre>
<pre lang="bash"><code>npm start
&gt; npm@x.x.x start
&gt; node foo.js
(foo.js output would be here)
</code></pre>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-run-script.html">npm run-script</a></li>
deps/npm/docs/output/commands/npm-stop.html
Vendored
+20 -2
View File
@@ -141,14 +141,32 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#example">Example</a></li><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
<pre lang="bash"><code>npm stop [-- &lt;args&gt;]
</code></pre>
<h3 id="description">Description</h3>
<p>This runs a package’s “stop” script, if one was provided.</p>
<p>This runs a predefined command specified in the “stop” property of a
package’s “scripts” object.</p>
<p>Unlike with <a href="../commands/npm-start.html">npm start</a>, there is no default script
that will run if the <code>"stop"</code> property is not defined.</p>
<h3 id="example">Example</h3>
<pre lang="json"><code>{
"scripts": {
"stop": "node bar.js"
}
}
</code></pre>
<pre lang="bash"><code>npm stop
&gt; npm@x.x.x stop
&gt; node bar.js
(bar.js output would be here)
</code></pre>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-run-script.html">npm run-script</a></li>
deps/npm/docs/output/commands/npm-test.html
Vendored
+16 -2
View File
@@ -141,7 +141,7 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#example">Example</a></li><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
@@ -150,7 +150,21 @@ npm command-line interface
aliases: t, tst
</code></pre>
<h3 id="description">Description</h3>
<p>This runs a package’s “test” script, if one was provided.</p>
<p>This runs a predefined command specified in the <code>"test"</code> property of
a package’s <code>"scripts"</code> object.</p>
<h3 id="example">Example</h3>
<pre lang="json"><code>{
"scripts": {
"test": "node test.js"
}
}
</code></pre>
<pre lang="bash"><code>npm test
&gt; npm@x.x.x test
&gt; node test.js
(test.js output would be here)
</code></pre>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-run-script.html">npm run-script</a></li>
deps/npm/docs/output/commands/npm-token.html
Vendored
+21 -11
View File
@@ -153,8 +153,8 @@ npm command-line interface
<p>This lets you list, create and revoke authentication tokens.</p>
<ul>
<li><code>npm token list</code>:
Shows a table of all active authentication tokens. You can request this as
JSON with <code>--json</code> or tab-separated values with <code>--parseable</code>.</li>
Shows a table of all active authentication tokens. You can request
this as JSON with <code>--json</code> or tab-separated values with <code>--parseable</code>.</li>
</ul>
<pre lang="bash"><code>+--------+---------+------------+----------+----------------+
| id | token | created | read-only | CIDR whitelist |
@@ -175,11 +175,19 @@ JSON with <code>--json</code> or tab-separated values with <code>--parseable</co
+--------+---------+------------+----------+----------------+
</code></pre>
<ul>
<li><code>npm token create [--read-only] [--cidr=&lt;cidr-ranges&gt;]</code>:
Create a new authentication token. It can be <code>--read-only</code> or accept a list of
<a href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing">CIDR</a> ranges to
limit use of this token to. This will prompt you for your password, and, if you have
two-factor authentication enabled, an otp.</li>
<li>
<p><code>npm token create [--read-only] [--cidr=&lt;cidr-ranges&gt;]</code>:
Create a new authentication token. It can be <code>--read-only</code>, or accept
a list of
<a href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing">CIDR</a>
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.</p>
<p>Currently, the cli can not generate automation tokens. Please refer to
the <a href="https://docs.npmjs.com/creating-and-viewing-access-tokens">docs
website</a>
for more information on generating automation tokens.</p>
</li>
</ul>
<pre lang="bash"><code>+----------------+--------------------------------------+
| token | a73c9572-f1b9-8983-983d-ba3ac3cc913d |
@@ -193,10 +201,12 @@ two-factor authentication enabled, an otp.</li>
</code></pre>
<ul>
<li><code>npm token revoke &lt;token|id&gt;</code>:
This removes an authentication token, making it immediately unusable. This can accept
both complete tokens (as you get back from <code>npm token create</code> and will
find in your <code>.npmrc</code>) and ids as seen in the <code>npm token list</code> output.
This will NOT accept the truncated token found in <code>npm token list</code> output.</li>
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 <code>npm token create</code>, and those
found in your <code>.npmrc</code>), and ids as seen in the parseable or json
output of <code>npm token list</code>. This will NOT accept the truncated token
found in the normal <code>npm token list</code> output.</li>
</ul>
</div>
deps/npm/docs/output/commands/npm-uninstall.html
Vendored
+23 -30
View File
@@ -141,48 +141,41 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#see-also">See Also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#synopsis">Synopsis</a></li><li><a href="#description">Description</a></li><li><a href="#examples">Examples</a></li><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
<pre lang="bash"><code>npm uninstall [&lt;@scope&gt;/]&lt;pkg&gt;[@&lt;version&gt;]... [-S|--save|-D|--save-dev|-O|--save-optional|--no-save]
<pre lang="bash"><code>npm uninstall [&lt;@scope&gt;/]&lt;pkg&gt;[@&lt;version&gt;]... [-S|--save|--no-save]
aliases: remove, rm, r, un, unlink
</code></pre>
<h3 id="description">Description</h3>
<p>This uninstalls a package, completely removing everything npm installed
on its behalf.</p>
<p>Example:</p>
<p>It also removes the package from the <code>dependencies</code>, <code>devDependencies</code>,
<code>optionalDependencies</code>, and <code>peerDependencies</code> objects in your
<code>package.json</code>.</p>
<p>Futher, if you have an <code>npm-shrinkwrap.json</code> or <code>package-lock.json</code>, npm
will update those files as well.</p>
<p><code>--no-save</code> will tell npm not to remove the package from your
<code>package.json</code>, <code>npm-shrinkwrap.json</code>, or <code>package-lock.json</code> files.</p>
<p><code>--save</code> or <code>-S</code> will tell npm to remove the package from your
<code>package.json</code>, <code>npm-shrinkwrap.json</code>, and <code>package-lock.json</code> files.
This is the default, but you may need to use this if you have for
instance <code>save=false</code> in your <code>npmrc</code> file</p>
<p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
it uninstalls the current package context as a global package.
<code>--no-save</code> is ignored in this case.</p>
<p>Scope is optional and follows the usual rules for <a href="../using-npm/scope.html"><code>scope</code></a>.</p>
<h3 id="examples">Examples</h3>
<pre lang="bash"><code>npm uninstall sax
</code></pre>
<p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
it uninstalls the current package context as a global package.</p>
<p><code>npm uninstall</code> takes 3 exclusive, optional flags which save or update
the package version in your main package.json:</p>
<ul>
<li>
<p><code>-S, --save</code>: Package will be removed from your <code>dependencies</code>.</p>
</li>
<li>
<p><code>-D, --save-dev</code>: Package will be removed from your <code>devDependencies</code>.</p>
</li>
<li>
<p><code>-O, --save-optional</code>: Package will be removed from your <code>optionalDependencies</code>.</p>
</li>
<li>
<p><code>--no-save</code>: Package will not be removed from your <code>package.json</code> file.</p>
</li>
</ul>
<p>Further, if you have an <code>npm-shrinkwrap.json</code> then it will be updated as
well.</p>
<p>Scope is optional and follows the usual rules for <a href="../using-npm/scope.html"><code>scope</code></a>.</p>
<p>Examples:</p>
<pre lang="bash"><code>npm uninstall sax --save
npm uninstall @myorg/privatepackage --save
npm uninstall node-tap --save-dev
npm uninstall dtrace-provider --save-optional
npm uninstall lodash --no-save
<p><code>sax</code> will no longer be in your <code>package.json</code>, <code>npm-shrinkwrap.json</code>, or
<code>package-lock.json</code> files.</p>
<pre lang="bash"><code>npm uninstall lodash --no-save
</code></pre>
<p><code>lodash</code> will not be removed from your <code>package.json</code>,
<code>npm-shrinkwrap.json</code>, or <code>package-lock.json</code> files.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-prune.html">npm prune</a></li>
deps/npm/docs/output/commands/npm-unpublish.html
Vendored
+16 -9
View File
@@ -145,6 +145,7 @@ npm command-line interface
</section>
<div id="_content"><h3 id="synopsis">Synopsis</h3>
<p>To learn more about how the npm registry treats unpublish, see our <!-- raw HTML omitted --> unpublish policies<!-- raw HTML omitted --></p>
<h4 id="unpublishing-a-single-version-of-a-package">Unpublishing a single version of a package</h4>
<pre lang="bash"><code>npm unpublish [&lt;@scope&gt;/]&lt;pkg&gt;@&lt;version&gt;
</code></pre>
@@ -152,16 +153,21 @@ npm command-line interface
<pre lang="bash"><code>npm unpublish [&lt;@scope&gt;/]&lt;pkg&gt; --force
</code></pre>
<h3 id="warning">Warning</h3>
<p>Consider using the <code>deprecate</code> command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package.</p>
<p>Consider using the <a href="../commands/npm-deprecate.html"><code>deprecate</code></a> command instead,
if your intent is to encourage users to upgrade, or if you no longer
want to maintain a package.</p>
<h3 id="description">Description</h3>
<p>This removes a package version from the registry, deleting its
entry and removing the tarball.</p>
<p>If no version is specified, or if all versions are removed then
the root package entry is removed from the registry entirely.</p>
<p>Even if a package version is unpublished, that specific name and
version combination can never be reused. In order to publish the
package again, a new version number must be used. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.</p>
<p>To learn more about how unpublish is treated on the npm registry, see our <!-- raw HTML omitted --> unpublish policies<!-- raw HTML omitted -->.</p>
<p>This removes a package version from the registry, deleting its entry and
removing the tarball.</p>
<p>The npm registry will return an error if you are not <a href="../commands/npm-login.html">logged
in</a>.</p>
<p>If you 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.</p>
<p>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.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="../commands/npm-deprecate.html">npm deprecate</a></li>
@@ -169,6 +175,7 @@ package again, a new version number must be used. If you unpublish the entire pa
<li><a href="../using-npm/registry.html">npm registry</a></li>
<li><a href="../commands/npm-adduser.html">npm adduser</a></li>
<li><a href="../commands/npm-owner.html">npm owner</a></li>
<li><a href="../commands/npm-login.html">npm login</a></li>
</ul>
</div>
deps/npm/docs/output/commands/npm.html
Vendored
+1 -1
View File
@@ -148,7 +148,7 @@ npm command-line interface
<pre lang="bash"><code>npm &lt;command&gt; [args]
</code></pre>
<h3 id="version">Version</h3>
<p>7.4.0</p>
<p>7.4.2</p>
<h3 id="description">Description</h3>
<p>npm is the package manager for the Node JavaScript platform. It puts
modules in place so that node can find them, and manages dependency
deps/npm/docs/output/configuring-npm/install.html
Vendored
+37 -14
View File
@@ -145,20 +145,33 @@ npm command-line interface
</section>
<div id="_content"><h3 id="description">Description</h3>
<p>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. <strong>We strongly recommend using a Node version manager to install Node.js and npm.</strong> 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.</p>
<p>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. <strong>We strongly recommend using a Node
version manager to install Node.js and npm.</strong> 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.</p>
<h3 id="overview">Overview</h3>
<ul>
<li><a href="#checking-your-version-of-npm-and-node-js">Checking your version of npm and Node.js</a></li>
<li><a href="#using-a-node-version-manager-to-install-node-js-and-npm">Using a Node version manager to install Node.js and npm</a></li>
<li><a href="#using-a-node-installer-to-install-node-js-and-npm">Using a Node installer to install Node.js and npm</a></li>
<li><a href="#checking-your-version-of-npm-and-node-js">Checking your version of npm and
Node.js</a></li>
<li><a href="#using-a-node-version-manager-to-install-node-js-and-npm">Using a Node version manager to install Node.js and
npm</a></li>
<li><a href="#using-a-node-installer-to-install-node-js-and-npm">Using a Node installer to install Node.js and
npm</a></li>
</ul>
<h3 id="checking-your-version-of-npm-and-nodejs">Checking your version of npm and Node.js</h3>
<p>To see if you already have Node.js and npm installed and check the installed version, run the following commands:</p>
<p>To see if you already have Node.js and npm installed and check the
installed version, run the following commands:</p>
<pre><code>node -v
npm -v
</code></pre>
<h3 id="using-a-node-version-manager-to-install-nodejs-and-npm">Using a Node version manager to install Node.js and npm</h3>
<p>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.</p>
<p>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.</p>
<h4 id="osx-or-linux-node-version-managers">OSX or Linux Node version managers</h4>
<ul>
<li><a href="https://github.com/creationix/nvm">nvm</a></li>
@@ -170,22 +183,32 @@ npm -v
<li><a href="https://github.com/coreybutler/nvm-windows">nvm-windows</a></li>
</ul>
<h3 id="using-a-node-installer-to-install-nodejs-and-npm">Using a Node installer to install Node.js and npm</h3>
<p>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.</p>
<p>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.</p>
<ul>
<li><a href="https://nodejs.org/en/download/">Node.js installer</a></li>
<li><a href="https://github.com/nodesource/distributions">NodeSource installer</a>. If you use Linux, we recommend that you use a NodeSource installer.</li>
<li><a href="https://github.com/nodesource/distributions">NodeSource installer</a>. If
you use Linux, we recommend that you use a NodeSource installer.</li>
</ul>
<h4 id="os-x-or-windows-node-installers">OS X or Windows Node installers</h4>
<p>If you’re using OS X or Windows, use one of the installers from the <a href="https://nodejs.org/en/download/">Node.js download page</a>. Be sure to install the version labeled <strong>LTS</strong>. Other versions have not yet been tested with npm.</p>
<p>If you’re using OS X or Windows, use one of the installers from the
<a href="https://nodejs.org/en/download/">Node.js download page</a>. Be sure to
install the version labeled <strong>LTS</strong>. Other versions have not yet been
tested with npm.</p>
<h4 id="linux-or-other-operating-systems-node-installers">Linux or other operating systems Node installers</h4>
<p>If you’re using Linux or another operating system, use one of the following installers:</p>
<p>If you’re using Linux or another operating system, use one of the following
installers:</p>
<ul>
<li><a href="https://github.com/nodesource/distributions">NodeSource installer</a> (recommended)</li>
<li>One of the installers on the <a href="https://nodejs.org/en/download/">Node.js download page</a></li>
<li><a href="https://github.com/nodesource/distributions">NodeSource installer</a>
(recommended)</li>
<li>One of the installers on the <a href="https://nodejs.org/en/download/">Node.js download
page</a></li>
</ul>
<p>Or see <a href="https://nodejs.org/en/download/package-manager/">this page</a> to install npm for Linux in the way many Linux developers prefer.</p>
<p>Or see <a href="https://nodejs.org/en/download/package-manager/">this page</a> to
install npm for Linux in the way many Linux developers prefer.</p>
<h4 id="less-common-operating-systems">Less-common operating systems</h4>
<p>For more information on installing Node.js on a variety of operating systems, see <a href="https://nodejs.org/en/download/package-manager/">this page</a>.</p>
<p>For more information on installing Node.js on a variety of operating
systems, see <a href="https://nodejs.org/en/download/package-manager/">this page</a>.</p>
</div>
<footer id="edit">
deps/npm/docs/output/configuring-npm/shrinkwrap-json.html → deps/npm/docs/output/configuring-npm/npm-shrinkwrap-json.html
Vendored
+12 -9
View File
@@ -1,5 +1,5 @@
<html><head>
<title>shrinkwrap.json</title>
<title>npm-shrinkwrap.json</title>
<style>
body {
background-color: #ffffff;
@@ -135,7 +135,7 @@ npm command-line interface
<section id="content">
<header class="title">
<h1 id="shrinkwrapjson">shrinkwrap.json</h1>
<h1 id="npm-shrinkwrapjson">npm-shrinkwrap.json</h1>
<span class="description">A publishable lockfile</span>
</header>
@@ -151,12 +151,15 @@ npm command-line interface
<p>The recommended use-case for <code>npm-shrinkwrap.json</code> is applications deployed
through the publishing process on the registry: for example, daemons and
command-line tools intended as global installs or <code>devDependencies</code>. It’s
strongly discouraged for library authors to publish this file, since that would
prevent end users from having control over transitive dependency updates.</p>
<p>Additionally, if both <code>package-lock.json</code> and <code>npm-shrinkwrap.json</code> are present
in a package root, <code>package-lock.json</code> will be ignored in favor of this file.</p>
<p>For full details and description of the <code>npm-shrinkwrap.json</code> file format, refer
to the manual page for <a href="../configuring-npm/package-lock-json.html">package-lock.json</a>.</p>
strongly discouraged for library authors to publish this file, since that
would prevent end users from having control over transitive dependency
updates.</p>
<p>If both <code>package-lock.json</code> and <code>npm-shrinkwrap.json</code> are present in a
package root, <code>npm-shrinkwrap.json</code> will be preferred over the
<code>package-lock.json</code> file.</p>
<p>For full details and description of the <code>npm-shrinkwrap.json</code> file format,
refer to the manual page for
<a href="../configuring-npm/package-lock-json.html">package-lock.json</a>.</p>
<h3 id="see-also">See also</h3>
<ul>
<li><a href="../commands/npm-shrinkwrap.html">npm shrinkwrap</a></li>
@@ -167,7 +170,7 @@ to the manual page for <a href="../configuring-npm/package-lock-json.html">packa
</div>
<footer id="edit">
<a href="https://github.com/npm/cli/edit/latest/docs/content/configuring-npm/shrinkwrap-json.md">
<a href="https://github.com/npm/cli/edit/latest/docs/content/configuring-npm/npm-shrinkwrap-json.md">
<svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;">
<path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path>
</svg>
deps/npm/docs/output/configuring-npm/npmrc.html
Vendored
+27 -26
View File
@@ -145,11 +145,12 @@ npm command-line interface
</section>
<div id="_content"><h3 id="description">Description</h3>
<p>npm gets its config settings from the command line, environment
variables, and <code>npmrc</code> files.</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>For a list of available configuration options, see <a href="../using-npm/config.html">config</a>.</p>
<p>npm gets its config settings from the command line, environment variables,
and <code>npmrc</code> files.</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>For a list of available configuration options, see
<a href="../using-npm/config.html">config</a>.</p>
<h3 id="files">Files</h3>
<p>The four relevant files are:</p>
<ul>
@@ -158,21 +159,22 @@ of the user and global npmrc files.</p>
<li>global config file ($PREFIX/etc/npmrc)</li>
<li>npm builtin config file (/path/to/npm/npmrc)</li>
</ul>
<p>All npm config files are an ini-formatted list of <code>key = value</code>
parameters. Environment variables can be replaced using
<code>${VARIABLE_NAME}</code>. For example:</p>
<p>All npm config files are an ini-formatted list of <code>key = value</code> parameters.
Environment variables can be replaced using <code>${VARIABLE_NAME}</code>. For
example:</p>
<pre lang="bash"><code>prefix = ${HOME}/.npm-packages
</code></pre>
<p>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.</p>
<p>Array values are specified by adding “[]” after the key name. For
example:</p>
<p>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.</p>
<p>Array values are specified by adding “[]” after the key name. For example:</p>
<pre lang="bash"><code>key[] = "first value"
key[] = "second value"
</code></pre>
<h4 id="comments">Comments</h4>
<p>Lines in <code>.npmrc</code> files are interpreted as comments when they begin with a <code>;</code> or <code>#</code> character. <code>.npmrc</code> files are parsed by <a href="https://github.com/npm/ini">npm/ini</a>, which specifies this comment syntax.</p>
<p>Lines in <code>.npmrc</code> files are interpreted as comments when they begin with a
<code>;</code> or <code>#</code> character. <code>.npmrc</code> files are parsed by
<a href="https://github.com/npm/ini">npm/ini</a>, which specifies this comment syntax.</p>
<p>For example:</p>
<pre lang="bash"><code># last modified: 01 Jan 2016
; Set a new registry for a scoped package
@@ -182,26 +184,25 @@ key[] = "second value"
<p>When working locally in a project, a <code>.npmrc</code> file in the root of the
project (ie, a sibling of <code>node_modules</code> and <code>package.json</code>) will set
config values specific to this project.</p>
<p>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.</p>
<p>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.</p>
<p>Additionally, this file is not read in global mode, such as when running
<code>npm install -g</code>.</p>
<h4 id="per-user-config-file">Per-user config file</h4>
<p><code>$HOME/.npmrc</code> (or the <code>userconfig</code> param, if set in the environment
or on the command line)</p>
<p><code>$HOME/.npmrc</code> (or the <code>userconfig</code> param, if set in the environment or on
the command line)</p>
<h4 id="global-config-file">Global config file</h4>
<p><code>$PREFIX/etc/npmrc</code> (or the <code>globalconfig</code> param, if set above):
This file is an ini-file formatted list of <code>key = value</code> parameters.
Environment variables can be replaced as above.</p>
<p><code>$PREFIX/etc/npmrc</code> (or the <code>globalconfig</code> param, if set above): This file
is an ini-file formatted list of <code>key = value</code> parameters. Environment
variables can be replaced as above.</p>
<h4 id="built-in-config-file">Built-in config file</h4>
<p><code>path/to/npm/itself/npmrc</code></p>
<p>This is an unchangeable “builtin” configuration file that npm keeps
consistent across updates. Set fields in here using the <code>./configure</code>
script that comes with npm. This is primarily for distribution
maintainers to override default configs in a standard and consistent
manner.</p>
script that comes with npm. This is primarily for distribution maintainers
to override default configs in a standard and consistent manner.</p>
<h3 id="see-also">See also</h3>
<ul>
<li><a href="../configuring-npm/folders.html">npm folders</a></li>
deps/npm/docs/output/configuring-npm/package-json.html
Vendored
+396 -318
View File
@@ -141,59 +141,65 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#name">name</a></li><li><a href="#version">version</a></li><li><a href="#description2">description</a></li><li><a href="#keywords">keywords</a></li><li><a href="#homepage">homepage</a></li><li><a href="#bugs">bugs</a></li><li><a href="#license">license</a></li><li><a href="#people-fields-author-contributors">people fields: author, contributors</a></li><li><a href="#funding">funding</a></li><li><a href="#files">files</a></li><li><a href="#main">main</a></li><li><a href="#browser">browser</a></li><li><a href="#bin">bin</a></li><li><a href="#man">man</a></li><li><a href="#directories">directories</a></li><ul><li><a href="#directorieslib">directories.lib</a></li><li><a href="#directoriesbin">directories.bin</a></li><li><a href="#directoriesman">directories.man</a></li><li><a href="#directoriesdoc">directories.doc</a></li><li><a href="#directoriesexample">directories.example</a></li><li><a href="#directoriestest">directories.test</a></li></ul><li><a href="#repository">repository</a></li><li><a href="#scripts">scripts</a></li><li><a href="#config">config</a></li><li><a href="#dependencies">dependencies</a></li><ul><li><a href="#urls-as-dependencies">URLs as Dependencies</a></li><li><a href="#git-urls-as-dependencies">Git URLs as Dependencies</a></li><li><a href="#github-urls">GitHub URLs</a></li><li><a href="#local-paths">Local Paths</a></li></ul><li><a href="#devdependencies">devDependencies</a></li><li><a href="#peerdependencies">peerDependencies</a></li><li><a href="#peerdependenciesmeta">peerDependenciesMeta</a></li><li><a href="#bundleddependencies">bundledDependencies</a></li><li><a href="#optionaldependencies">optionalDependencies</a></li><li><a href="#engines">engines</a></li><li><a href="#enginestrict">engineStrict</a></li><li><a href="#os">os</a></li><li><a href="#cpu">cpu</a></li><li><a href="#preferglobal">preferGlobal</a></li><li><a href="#private">private</a></li><li><a href="#publishconfig">publishConfig</a></li><li><a href="#workspaces">workspaces</a></li><li><a href="#default-values">DEFAULT VALUES</a></li><li><a href="#see-also">SEE ALSO</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#name">name</a></li><li><a href="#version">version</a></li><li><a href="#description2">description</a></li><li><a href="#keywords">keywords</a></li><li><a href="#homepage">homepage</a></li><li><a href="#bugs">bugs</a></li><li><a href="#license">license</a></li><li><a href="#people-fields-author-contributors">people fields: author, contributors</a></li><li><a href="#funding">funding</a></li><li><a href="#files">files</a></li><li><a href="#main">main</a></li><li><a href="#browser">browser</a></li><li><a href="#bin">bin</a></li><li><a href="#man">man</a></li><li><a href="#directories">directories</a></li><ul><li><a href="#directoriesbin">directories.bin</a></li><li><a href="#directoriesman">directories.man</a></li></ul><li><a href="#repository">repository</a></li><li><a href="#scripts">scripts</a></li><li><a href="#config">config</a></li><li><a href="#dependencies">dependencies</a></li><ul><li><a href="#urls-as-dependencies">URLs as Dependencies</a></li><li><a href="#git-urls-as-dependencies">Git URLs as Dependencies</a></li><li><a href="#github-urls">GitHub URLs</a></li><li><a href="#local-paths">Local Paths</a></li></ul><li><a href="#devdependencies">devDependencies</a></li><li><a href="#peerdependencies">peerDependencies</a></li><li><a href="#peerdependenciesmeta">peerDependenciesMeta</a></li><li><a href="#bundleddependencies">bundledDependencies</a></li><li><a href="#optionaldependencies">optionalDependencies</a></li><li><a href="#engines">engines</a></li><li><a href="#os">os</a></li><li><a href="#cpu">cpu</a></li><li><a href="#private">private</a></li><li><a href="#publishconfig">publishConfig</a></li><li><a href="#workspaces">workspaces</a></li><li><a href="#default-values">DEFAULT VALUES</a></li><li><a href="#see-also">SEE ALSO</a></li></ul></div>
</section>
<div id="_content"><h3 id="description">Description</h3>
<p>This document is all you need to know about what’s required in your package.json
file. It must be actual JSON, not just a JavaScript object literal.</p>
<p>This document is all you need to know about what’s required in your
package.json file. It must be actual JSON, not just a JavaScript object
literal.</p>
<p>A lot of the behavior described in this document is affected by the config
settings described in <a href="../using-npm/config.html"><code>config</code></a>.</p>
<h3 id="name">name</h3>
<p>If you plan to publish your package, the <em>most</em> important things in your
package.json are the name and version fields as they will be required. The name
and version together form an identifier that is assumed to be completely unique.
Changes to the package should come along with changes to the version. If you don’t
plan to publish your package, the name and version fields are optional.</p>
package.json are the name and version fields as they will be required. The
name and version together form an identifier that is assumed to be
completely unique. Changes to the package should come along with changes
to the version. If you don’t plan to publish your package, the name and
version fields are optional.</p>
<p>The name is what your thing is called.</p>
<p>Some rules:</p>
<ul>
<li>The name must be less than or equal to 214 characters. This includes the scope for
scoped packages.</li>
<li>The names of scoped packages can begin with a dot or an underscore. This is not permitted without a scope.</li>
<li>The name must be less than or equal to 214 characters. This includes the
scope for scoped packages.</li>
<li>The names of scoped packages can begin with a dot or an underscore. This
is not permitted without a scope.</li>
<li>New packages must not have uppercase letters in the name.</li>
<li>The name ends up being part of a URL, an argument on the command line, and a
folder name. Therefore, the name can’t contain any non-URL-safe characters.</li>
<li>The name ends up being part of a URL, an argument on the command line,
and a folder name. Therefore, the name can’t contain any non-URL-safe
characters.</li>
</ul>
<p>Some tips:</p>
<ul>
<li>Don’t use the same name as a core Node module.</li>
<li>Don’t put “js” or “node” in the name. It’s assumed that it’s js, since you’re
writing a package.json file, and you can specify the engine using the “engines”
field. (See below.)</li>
<li>The name will probably be passed as an argument to require(), so it should
be something short, but also reasonably descriptive.</li>
<li>You may want to check the npm registry to see if there’s something by that name
already, before you get too attached to it. <a href="https://www.npmjs.com/">https://www.npmjs.com/</a></li>
<li>Don’t put “js” or “node” in the name. It’s assumed that it’s js, since
you’re writing a package.json file, and you can specify the engine using
the “engines” field. (See below.)</li>
<li>The name will probably be passed as an argument to require(), so it
should be something short, but also reasonably descriptive.</li>
<li>You may want to check the npm registry to see if there’s something by
that name already, before you get too attached to it.
<a href="https://www.npmjs.com/">https://www.npmjs.com/</a></li>
</ul>
<p>A name can be optionally prefixed by a scope, e.g. <code>@myorg/mypackage</code>. See
<a href="../using-npm/scope.html"><code>scope</code></a> for more detail.</p>
<h3 id="version">version</h3>
<p>If you plan to publish your package, the <em>most</em> important things in your
package.json are the name and version fields as they will be required. The name
and version together form an identifier that is assumed to be completely unique.
Changes to the package should come along with changes to the version. If you don’t
plan to publish your package, the name and version fields are optional.</p>
package.json are the name and version fields as they will be required. The
name and version together form an identifier that is assumed to be
completely unique. Changes to the package should come along with changes
to the version. If you don’t plan to publish your package, the name and
version fields are optional.</p>
<p>Version must be parseable by
<a href="https://github.com/npm/node-semver">node-semver</a>, which is bundled
with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
<a href="https://github.com/npm/node-semver">node-semver</a>, which is bundled with
npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
<p>More on version numbers and ranges at <a href="../using-npm/semver.html">semver</a>.</p>
<h3 id="description2">description</h3>
<p>Put a description in it. It’s a string. This helps people discover your
package, as it’s listed in <code>npm search</code>.</p>
<h3 id="keywords">keywords</h3>
<p>Put keywords in it. It’s an array of strings. This helps people
discover your package as it’s listed in <code>npm search</code>.</p>
<p>Put keywords in it. It’s an array of strings. This helps people discover
your package as it’s listed in <code>npm search</code>.</p>
<h3 id="homepage">homepage</h3>
<p>The url to the project homepage.</p>
<p>Example:</p>
@@ -201,127 +207,152 @@ discover your package as it’s listed in <code>npm search</code>.</p>
</code></pre>
<h3 id="bugs">bugs</h3>
<p>The url to your project’s issue tracker and / or the email address to which
issues should be reported. These are helpful for people who encounter issues
with your package.</p>
issues should be reported. These are helpful for people who encounter
issues with your package.</p>
<p>It should look like this:</p>
<pre lang="json"><code>{ "url" : "https://github.com/owner/project/issues"
, "email" : "project@hostname.com"
<pre lang="json"><code>{
"url" : "https://github.com/owner/project/issues",
"email" : "project@hostname.com"
}
</code></pre>
<p>You can specify either one or both values. If you want to provide only a url,
you can specify the value for “bugs” as a simple string instead of an object.</p>
<p>You can specify either one or both values. If you want to provide only a
url, you can specify the value for “bugs” as a simple string instead of an
object.</p>
<p>If a url is provided, it will be used by the <code>npm bugs</code> command.</p>
<h3 id="license">license</h3>
<p>You should specify a license for your package so that people know how they are
permitted to use it, and any restrictions you’re placing on it.</p>
<p>If you’re using a common license such as BSD-2-Clause or MIT, add a
current SPDX license identifier for the license you’re using, like this:</p>
<pre lang="json"><code>{ "license" : "BSD-3-Clause" }
<p>You should specify a license for your package so that people know how they
are permitted to use it, and any restrictions you’re placing on it.</p>
<p>If you’re using a common license such as BSD-2-Clause or MIT, add a current
SPDX license identifier for the license you’re using, like this:</p>
<pre lang="json"><code>{
"license" : "BSD-3-Clause"
}
</code></pre>
<p>You can check <a href="https://spdx.org/licenses/">the full list of SPDX license IDs</a>.
Ideally you should pick one that is
<p>You can check <a href="https://spdx.org/licenses/">the full list of SPDX license
IDs</a>. Ideally you should pick one that is
<a href="https://opensource.org/licenses/alphabetical">OSI</a> approved.</p>
<p>If your package is licensed under multiple common licenses, use an <a href="https://www.npmjs.com/package/spdx">SPDX license
expression syntax version 2.0 string</a>, like this:</p>
<pre lang="json"><code>{ "license" : "(ISC OR GPL-3.0)" }
<p>If your package is licensed under multiple common licenses, use an <a href="https://www.npmjs.com/package/spdx">SPDX
license expression syntax version 2.0
string</a>, like this:</p>
<pre lang="json"><code>{
"license" : "(ISC OR GPL-3.0)"
}
</code></pre>
<p>If you are using a license that hasn’t been assigned an SPDX identifier, or if
you are using a custom license, use a string value like this one:</p>
<pre lang="json"><code>{ "license" : "SEE LICENSE IN &lt;filename&gt;" }
<pre lang="json"><code>{
"license" : "SEE LICENSE IN &lt;filename&gt;"
}
</code></pre>
<p>Then include a file named <code>&lt;filename&gt;</code> at the top level of the package.</p>
<p>Some old packages used license objects or a “licenses” property containing an
array of license objects:</p>
<p>Some old packages used license objects or a “licenses” property containing
an array of license objects:</p>
<pre lang="json"><code>// Not valid metadata
{ "license" :
{ "type" : "ISC"
, "url" : "https://opensource.org/licenses/ISC"
{
"license" : {
"type" : "ISC",
"url" : "https://opensource.org/licenses/ISC"
}
}
// Not valid metadata
{ "licenses" :
[
{ "type": "MIT"
, "url": "https://www.opensource.org/licenses/mit-license.php"
}
, { "type": "Apache-2.0"
, "url": "https://opensource.org/licenses/apache2.0.php"
{
"licenses" : [
{
"type": "MIT",
"url": "https://www.opensource.org/licenses/mit-license.php"
},
{
"type": "Apache-2.0",
"url": "https://opensource.org/licenses/apache2.0.php"
}
]
}
</code></pre>
<p>Those styles are now deprecated. Instead, use SPDX expressions, like this:</p>
<pre lang="json"><code>{ "license": "ISC" }
{ "license": "(MIT OR Apache-2.0)" }
<pre lang="json"><code>{
"license": "ISC"
}
</code></pre>
<pre lang="json"><code>{
"license": "(MIT OR Apache-2.0)"
}
</code></pre>
<p>Finally, if you do not wish to grant others the right to use a private or
unpublished package under any terms:</p>
<pre lang="json"><code>{ "license": "UNLICENSED" }
<pre lang="json"><code>{
"license": "UNLICENSED"
}
</code></pre>
<p>Consider also setting <code>"private": true</code> to prevent accidental publication.</p>
<h3 id="people-fields-author-contributors">people fields: author, contributors</h3>
<p>The “author” is one person. “contributors” is an array of people. A “person”
is an object with a “name” field and optionally “url” and “email”, like this:</p>
<pre lang="json"><code>{ "name" : "Barney Rubble"
, "email" : "b@rubble.com"
, "url" : "http://barnyrubble.tumblr.com/"
<p>The “author” is one person. “contributors” is an array of people. A
“person” is an object with a “name” field and optionally “url” and “email”,
like this:</p>
<pre lang="json"><code>{
"name" : "Barney Rubble",
"email" : "b@rubble.com",
"url" : "http://barnyrubble.tumblr.com/"
}
</code></pre>
<p>Or you can shorten that all into a single string, and npm will parse it for you:</p>
<pre lang="json"><code>"Barney Rubble &lt;b@rubble.com&gt; (http://barnyrubble.tumblr.com/)"
<p>Or you can shorten that all into a single string, and npm will parse it for
you:</p>
<pre lang="json"><code>{
"author": "Barney Rubble &lt;b@rubble.com&gt; (http://barnyrubble.tumblr.com/)"
}
</code></pre>
<p>Both email and url are optional either way.</p>
<p>npm also sets a top-level “maintainers” field with your npm user info.</p>
<h3 id="funding">funding</h3>
<p>You can specify an object containing an URL that provides up-to-date
information about ways to help fund development of your package, or
a string URL, or an array of these:</p>
<pre><code>"funding": {
"type" : "individual",
"url" : "http://example.com/donate"
}
"funding": {
"type" : "patreon",
"url" : "https://www.patreon.com/my-account"
}
"funding": "http://example.com/donate"
"funding": [
{
information about ways to help fund development of your package, or a
string URL, or an array of these:</p>
<pre lang="json"><code>{
"funding": {
"type" : "individual",
"url" : "http://example.com/donate"
},
"http://example.com/donateAlso",
{
"funding": {
"type" : "patreon",
"url" : "https://www.patreon.com/my-account"
}
]
},
"funding": "http://example.com/donate",
"funding": [
{
"type" : "individual",
"url" : "http://example.com/donate"
},
"http://example.com/donateAlso",
{
"type" : "patreon",
"url" : "https://www.patreon.com/my-account"
}
]
}
</code></pre>
<p>Users can use the <code>npm fund</code> subcommand to list the <code>funding</code> URLs of all
dependencies of their project, direct and indirect. A shortcut to visit each
funding url is also available when providing the project name such as:
<code>npm fund &lt;projectname&gt;</code> (when there are multiple URLs, the first one will be
visited)</p>
dependencies of their project, direct and indirect. A shortcut to visit
each funding url is also available when providing the project name such as:
<code>npm fund &lt;projectname&gt;</code> (when there are multiple URLs, the first one will
be visited)</p>
<h3 id="files">files</h3>
<p>The optional <code>files</code> field is an array of file patterns that describes
the entries to be included when your package is installed as a
dependency. File patterns follow a similar syntax to <code>.gitignore</code>, but
reversed: including a file, directory, or glob pattern (<code>*</code>, <code>**/*</code>, and such)
will make it so that file is included in the tarball when it’s packed. Omitting
the field will make it default to <code>["*"]</code>, which means it will include all files.</p>
<p>Some special files and directories are also included or excluded regardless of
whether they exist in the <code>files</code> array (see below).</p>
<p>You can also provide a <code>.npmignore</code> file in the root of your package or
in subdirectories, which will keep files from being included. At the
root of your package it will not override the “files” field, but in
subdirectories it will. The <code>.npmignore</code> file works just like a
<code>.gitignore</code>. If there is a <code>.gitignore</code> file, and <code>.npmignore</code> is
missing, <code>.gitignore</code>’s contents will be used instead.</p>
<p>The optional <code>files</code> field is an array of file patterns that describes the
entries to be included when your package is installed as a dependency. File
patterns follow a similar syntax to <code>.gitignore</code>, but reversed: including a
file, directory, or glob pattern (<code>*</code>, <code>**/*</code>, and such) will make it so
that file is included in the tarball when it’s packed. Omitting the field
will make it default to <code>["*"]</code>, which means it will include all files.</p>
<p>Some special files and directories are also included or excluded regardless
of whether they exist in the <code>files</code> array (see below).</p>
<p>You can also provide a <code>.npmignore</code> file in the root of your package or in
subdirectories, which will keep files from being included. At the root of
your package it will not override the “files” field, but in subdirectories
it will. The <code>.npmignore</code> file works just like a <code>.gitignore</code>. If there is
a <code>.gitignore</code> file, and <code>.npmignore</code> is missing, <code>.gitignore</code>’s contents
will be used instead.</p>
<p>Files included with the “package.json#files” field <em>cannot</em> be excluded
through <code>.npmignore</code> or <code>.gitignore</code>.</p>
<p>Certain files are always included, regardless of settings:</p>
@@ -350,176 +381,201 @@ through <code>.npmignore</code> or <code>.gitignore</code>.</p>
<li><code>node_modules</code></li>
<li><code>config.gypi</code></li>
<li><code>*.orig</code></li>
<li><code>package-lock.json</code> (use shrinkwrap instead)</li>
<li><code>package-lock.json</code> (use
<a href="../configuring-npm/npm-shrinkwrap-json.html"><code>npm-shrinkwrap.json</code></a> if you wish
it to be published)</li>
</ul>
<h3 id="main">main</h3>
<p>The main field is a module ID that is the primary entry point to your program.
That is, if your package is named <code>foo</code>, and a user installs it, and then does
<code>require("foo")</code>, then your main module’s exports object will be returned.</p>
<p>This should be a module ID relative to the root of your package folder.</p>
<p>For most modules, it makes the most sense to have a main script and often not
much else.</p>
<p>The main field is a module ID that is the primary entry point to your
program. That is, if your package is named <code>foo</code>, and a user installs it,
and then does <code>require("foo")</code>, then your main module’s exports object will
be returned.</p>
<p>This should be a module relative to the root of your package folder.</p>
<p>For most modules, it makes the most sense to have a main script and often
not much else.</p>
<h3 id="browser">browser</h3>
<p>If your module is meant to be used client-side the browser field should be
used instead of the main field. This is helpful to hint users that it might
rely on primitives that aren’t available in Node.js modules. (e.g. <code>window</code>)</p>
rely on primitives that aren’t available in Node.js modules. (e.g.
<code>window</code>)</p>
<h3 id="bin">bin</h3>
<p>A lot of packages have one or more executable files that they’d like to
install into the PATH. npm makes this pretty easy (in fact, it uses this
feature to install the “npm” executable.)</p>
<p>To use this, supply a <code>bin</code> field in your package.json which is a map of
command name to local file name. On install, npm will symlink that file into
<code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local
command name to local file name. On install, npm will symlink that file
into <code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local
installs.</p>
<p>For example, myapp could have this:</p>
<pre lang="json"><code>{ "bin" : { "myapp" : "./cli.js" } }
<pre lang="json"><code>{
"bin": {
"myapp": "./cli.js"
}
}
</code></pre>
<p>So, when you install myapp, it’ll create a symlink from the <code>cli.js</code> script to
<code>/usr/local/bin/myapp</code>.</p>
<p>If you have a single executable, and its name should be the name
of the package, then you can just supply it as a string. For example:</p>
<pre lang="json"><code>{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }
<p>So, when you install myapp, it’ll create a symlink from the <code>cli.js</code> script
to <code>/usr/local/bin/myapp</code>.</p>
<p>If you have a single executable, and its name should be the name of the
package, then you can just supply it as a string. For example:</p>
<pre lang="json"><code>{
"name": "my-program",
"version": "1.2.5",
"bin": "./path/to/program"
}
</code></pre>
<p>would be the same as this:</p>
<pre lang="json"><code>{ "name": "my-program"
, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }
<pre lang="json"><code>{
"name": "my-program",
"version": "1.2.5",
"bin": {
"my-program": "./path/to/program"
}
}
</code></pre>
<p>Please make sure that your file(s) referenced in <code>bin</code> starts with
<code>#!/usr/bin/env node</code>, otherwise the scripts are started without the node
executable!</p>
<h3 id="man">man</h3>
<p>Specify either a single file or an array of filenames to put in place for the
<code>man</code> program to find.</p>
<p>Specify either a single file or an array of filenames to put in place for
the <code>man</code> program to find.</p>
<p>If only a single file is provided, then it’s installed such that it is the
result from <code>man &lt;pkgname&gt;</code>, regardless of its actual filename. For example:</p>
<pre lang="json"><code>{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : "./man/doc.1"
result from <code>man &lt;pkgname&gt;</code>, regardless of its actual filename. For
example:</p>
<pre lang="json"><code>{
"name": "foo",
"version": "1.2.3",
"description": "A packaged foo fooer for fooing foos",
"main": "foo.js",
"man": "./man/doc.1"
}
</code></pre>
<p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p>
<p>If the filename doesn’t start with the package name, then it’s prefixed.
So, this:</p>
<pre lang="json"><code>{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/bar.1" ]
<pre lang="json"><code>{
"name": "foo",
"version": "1.2.3",
"description": "A packaged foo fooer for fooing foos",
"main": "foo.js",
"man": [
"./man/foo.1",
"./man/bar.1"
]
}
</code></pre>
<p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p>
<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are
compressed. The number dictates which man section the file is installed into.</p>
<pre lang="json"><code>{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/foo.2" ]
compressed. The number dictates which man section the file is installed
into.</p>
<pre lang="json"><code>{
"name": "foo",
"version": "1.2.3",
"description": "A packaged foo fooer for fooing foos",
"main": "foo.js",
"man": [
"./man/foo.1",
"./man/foo.2"
]
}
</code></pre>
<p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p>
<h3 id="directories">directories</h3>
<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a
few ways that you can indicate the structure of your package using a <code>directories</code>
object. If you look at <a href="https://registry.npmjs.org/npm/latest">npm’s package.json</a>,
you’ll see that it has directories for doc, lib, and man.</p>
<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec
details a few ways that you can indicate the structure of your package
using a <code>directories</code> object. If you look at <a href="https://registry.npmjs.org/npm/latest">npm’s
package.json</a>, you’ll see that it
has directories for doc, lib, and man.</p>
<p>In the future, this information may be used in other creative ways.</p>
<h4 id="directorieslib">directories.lib</h4>
<p>Tell people where the bulk of your library is. Nothing special is done
with the lib folder in any way, but it’s useful meta info.</p>
<h4 id="directoriesbin">directories.bin</h4>
<p>If you specify a <code>bin</code> directory in <code>directories.bin</code>, all the files in
that folder will be added.</p>
<p>Because of the way the <code>bin</code> directive works, specifying both a
<code>bin</code> path and setting <code>directories.bin</code> is an error. If you want to
specify individual files, use <code>bin</code>, and for all the files in an
existing <code>bin</code> directory, use <code>directories.bin</code>.</p>
<p>Because of the way the <code>bin</code> directive works, specifying both a <code>bin</code> path
and setting <code>directories.bin</code> is an error. If you want to specify
individual files, use <code>bin</code>, and for all the files in an existing <code>bin</code>
directory, use <code>directories.bin</code>.</p>
<h4 id="directoriesman">directories.man</h4>
<p>A folder that is full of man pages. Sugar to generate a “man” array by
walking the folder.</p>
<h4 id="directoriesdoc">directories.doc</h4>
<p>Put markdown files in here. Eventually, these will be displayed nicely,
maybe, someday.</p>
<h4 id="directoriesexample">directories.example</h4>
<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p>
<h4 id="directoriestest">directories.test</h4>
<p>Put your tests in here. It is currently not exposed, but it might be in the
future.</p>
<h3 id="repository">repository</h3>
<p>Specify the place where your code lives. This is helpful for people who
want to contribute. If the git repo is on GitHub, then the <code>npm docs</code>
command will be able to find you.</p>
<p>Do it like this:</p>
<pre lang="json"><code>"repository": {
"type" : "git",
"url" : "https://github.com/npm/cli.git"
}
"repository": {
"type" : "svn",
"url" : "https://v8.googlecode.com/svn/trunk/"
<pre lang="json"><code>{
"repository": {
"type": "git",
"url": "https://github.com/npm/cli.git"
}
}
</code></pre>
<p>The URL should be a publicly available (perhaps read-only) url that can be handed
directly to a VCS program without any modification. It should not be a url to an
html project page that you put in your browser. It’s for computers.</p>
<p>For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
shortcut syntax you use for <code>npm install</code>:</p>
<pre lang="json"><code>"repository": "npm/npm"
<p>The URL should be a publicly available (perhaps read-only) url that can be
handed directly to a VCS program without any modification. It should not
be a url to an html project page that you put in your browser. It’s for
computers.</p>
<p>For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the
same shortcut syntax you use for <code>npm install</code>:</p>
<pre lang="json"><code>{
"repository": "npm/npm",
"repository": "github:user/repo"
"repository": "github:user/repo",
"repository": "gist:11081aaa281"
"repository": "gist:11081aaa281",
"repository": "bitbucket:user/repo"
"repository": "bitbucket:user/repo",
"repository": "gitlab:user/repo"
"repository": "gitlab:user/repo"
}
</code></pre>
<p>If the <code>package.json</code> for your package is not in the root directory (for example
if it is part of a monorepo), you can specify the directory in which it lives:</p>
<pre lang="json"><code>"repository": {
"type" : "git",
"url" : "https://github.com/facebook/react.git",
"directory": "packages/react-dom"
<p>If the <code>package.json</code> for your package is not in the root directory (for
example if it is part of a monorepo), you can specify the directory in
which it lives:</p>
<pre lang="json"><code>{
"repository": {
"type": "git",
"url": "https://github.com/facebook/react.git",
"directory": "packages/react-dom"
}
}
</code></pre>
<h3 id="scripts">scripts</h3>
<p>The “scripts” property is a dictionary containing script commands that are run
at various times in the lifecycle of your package. The key is the lifecycle
event, and the value is the command to run at that point.</p>
<p>See <a href="../using-npm/scripts.html"><code>scripts</code></a> to find out more about writing package scripts.</p>
<p>The “scripts” property is a dictionary containing script commands that are
run at various times in the lifecycle of your package. The key is the
lifecycle event, and the value is the command to run at that point.</p>
<p>See <a href="../using-npm/scripts.html"><code>scripts</code></a> to find out more about writing package
scripts.</p>
<h3 id="config">config</h3>
<p>A “config” object can be used to set configuration parameters used in package
scripts that persist across upgrades. For instance, if a package had the
following:</p>
<pre lang="json"><code>{ "name" : "foo"
, "config" : { "port" : "8080" } }
<p>A “config” object can be used to set configuration parameters used in
package scripts that persist across upgrades. For instance, if a package
had the following:</p>
<pre lang="json"><code>{
"name": "foo",
"config": {
"port": "8080"
}
}
</code></pre>
<p>and then had a “start” command that then referenced the
<code>npm_package_config_port</code> environment variable, then the user could
override that by doing <code>npm config set foo:port 8001</code>.</p>
<p>See <a href="../using-npm/config.html"><code>config</code></a> and <a href="../using-npm/scripts.html"><code>scripts</code></a> for more on package
configs.</p>
<p>See <a href="../using-npm/config.html"><code>config</code></a> and <a href="../using-npm/scripts.html"><code>scripts</code></a> for
more on package configs.</p>
<h3 id="dependencies">dependencies</h3>
<p>Dependencies are specified in a simple object that maps a package name to a
version range. The version range is a string which has one or more
space-separated descriptors. Dependencies can also be identified with a
tarball or git URL.</p>
<p><strong>Please do not put test harnesses or transpilers in your
<code>dependencies</code> object.</strong> See <code>devDependencies</code>, below.</p>
<p>See <a href="../using-npm/semver.html">semver</a> for more details about specifying version ranges.</p>
<p><strong>Please do not put test harnesses or transpilers or other “development”
time tools in your <code>dependencies</code> object.</strong> See <code>devDependencies</code>, below.</p>
<p>See <a href="../using-npm/semver.html">semver</a> for more details about specifying version
ranges.</p>
<ul>
<li><code>version</code> Must match <code>version</code> exactly</li>
<li><code>&gt;version</code> Must be greater than <code>version</code></li>
<li><code>&gt;=version</code> etc</li>
<li><code>&lt;version</code></li>
<li><code>&lt;=version</code></li>
<li><code>~version</code> “Approximately equivalent to version” See <a href="../using-npm/semver.html">semver</a></li>
<li><code>~version</code> “Approximately equivalent to version” See
<a href="../using-npm/semver.html">semver</a></li>
<li><code>^version</code> “Compatible with version” See <a href="../using-npm/semver.html">semver</a></li>
<li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</li>
<li><code>http://...</code> See ‘URLs as Dependencies’ below</li>
@@ -533,19 +589,20 @@ tarball or git URL.</p>
<li><code>path/path/path</code> See <a href="#local-paths">Local Paths</a> below</li>
</ul>
<p>For example, these are all valid:</p>
<pre lang="json"><code>{ "dependencies" :
{ "foo" : "1.0.0 - 2.9999.9999"
, "bar" : "&gt;=1.0.2 &lt;2.1.2"
, "baz" : "&gt;1.0.2 &lt;=2.3.4"
, "boo" : "2.0.1"
, "qux" : "&lt;1.0.0 || &gt;=2.3.1 &lt;2.4.5 || &gt;=2.5.2 &lt;3.0.0"
, "asd" : "http://asdf.com/asdf.tar.gz"
, "til" : "~1.2"
, "elf" : "~1.2.3"
, "two" : "2.x"
, "thr" : "3.3.x"
, "lat" : "latest"
, "dyl" : "file:../dyl"
<pre lang="json"><code>{
"dependencies": {
"foo": "1.0.0 - 2.9999.9999",
"bar": "&gt;=1.0.2 &lt;2.1.2",
"baz": "&gt;1.0.2 &lt;=2.3.4",
"boo": "2.0.1",
"qux": "&lt;1.0.0 || &gt;=2.3.1 &lt;2.4.5 || &gt;=2.5.2 &lt;3.0.0",
"asd": "http://asdf.com/asdf.tar.gz",
"til": "~1.2",
"elf": "~1.2.3",
"two": "2.x",
"thr": "3.3.x",
"lat": "latest",
"dyl": "file:../dyl"
}
}
</code></pre>
@@ -562,8 +619,8 @@ install time.</p>
<p>If <code>#&lt;commit-ish&gt;</code> is provided, it will be used to clone exactly that
commit. If the commit-ish has the format <code>#semver:&lt;semver&gt;</code>, <code>&lt;semver&gt;</code> 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 <code>#&lt;commit-ish&gt;</code> or <code>#semver:&lt;semver&gt;</code> is
or refs matching that range in the remote repository, much as it would for
a registry dependency. If neither <code>#&lt;commit-ish&gt;</code> or <code>#semver:&lt;semver&gt;</code> is
specified, then <code>master</code> is used.</p>
<p>Examples:</p>
<pre lang="bash"><code>git+ssh://git@github.com:npm/cli.git#v1.0.27
@@ -586,9 +643,8 @@ included. For example:</p>
}
</code></pre>
<h4 id="local-paths">Local Paths</h4>
<p>As of version 2.0.0 you can provide a path to a local directory that contains a
package. Local paths can be saved using <code>npm install -S</code> or
<code>npm install --save</code>, using any of these forms:</p>
<p>As of version 2.0.0 you can provide a path to a local directory that
contains a package. Local paths can be saved using <code>npm install -S</code> or <code>npm install --save</code>, using any of these forms:</p>
<pre lang="bash"><code>../foo/bar
~/foo/bar
./foo/bar
@@ -603,24 +659,24 @@ package. Local paths can be saved using <code>npm install -S</code> or
}
}
</code></pre>
<p>This feature is helpful for local offline development and creating
tests that require npm installing where you don’t want to hit an
external server, but should not be used when publishing packages
to the public registry.</p>
<p>This feature is helpful for local offline development and creating tests
that require npm installing where you don’t want to hit an external server,
but should not be used when publishing packages to the public registry.</p>
<h3 id="devdependencies">devDependencies</h3>
<p>If someone is planning on downloading and using your module in their
program, then they probably don’t want or need to download and build
the external test or documentation framework that you use.</p>
<p>In this case, it’s best to map these additional items in a <code>devDependencies</code>
object.</p>
<p>These things will be installed when doing <code>npm link</code> or <code>npm install</code>
from the root of a package, and can be managed like any other npm
configuration param. See <a href="../using-npm/config.html"><code>config</code></a> for more on the topic.</p>
program, then they probably don’t want or need to download and build the
external test or documentation framework that you use.</p>
<p>In this case, it’s best to map these additional items in a
<code>devDependencies</code> object.</p>
<p>These things will be installed when doing <code>npm link</code> or <code>npm install</code> from
the root of a package, and can be managed like any other npm configuration
param. See <a href="../using-npm/config.html"><code>config</code></a> for more on the topic.</p>
<p>For build steps that are not platform-specific, such as compiling
CoffeeScript or other languages to JavaScript, use the <code>prepare</code>
script to do this, and make the required package a devDependency.</p>
CoffeeScript or other languages to JavaScript, use the <code>prepare</code> script to
do this, and make the required package a devDependency.</p>
<p>For example:</p>
<pre lang="json"><code>{ "name": "ethopia-waza",
<pre lang="json"><code>{
"name": "ethopia-waza",
"description": "a delightfully fruity coffee varietal",
"version": "1.2.3",
"devDependencies": {
@@ -632,15 +688,16 @@ script to do this, and make the required package a devDependency.</p>
"main": "lib/waza.js"
}
</code></pre>
<p>The <code>prepare</code> script will be run before publishing, so that users
can consume the functionality without requiring them to compile it
themselves. In dev mode (ie, locally running <code>npm install</code>), it’ll
run this script as well, so that you can test it easily.</p>
<p>The <code>prepare</code> script will be run before publishing, so that users can
consume the functionality without requiring them to compile it themselves.
In dev mode (ie, locally running <code>npm install</code>), it’ll run this script as
well, so that you can test it easily.</p>
<h3 id="peerdependencies">peerDependencies</h3>
<p>In some cases, you want to express the compatibility of your package with a
host tool or library, while not necessarily doing a <code>require</code> of this host.
This is usually referred to as a <em>plugin</em>. Notably, your module may be exposing
a specific interface, expected and specified by the host documentation.</p>
This is usually referred to as a <em>plugin</em>. Notably, your module may be
exposing a specific interface, expected and specified by the host
documentation.</p>
<p>For example:</p>
<pre lang="json"><code>{
"name": "tea-latte",
@@ -650,27 +707,30 @@ a specific interface, expected and specified by the host documentation.</p>
}
}
</code></pre>
<p>This ensures your package <code>tea-latte</code> can be installed <em>along</em> with the second
major version of the host package <code>tea</code> only. <code>npm install tea-latte</code> could
possibly yield the following dependency graph:</p>
<p>This ensures your package <code>tea-latte</code> can be installed <em>along</em> with the
second major version of the host package <code>tea</code> only. <code>npm install tea-latte</code> could possibly yield the following dependency graph:</p>
<pre lang="bash"><code>├── tea-latte@1.3.5
└── tea@2.2.0
</code></pre>
<p><strong>NOTE: npm versions 1 and 2 will automatically install <code>peerDependencies</code> if
they are not explicitly depended upon higher in the dependency tree. In the
next major version of npm (npm@3), this will no longer be the case. You will
receive a warning that the peerDependency is not installed instead.</strong> The
behavior in npms 1 &amp; 2 was frequently confusing and could easily put you into
dependency hell, a situation that npm is designed to avoid as much as possible.</p>
<p>Trying to install another plugin with a conflicting requirement will cause an
error. For this reason, make sure your plugin requirement is as broad as
possible, and not to lock it down to specific patch versions.</p>
<p>Assuming the host complies with <a href="https://semver.org/">semver</a>, only changes in
the host package’s major version will break your plugin. Thus, if you’ve worked
with every 1.x version of the host package, use <code>"^1.0"</code> or <code>"1.x"</code> to express
this. If you depend on features introduced in 1.5.2, use <code>"&gt;= 1.5.2 &lt; 2"</code>.</p>
<p>In npm versions 3 through 6, <code>peerDependencies</code> were not automatically
installed, and would raise a warning if an invalid version of the peer
dependency was found in the tree. As of npm v7, peerDependencies <em>are</em>
installed by default.</p>
<p>Trying to install another plugin with a conflicting requirement may cause
an error if the tree cannot be resolved correctly. For this reason, make
sure your plugin requirement is as broad as possible, and not to lock it
down to specific patch versions.</p>
<p>Assuming the host complies with <a href="https://semver.org/">semver</a>, only changes
in the host package’s major version will break your plugin. Thus, if you’ve
worked with every 1.x version of the host package, use <code>"^1.0"</code> or <code>"1.x"</code>
to express this. If you depend on features introduced in 1.5.2, use
<code>"^1.5.2"</code>.</p>
<h3 id="peerdependenciesmeta">peerDependenciesMeta</h3>
<p>When a user installs your package, npm will emit warnings if packages specified in <code>peerDependencies</code> are not already installed. The <code>peerDependenciesMeta</code> field serves to provide npm more information on how your peer dependencies are to be used. Specifically, it allows peer dependencies to be marked as optional.</p>
<p>When a user installs your package, npm will emit warnings if packages
specified in <code>peerDependencies</code> are not already installed. The
<code>peerDependenciesMeta</code> field serves to provide npm more information on how
your peer dependencies are to be used. Specifically, it allows peer
dependencies to be marked as optional.</p>
<p>For example:</p>
<pre lang="json"><code>{
"name": "tea-latte",
@@ -686,7 +746,10 @@ this. If you depend on features introduced in 1.5.2, use <code>"&gt;= 1.5.2 &lt;
}
}
</code></pre>
<p>Marking a peer dependency as optional ensures npm will not emit a warning if the <code>soy-milk</code> package is not installed on the host. This allows you to integrate and interact with a variety of host packages without requiring all of them to be installed.</p>
<p>Marking a peer dependency as optional ensures npm will not emit a warning
if the <code>soy-milk</code> package is not installed on the host. This allows you to
integrate and interact with a variety of host packages without requiring
all of them to be installed.</p>
<h3 id="bundleddependencies">bundledDependencies</h3>
<p>This defines an array of package names that will be bundled when publishing
the package.</p>
@@ -700,22 +763,22 @@ array and executing <code>npm pack</code>.</p>
"name": "awesome-web-framework",
"version": "1.0.0",
"bundledDependencies": [
"renderized", "super-streams"
"renderized",
"super-streams"
]
}
</code></pre>
<p>we can obtain <code>awesome-web-framework-1.0.0.tgz</code> file by running <code>npm pack</code>.
This file contains the dependencies <code>renderized</code> and <code>super-streams</code> which
can be installed in a new project by executing <code>npm install awesome-web-framework-1.0.0.tgz</code>. Note that the package names do not include
any versions, as that information is specified in <code>dependencies</code>.</p>
can be installed in a new project by executing <code>npm install awesome-web-framework-1.0.0.tgz</code>. Note that the package names do not
include any versions, as that information is specified in <code>dependencies</code>.</p>
<p>If this is spelled <code>"bundleDependencies"</code>, then that is also honored.</p>
<h3 id="optionaldependencies">optionalDependencies</h3>
<p>If a dependency can be used, but you would like npm to proceed if it cannot be
found or fails to install, then you may put it in the <code>optionalDependencies</code>
object. This is a map of package name to version or url, just like the
<code>dependencies</code> object. The difference is that build failures do not cause
installation to fail. Running <code>npm install --no-optional</code> will prevent these
dependencies from being installed.</p>
<p>If a dependency can be used, but you would like npm to proceed if it cannot
be found or fails to install, then you may put it in the
<code>optionalDependencies</code> object. This is a map of package name to version or
url, just like the <code>dependencies</code> object. The difference is that build
failures do not cause installation to fail. Running <code>npm install --no-optional</code> will prevent these dependencies from being installed.</p>
<p>It is still your program’s responsibility to handle the lack of the
dependency. For example, something like this:</p>
<pre lang="js"><code>try {
@@ -738,31 +801,42 @@ if (foo) {
<code>dependencies</code>, so it’s usually best to only put in one place.</p>
<h3 id="engines">engines</h3>
<p>You can specify the version of node that your stuff works on:</p>
<pre lang="json"><code>{ "engines" : { "node" : "&gt;=0.10.3 &lt;0.12" } }
<pre lang="json"><code>{
"engines": {
"node": "&gt;=0.10.3 &lt;15"
}
}
</code></pre>
<p>And, like with dependencies, if you don’t specify the version (or if you
specify “*” as the version), then any version of node will do.</p>
<p>If you specify an “engines” field, then npm will require that “node” be
somewhere on that list. If “engines” is omitted, then npm will just assume
that it works on node.</p>
<p>You can also use the “engines” field to specify which versions of npm
are capable of properly installing your program. For example:</p>
<pre lang="json"><code>{ "engines" : { "npm" : "~1.0.20" } }
<p>You can also use the “engines” field to specify which versions of npm are
capable of properly installing your program. For example:</p>
<pre lang="json"><code>{
"engines": {
"npm": "~1.0.20"
}
}
</code></pre>
<p>Unless the user has set the <code>engine-strict</code> config flag, this
field is advisory only and will only produce warnings when your package is installed as a dependency.</p>
<h3 id="enginestrict">engineStrict</h3>
<p><strong>This feature was removed in npm 3.0.0</strong></p>
<p>Prior to npm 3.0.0, this feature was used to treat this package as if the
user had set <code>engine-strict</code>. It is no longer used.</p>
<p>Unless the user has set the <code>engine-strict</code> config flag, this field is
advisory only and will only produce warnings when your package is installed
as a dependency.</p>
<h3 id="os">os</h3>
<p>You can specify which operating systems your
module will run on:</p>
<pre lang="json"><code>"os" : [ "darwin", "linux" ]
<pre lang="json"><code>{
"os": [
"darwin",
"linux"
]
}
</code></pre>
<p>You can also block instead of allowing operating systems,
just prepend the blocked os with a ‘!’:</p>
<pre lang="json"><code>"os" : [ "!win32" ]
<p>You can also block instead of allowing operating systems, just prepend the
blocked os with a ‘!’:</p>
<pre lang="json"><code>{
"os": [
"!win32"
]
}
</code></pre>
<p>The host operating system is determined by <code>process.platform</code></p>
<p>It is allowed to both block and allow an item, although there isn’t any
@@ -770,44 +844,48 @@ good reason to do this.</p>
<h3 id="cpu">cpu</h3>
<p>If your code only runs on certain cpu architectures,
you can specify which ones.</p>
<pre lang="json"><code>"cpu" : [ "x64", "ia32" ]
<pre lang="json"><code>{
"cpu": [
"x64",
"ia32"
]
}
</code></pre>
<p>Like the <code>os</code> option, you can also block architectures:</p>
<pre lang="json"><code>"cpu" : [ "!arm", "!mips" ]
<pre lang="json"><code>{
"cpu": [
"!arm",
"!mips"
]
}
</code></pre>
<p>The host architecture is determined by <code>process.arch</code></p>
<h3 id="preferglobal">preferGlobal</h3>
<p><strong>DEPRECATED</strong></p>
<p>This option used to trigger an npm warning, but it will no longer warn. It is
purely there for informational purposes. It is now recommended that you install
any binaries as local devDependencies wherever possible.</p>
<h3 id="private">private</h3>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
to publish it.</p>
<p>This is a way to prevent accidental publication of private repositories. If
you would like to ensure that a given package is only ever published to a
specific registry (for example, an internal registry), then use the
<code>publishConfig</code> dictionary described below to override the <code>registry</code> config
param at publish-time.</p>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse to
publish it.</p>
<p>This is a way to prevent accidental publication of private repositories.
If you would like to ensure that a given package is only ever published to
a specific registry (for example, an internal registry), then use the
<code>publishConfig</code> dictionary described below to override the <code>registry</code>
config param at publish-time.</p>
<h3 id="publishconfig">publishConfig</h3>
<p>This is a set of config values that will be used at publish-time. It’s
especially handy if you want to set the tag, registry or access, so that
you can ensure that a given package is not tagged with “latest”, published
to the global public registry or that a scoped module is private by default.</p>
<p>Any config values can be overridden, but only “tag”, “registry” and “access”
probably matter for the purposes of publishing.</p>
<p>See <a href="../using-npm/config.html"><code>config</code></a> to see the list of config options that can be
overridden.</p>
to the global public registry or that a scoped module is private by
default.</p>
<p>See <a href="../using-npm/config.html"><code>config</code></a> to see the list of config options that
can be overridden.</p>
<h3 id="workspaces">workspaces</h3>
<p>The optional <code>workspaces</code> field is an array of file patterns that describes
locations within the local file system that the install client should look up
to find each <a href="../using-npm/workspaces.html">workspace</a> that needs to be symlinked to
the top level <code>node_modules</code> folder.</p>
locations within the local file system that the install client should look
up to find each <a href="../using-npm/workspaces.html">workspace</a> that needs to be
symlinked to the top level <code>node_modules</code> folder.</p>
<p>It can describe either the direct paths of the folders to be used as
workspaces or it can define globs that will resolve to these same folders.</p>
<p>In the following example, all folders located inside the folder <code>./packages</code>
will be treated as workspaces as long as they have valid <code>package.json</code> files
inside them:</p>
<p>In the following example, all folders located inside the folder
<code>./packages</code> will be treated as workspaces as long as they have valid
<code>package.json</code> files inside them:</p>
<pre lang="json"><code>{
"name": "workspace-example",
"workspaces": [
@@ -821,20 +899,20 @@ inside them:</p>
<ul>
<li>
<p><code>"scripts": {"start": "node server.js"}</code></p>
<p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p>
<p>If there is a <code>server.js</code> file in the root of your package, then npm will
default the <code>start</code> command to <code>node server.js</code>.</p>
</li>
<li>
<p><code>"scripts":{"install": "node-gyp rebuild"}</code></p>
<p>If there is a <code>binding.gyp</code> file in the root of your package and you have not defined an <code>install</code> or <code>preinstall</code> script, npm will
default the <code>install</code> command to compile using node-gyp.</p>
<p>If there is a <code>binding.gyp</code> file in the root of your package and you have
not defined an <code>install</code> or <code>preinstall</code> script, npm will default the
<code>install</code> command to compile using node-gyp.</p>
</li>
<li>
<p><code>"contributors": [...]</code></p>
<p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
treat each line as a <code>Name &lt;email&gt; (url)</code> format, where email and url
are optional. Lines which start with a <code>#</code> or are blank, will be
ignored.</p>
<p>If there is an <code>AUTHORS</code> file in the root of your package, npm will treat
each line as a <code>Name &lt;email&gt; (url)</code> format, where email and url are
optional. Lines which start with a <code>#</code> or are blank, will be ignored.</p>
</li>
</ul>
<h3 id="see-also">SEE ALSO</h3>
deps/npm/docs/output/configuring-npm/package-lock-json.html
Vendored
+202 -84
View File
@@ -141,7 +141,7 @@ npm command-line interface
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#file-format">File Format</a></li><ul><li><a href="#name">name</a></li><li><a href="#version">version</a></li><li><a href="#lockfileversion">lockfileVersion</a></li><li><a href="#packageintegrity">packageIntegrity</a></li><li><a href="#preservesymlinks">preserveSymlinks</a></li><li><a href="#dependencies">dependencies</a></li><ul><li><a href="#version2">version</a></li><li><a href="#integrity">integrity</a></li><li><a href="#resolved">resolved</a></li><li><a href="#bundled">bundled</a></li><li><a href="#dev">dev</a></li><li><a href="#optional">optional</a></li><li><a href="#requires">requires</a></li><li><a href="#dependencies2">dependencies</a></li></ul></ul><li><a href="#see-also">See also</a></li></ul></div>
<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#package-lockjson-vs-npm-shrinkwrapjson"><code>package-lock.json</code> vs <code>npm-shrinkwrap.json</code></a></li><li><a href="#hidden-lockfiles">Hidden Lockfiles</a></li><li><a href="#handling-old-lockfiles">Handling Old Lockfiles</a></li><li><a href="#file-format">File Format</a></li><ul><li><a href="#name"><code>name</code></a></li><li><a href="#version"><code>version</code></a></li><li><a href="#lockfileversion"><code>lockfileVersion</code></a></li><li><a href="#packages"><code>packages</code></a></li><li><a href="#dependencies">dependencies</a></li></ul><li><a href="#see-also">See also</a></li></ul></div>
</section>
<div id="_content"><h3 id="description">Description</h3>
@@ -153,106 +153,224 @@ generate identical trees, regardless of intermediate dependency updates.</p>
various purposes:</p>
<ul>
<li>
<p>Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.</p>
<p>Describe a single representation of a dependency tree such that
teammates, deployments, and continuous integration are guaranteed to
install exactly the same dependencies.</p>
</li>
<li>
<p>Provide a facility for users to “time-travel” to previous states of <code>node_modules</code> without having to commit the directory itself.</p>
<p>Provide a facility for users to “time-travel” to previous states of
<code>node_modules</code> without having to commit the directory itself.</p>
</li>
<li>
<p>To facilitate greater visibility of tree changes through readable source control diffs.</p>
<p>Facilitate greater visibility of tree changes through readable source
control diffs.</p>
</li>
<li>
<p>And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.</p>
<p>Optimize the installation process by allowing npm to skip repeated
metadata resolutions for previously-installed packages.</p>
</li>
<li>
<p>As of npm v7, lockfiles include enough information to gain a complete
picture of the package tree, reducing the need to read <code>package.json</code>
files, and allowing for significant performance improvements.</p>
</li>
</ul>
<p>One key detail about <code>package-lock.json</code> is that it cannot be published, and it
will be ignored if found in any place other than the toplevel package. It shares
a format with <a href="../configuring-npm/shrinkwrap-json.html">npm-shrinkwrap.json</a>, which is essentially the same file, but
allows publication. This is not recommended unless deploying a CLI tool or
otherwise using the publication process for producing production packages.</p>
<p>If both <code>package-lock.json</code> and <code>npm-shrinkwrap.json</code> are present in the root of
a package, <code>package-lock.json</code> will be completely ignored.</p>
<h3 id="package-lockjson-vs-npm-shrinkwrapjson"><code>package-lock.json</code> vs <code>npm-shrinkwrap.json</code></h3>
<p>Both of these files have the same format, and perform similar functions in
the root of a project.</p>
<p>The difference is that <code>package-lock.json</code> is that it cannot be published,
and it will be ignored if found in any place other than the root project.</p>
<p>In contrast, <a href="../configuring-npm/npm-shrinkwrap-json.html">npm-shrinkwrap.json</a> 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.</p>
<p>If both <code>package-lock.json</code> and <code>npm-shrinkwrap.json</code> are present in the
root of a project, <code>npm-shrinkwrap.json</code> will take precedence and
<code>package-lock.json</code> will be ignored.</p>
<h3 id="hidden-lockfiles">Hidden Lockfiles</h3>
<p>In order to avoid processing the <code>node_modules</code> folder repeatedly, npm as
of v7 uses a “hidden” lockfile present in
<code>node_modules/.package-lock.json</code>. This contains information about the
tree, and is used in lieu of reading the entire <code>node_modules</code> hierarchy
provided that the following conditions are met:</p>
<ul>
<li>All package folders it references exist in the <code>node_modules</code> hierarchy.</li>
<li>No package folders exist in the <code>node_modules</code> hierarchy that are not
listed in the lockfile.</li>
<li>The modified time of the file is at least as recent as all of the package
folders it references.</li>
</ul>
<p>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.</p>
<p>Note that it <em>is</em> possible to manually change the <em>contents</em> 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 <code>node_modules/foo/lib/bar.js</code>, then the
modified time on <code>node_modules/foo</code> will not reflect this change. If you
are manually editing files in <code>node_modules</code>, it is generally best to
delete the file at <code>node_modules/.package-lock.json</code>.</p>
<p>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 <code>lockfileVersion: 3</code>, rather than
<code>lockfileVersion: 2</code>.</p>
<h3 id="handling-old-lockfiles">Handling Old Lockfiles</h3>
<p>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 <code>node_modules</code> tree or (in the case of empty
<code>node_modules</code> trees or very old lockfile formats) the npm registry.</p>
<h3 id="file-format">File Format</h3>
<h4 id="name">name</h4>
<p>The name of the package this is a package-lock for. This must match what’s in
<code>package.json</code>.</p>
<h4 id="version">version</h4>
<p>The version of the package this is a package-lock for. This must match what’s in
<code>package.json</code>.</p>
<h4 id="lockfileversion">lockfileVersion</h4>
<p>An integer version, starting at <code>1</code> with the version number of this document
whose semantics were used when generating this <code>package-lock.json</code>.</p>
<h4 id="packageintegrity">packageIntegrity</h4>
<p>This is a <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">subresource
integrity</a> value
created from the <code>package.json</code>. No preprocessing of the <code>package.json</code> should
be done. Subresource integrity strings can be produced by modules like
<a href="https://www.npmjs.com/package/ssri"><code>ssri</code></a>.</p>
<h4 id="preservesymlinks">preserveSymlinks</h4>
<p>Indicates that the install was done with the environment variable
<code>NODE_PRESERVE_SYMLINKS</code> enabled. The installer should insist that the value of
this property match that environment variable.</p>
<h4 id="name"><code>name</code></h4>
<p>The name of the package this is a package-lock for. This will match what’s
in <code>package.json</code>.</p>
<h4 id="version"><code>version</code></h4>
<p>The version of the package this is a package-lock for. This will match
what’s in <code>package.json</code>.</p>
<h4 id="lockfileversion"><code>lockfileVersion</code></h4>
<p>An integer version, starting at <code>1</code> with the version number of this
document whose semantics were used when generating this
<code>package-lock.json</code>.</p>
<p>Note that the file format changed significantly in npm v7 to track
information that would have otherwise required looking in <code>node_modules</code> or
the npm registry. Lockfiles generated by npm v7 will contain
<code>lockfileVersion: 2</code>.</p>
<ul>
<li>No version provided: an “ancient” shrinkwrap file from a version of npm
prior to npm v5.</li>
<li><code>1</code>: The lockfile version used by npm v5 and v6.</li>
<li><code>2</code>: The lockfile version used by npm v7, which is backwards compatible
to v1 lockfiles.</li>
<li><code>3</code>: The lockfile version used by npm v7, <em>without</em> backwards
compatibility affordances. This is used for the hidden lockfile at
<code>node_modules/.package-lock.json</code>, and will likely be used in a future
version of npm, once support for npm v6 is no longer relevant.</li>
</ul>
<p>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.</p>
<h4 id="packages"><code>packages</code></h4>
<p>This is an object that maps package locations to an object containing the
information about that package.</p>
<p>The root project is typically listed with a key of <code>""</code>, and all other
packages are listed with their relative paths from the root project folder.</p>
<p>Package descriptors have the following fields:</p>
<ul>
<li>
<p>version: The version found in <code>package.json</code></p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>integrity: A <code>sha512</code> or <code>sha1</code> <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">Standard Subresource
Integrity</a>
string for the artifact that was unpacked in this location.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>dev, optional, devOptional: If the package is strictly part of the
<code>devDependencies</code> tree, then <code>dev</code> will be true. If it is strictly part
of the <code>optionalDependencies</code> tree, then <code>optional</code> will be set. If it
is both a <code>dev</code> dependency <em>and</em> an <code>optional</code> dependency of a non-dev
dependency, then <code>devOptional</code> will be set. (An <code>optional</code> dependency of
a <code>dev</code> dependency will have both <code>dev</code> and <code>optional</code> set.)</p>
</li>
<li>
<p>inBundle: A flag to indicate that the package is a bundled dependency.</p>
</li>
<li>
<p>hasInstallScript: A flag to indicate that the package has a <code>preinstall</code>,
<code>install</code>, or <code>postinstall</code> script.</p>
</li>
<li>
<p>hasShrinkwrap: A flag to indicate that the package has an
<code>npm-shrinkwrap.json</code> file.</p>
</li>
<li>
<p>bin, license, engines, dependencies, optionalDependencies: fields from
<code>package.json</code></p>
</li>
</ul>
<h4 id="dependencies">dependencies</h4>
<p>A mapping of package name to dependency object. Dependency objects have the
following properties:</p>
<h5 id="version2">version</h5>
<p>This is a specifier that uniquely identifies this package and should be
usable in fetching a new copy of it.</p>
<p>Legacy data for supporting versions of npm that use <code>lockfileVersion: 1</code>.
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.</p>
<p>npm v7 ignores this section entirely if a <code>packages</code> section is present,
but does keep it up to date in order to support switching between npm v6
and npm v7.</p>
<p>Dependency objects have the following fields:</p>
<ul>
<li>bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.</li>
<li>
<p>version: a specifier that varies depending on the nature of the package,
and is usable in fetching a new copy of it.</p>
<ul>
<li>bundled dependencies: Regardless of source, this is a version number
that is purely for informational purposes.</li>
<li>registry sources: This is a version number. (eg, <code>1.2.3</code>)</li>
<li>git sources: This is a git specifier with resolved committish. (eg, <code>git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e</code>)</li>
<li>http tarball sources: This is the URL of the tarball. (eg, <code>https://example.com/example-1.3.0.tgz</code>)</li>
<li>local tarball sources: This is the file URL of the tarball. (eg <code>file:///opt/storage/example-1.3.0.tgz</code>)</li>
<li>local link sources: This is the file URL of the link. (eg <code>file:libs/our-module</code>)</li>
<li>git sources: This is a git specifier with resolved committish. (eg,
<code>git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e</code>)</li>
<li>http tarball sources: This is the URL of the tarball. (eg,
<code>https://example.com/example-1.3.0.tgz</code>)</li>
<li>local tarball sources: This is the file URL of the tarball. (eg
<code>file:///opt/storage/example-1.3.0.tgz</code>)</li>
<li>local link sources: This is the file URL of the link. (eg
<code>file:libs/our-module</code>)</li>
</ul>
<h5 id="integrity">integrity</h5>
<p>This is a <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">Standard Subresource
Integrity</a> for this
resource.</p>
<ul>
<li>For bundled dependencies this is not included, regardless of source.</li>
<li>For registry sources, this is the <code>integrity</code> that the registry provided, or if one wasn’t provided the SHA1 in <code>shasum</code>.</li>
<li>For git sources this is the specific commit hash we cloned from.</li>
<li>For remote tarball sources this is an integrity based on a SHA512 of
the file.</li>
<li>For local tarball sources: This is an integrity field based on the SHA512 of the file.</li>
</li>
<li>
<p>integrity: A <code>sha512</code> or <code>sha1</code> <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">Standard Subresource
Integrity</a>
string for the artifact that was unpacked in this location. For git
dependencies, this is the commit sha.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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 <code>dependencies</code> or in a level higher than us.</p>
</li>
<li>
<p>dependencies: The dependencies of this dependency, exactly as at the top
level.</p>
</li>
</ul>
<h5 id="resolved">resolved</h5>
<ul>
<li>For bundled dependencies this is not included, regardless of source.</li>
<li>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.</li>
</ul>
<h5 id="bundled">bundled</h5>
<p>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.</p>
<h5 id="dev">dev</h5>
<p>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.</p>
<h5 id="optional">optional</h5>
<p>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.</p>
<p>All optional dependencies should be included even if they’re uninstallable
on the current platform.</p>
<h5 id="requires">requires</h5>
<p>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
<code>dependencies</code> or in a level higher than us.</p>
<h5 id="dependencies2">dependencies</h5>
<p>The dependencies of this dependency, exactly as at the top level.</p>
<h3 id="see-also">See also</h3>
<ul>
<li><a href="../commands/npm-shrinkwrap.html">npm shrinkwrap</a></li>
<li><a href="../configuring-npm/shrinkwrap-json.html">shrinkwrap.json</a></li>
<li><a href="../configuring-npm/package-locks.html">package-locks</a></li>
<li><a href="../configuring-npm/npm-shrinkwrap-json.html">npm-shrinkwrap.json</a></li>
<li><a href="../configuring-npm/package-json.html">package.json</a></li>
<li><a href="../commands/npm-install.html">npm install</a></li>
</ul>
deps/npm/docs/output/configuring-npm/package-locks.html
Vendored
-310
View File
@@ -1,310 +0,0 @@
<html><head>
<title>package-locks</title>
<style>
body {
background-color: #ffffff;
color: #24292e;
margin: 0;
line-height: 1.5;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
}
#rainbar {
height: 10px;
background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff);
}
a {
text-decoration: none;
color: #0366d6;
}
a:hover {
text-decoration: underline;
}
pre {
margin: 1em 0px;
padding: 1em;
border: solid 1px #e1e4e8;
border-radius: 6px;
display: block;
overflow: auto;
white-space: pre;
background-color: #f6f8fa;
color: #393a34;
}
code {
font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace;
font-size: 85%;
padding: 0.2em 0.4em;
background-color: #f6f8fa;
color: #393a34;
}
pre > code {
padding: 0;
background-color: inherit;
color: inherit;
}
h1, h2, h3 {
font-weight: 600;
}
#logobar {
background-color: #333333;
margin: 0 auto;
padding: 1em 4em;
}
#logobar .logo {
float: left;
}
#logobar .title {
font-weight: 600;
color: #dddddd;
float: left;
margin: 5px 0 0 1em;
}
#logobar:after {
content: "";
display: block;
clear: both;
}
#content {
margin: 0 auto;
padding: 0 4em;
}
#table_of_contents > h2 {
font-size: 1.17em;
}
#table_of_contents ul:first-child {
border: solid 1px #e1e4e8;
border-radius: 6px;
padding: 1em;
background-color: #f6f8fa;
color: #393a34;
}
#table_of_contents ul {
list-style-type: none;
padding-left: 1.5em;
}
#table_of_contents li {
font-size: 0.9em;
}
#table_of_contents li a {
color: #000000;
}
header.title {
border-bottom: solid 1px #e1e4e8;
}
header.title > h1 {
margin-bottom: 0.25em;
}
header.title > .description {
display: block;
margin-bottom: 0.5em;
line-height: 1;
}
footer#edit {
border-top: solid 1px #e1e4e8;
margin: 3em 0 4em 0;
padding-top: 2em;
}
</style>
</head>
<body>
<div id="banner">
<div id="rainbar"></div>
<div id="logobar">
<svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700">
<polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon>
<polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon>
</svg>
<div class="title">
npm command-line interface
</div>
</div>
</div>
<section id="content">
<header class="title">
<h1 id="package-locks">package-locks</h1>
<span class="description">An explanation of npm lockfiles</span>
</header>
<section id="table_of_contents">
<h2 id="table-of-contents">Table of contents</h2>
<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><ul><li><a href="#using-locked-packages">Using locked packages</a></li><li><a href="#resolving-lockfile-conflicts">Resolving lockfile conflicts</a></li></ul><li><a href="#see-also">See Also</a></li></ul></div>
</section>
<div id="_content"><h3 id="description">Description</h3>
<p>Conceptually, the “input” to <a href="../commands/npm-install.html"><code>npm install</code></a> is a <a href="../configuring-npm/package-json.html">package.json</a>, while its
“output” is a fully-formed <code>node_modules</code> tree: a representation of the
dependencies you declared. In an ideal world, npm would work like a pure
function: the same <code>package.json</code> should produce the exact same <code>node_modules</code>
tree, any time. In some cases, this is indeed true. But in many others, npm is
unable to do this. There are multiple reasons for this:</p>
<ul>
<li>
<p>different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.</p>
</li>
<li>
<p>a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.</p>
</li>
<li>
<p>A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (<code>1.2.3</code> instead of <code>^1.2.3</code>)</p>
</li>
<li>
<p>The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.</p>
</li>
</ul>
<p>As an example, consider package A:</p>
<pre lang="json"><code>{
"name": "A",
"version": "0.1.0",
"dependencies": {
"B": "&lt;0.1.0"
}
}
</code></pre>
<p>package B:</p>
<pre lang="json"><code>{
"name": "B",
"version": "0.0.1",
"dependencies": {
"C": "&lt;0.1.0"
}
}
</code></pre>
<p>and package C:</p>
<pre lang="json"><code>{
"name": "C",
"version": "0.0.1"
}
</code></pre>
<p>If these are the only versions of A, B, and C available in the
registry, then a normal <code>npm install A</code> will install:</p>
<pre lang="json"><code>A@0.1.0
`-- B@0.0.1
`-- C@0.0.1
</code></pre>
<p>However, if B@0.0.2 is published, then a fresh <code>npm install A</code> will
install:</p>
<pre lang="bash"><code>A@0.1.0
`-- B@0.0.2
`-- C@0.0.1
</code></pre>
<p>assuming the new version did not modify B’s dependencies. Of course,
the new version of B could include a new version of C and any number
of new dependencies. If such changes are undesirable, the author of A
could specify a dependency on B@0.0.1. However, if A’s author and B’s
author are not the same person, there’s no way for A’s author to say
that he or she does not want to pull in newly published versions of C
when B hasn’t changed at all.</p>
<p>To prevent this potential issue, npm uses <a href="../configuring-npm/package-lock-json.html">package-lock.json</a> or, if present, <a href="../configuring-npm/shrinkwrap-json.html">npm-shrinkwrap.json</a>. These files are called package locks, or lockfiles.</p>
<p>Whenever you run <code>npm install</code>, npm generates or updates your package lock,
which will look something like this:</p>
<pre lang="json"><code>{
"name": "A",
"version": "0.1.0",
...metadata fields...
"dependencies": {
"B": {
"version": "0.0.1",
"resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
"integrity": "sha512-DeAdb33F+"
"dependencies": {
"C": {
"version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
}
}
}
}
}
</code></pre>
<p>This file describes an <em>exact</em>, and more importantly <em>reproducible</em>
<code>node_modules</code> tree. Once it’s present, any future installation will base its
work off this file, instead of recalculating dependency versions off
<a href="../configuring-npm/package-json.html">package.json</a>.</p>
<p>The presence of a package lock changes the installation behavior such that:</p>
<ol>
<li>
<p>The module tree described by the package lock is reproduced. This means
reproducing the structure described in the file, using the specific files
referenced in “resolved” if available, falling back to normal package resolution
using “version” if one isn’t.</p>
</li>
<li>
<p>The tree is walked and any missing dependencies are installed in the usual
fashion.</p>
</li>
</ol>
<p>If <code>preshrinkwrap</code>, <code>shrinkwrap</code> or <code>postshrinkwrap</code> are in the <code>scripts</code>
property of the <code>package.json</code>, they will be executed in order. <code>preshrinkwrap</code>
and <code>shrinkwrap</code> are executed before the shrinkwrap, <code>postshrinkwrap</code> is
executed afterwards. These scripts run for both <code>package-lock.json</code> and
<code>npm-shrinkwrap.json</code>. For example to run some postprocessing on the generated
file:</p>
<pre lang="json"><code> "scripts": {
"postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
}
</code></pre>
<h4 id="using-locked-packages">Using locked packages</h4>
<p>Using a locked package is no different than using any package without a package
lock: any commands that update <code>node_modules</code> and/or <code>package.json</code>’s
dependencies will automatically sync the existing lockfile. This includes <code>npm install</code>, <code>npm rm</code>, <code>npm update</code>, etc. To prevent this update from happening,
you can use the <code>--no-save</code> option to prevent saving altogether, or
<code>--no-shrinkwrap</code> to allow <code>package.json</code> to be updated while leaving
<code>package-lock.json</code> or <code>npm-shrinkwrap.json</code> intact.</p>
<p>It is highly recommended you commit the generated package lock to source
control: this will allow anyone else on your team, your deployments, your
CI/continuous integration, and anyone else who runs <code>npm install</code> in your
package source to get the exact same dependency tree that you were developing
on. Additionally, the diffs from these changes are human-readable and will
inform you of any changes npm has made to your <code>node_modules</code>, so you can notice
if any transitive dependencies were updated, hoisted, etc.</p>
<h4 id="resolving-lockfile-conflicts">Resolving lockfile conflicts</h4>
<p>Occasionally, two separate npm install will create package locks that cause
merge conflicts in source control systems. As of <code>npm@5.7.0</code>, these conflicts
can be resolved by manually fixing any <code>package.json</code> conflicts, and then
running <code>npm install [--package-lock-only]</code> again. npm will automatically
resolve any conflicts for you and write a merged package lock that includes all
the dependencies from both branches in a reasonable tree. If
<code>--package-lock-only</code> is provided, it will do this without also modifying your
local <code>node_modules/</code>.</p>
<p>To make this process seamless on git, consider installing
<a href="https://npm.im/npm-merge-driver"><code>npm-merge-driver</code></a>, which will teach git how
to do this itself without any user interaction. In short: <code>$ npx npm-merge-driver install -g</code> will let you do this, and even works with
pre-<code>npm@5.7.0</code> versions of npm 5, albeit a bit more noisily. Note that if
<code>package.json</code> itself conflicts, you will have to resolve that by hand and run
<code>npm install</code> manually, even with the merge driver.</p>
<h3 id="see-also">See Also</h3>
<ul>
<li><a href="https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527">https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527</a></li>
<li><a href="../configuring-npm/package-json.html">package.json</a></li>
<li><a href="../configuring-npm/package-lock-json.html">package-lock.json</a></li>
<li><a href="../configuring-npm/shrinkwrap-json.html">shrinkwrap.json</a></li>
<li><a href="../commands/npm-shrinkwrap.html">npm shrinkwrap</a></li>
</ul>
</div>
<footer id="edit">
<a href="https://github.com/npm/cli/edit/latest/docs/content/configuring-npm/package-locks.md">
<svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;">
<path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path>
</svg>
Edit this page on GitHub
</a>
</footer>
</section>
</body></html>
deps/npm/lib/link.js
Vendored
+3
View File
@@ -45,6 +45,9 @@ const link = async args => {
// Returns a list of items that can't be fulfilled by
// things found in the current arborist inventory
const missingArgsFromTree = (tree, args) => {
if (tree.isLink)
return missingArgsFromTree(tree.target, args)
const foundNodes = []
const missing = args.filter(a => {
const arg = npa(a)
deps/npm/lib/ls.js
Vendored
+1 -1
View File
@@ -99,7 +99,7 @@ const getHumanOutputItem = (node, { args, color, global, long }) => {
// special formatting for top-level package name
if (node.isRoot) {
const hasNoPackageJson = !Object.keys(node.package).length
if (hasNoPackageJson)
if (hasNoPackageJson || global)
printable = path
else
printable += `${long ? EOL : ' '}${path}`
deps/npm/lib/search.js
Vendored
+1 -1
View File
@@ -12,7 +12,7 @@ const completion = require('./utils/completion/none.js')
const usage = usageUtil(
'search',
'npm search [--long] [search terms ...]'
'npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]'
)
const cmd = (args, cb) => search(args).then(() => cb()).catch(cb)
deps/npm/lib/token.js
Vendored
+1 -1
View File
@@ -17,7 +17,7 @@ token._validateCIDRList = validateCIDRList
const usageUtil = require('./utils/usage.js')
token.usage = usageUtil('token',
'npm token list\n' +
'npm token revoke <tokenKey>\n' +
'npm token revoke <id|token>\n' +
'npm token create [--read-only] [--cidr=list]')
const UsageError = (msg) =>
deps/npm/lib/uninstall.js
Vendored
+1 -1
View File
@@ -9,7 +9,7 @@ const completion = require('./utils/completion/installed-shallow.js')
const usage = usageUtil(
'uninstall',
'npm uninstall [<@scope>/]<pkg>[@<version>]... [--save-prod|--save-dev|--save-optional] [--no-save]'
'npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]'
)
const cmd = (args, cb) => rm(args).then(() => cb()).catch(cb)
deps/npm/lib/unpublish.js
Vendored
+1 -1
View File
@@ -35,7 +35,7 @@ const completionFn = async (args) => {
const access = await libaccess.lsPackages(username, opts)
// do a bit of filtering at this point, so that we don't need
// to fetch versions for more than one thing, but also don't
// accidentally a whole project
// accidentally unpublish a whole project
let pkgs = Object.keys(access || {})
if (!partialWord || !pkgs.length)
return pkgs
deps/npm/man/man1/npm-audit.1
Vendored
-2
View File
@@ -205,8 +205,6 @@ $ npm audit \-\-audit\-level=moderate
.IP \(bu 2
npm help install
.IP \(bu 2
npm help package\-locks
.IP \(bu 2
npm help config
.RE
deps/npm/man/man1/npm-ci.1
Vendored
+1 -1
View File
@@ -83,6 +83,6 @@ cache:
.IP \(bu 2
npm help install
.IP \(bu 2
npm help package\-locks
npm help package\-lock\.json
.RE
deps/npm/man/man1/npm-ls.1
Vendored
+1 -1
View File
@@ -26,7 +26,7 @@ example, running \fBnpm ls promzard\fP in npm's source tree will show:
.P
.RS 2
.nf
npm@7\.4\.0 /path/to/npm
npm@7\.4\.2 /path/to/npm
└─┬ init\-package\-json@0\.0\.4
└── promzard@0\.1\.5
.fi
deps/npm/man/man1/npm-prefix.1
Vendored
+16 -1
View File
@@ -10,12 +10,27 @@ npm prefix [\-g]
.RE
.SS Description
.P
Print the local prefix to standard out\. This is the closest parent directory
Print the local prefix to standard output\. This is the closest parent directory
to contain a \fBpackage\.json\fP file or \fBnode_modules\fP directory, unless \fB\-g\fP is
also specified\.
.P
If \fB\-g\fP is specified, this will be the value of the global prefix\. See
npm help \fBconfig\fP for more detail\.
.SS Example
.P
.RS 2
.nf
npm prefix
/usr/local/projects/foo
.fi
.RE
.P
.RS 2
.nf
npm prefix \-g
/usr/local
.fi
.RE
.SS See Also
.RS 0
.IP \(bu 2
deps/npm/man/man1/npm-search.1
Vendored
+55 -33
View File
@@ -14,25 +14,28 @@ aliases: s, se, find
.P
Search the registry for packages matching the search terms\. \fBnpm search\fP
performs a linear, incremental, lexically\-ordered search through package
metadata for all files in the registry\. If color is enabled, it will further
highlight the matches in the results\.
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 \fBcolor\fP
.P
Additionally, using the \fB\-\-searchopts\fP and \fB\-\-searchexclude\fP options paired with
more search terms will respectively include and exclude further patterns\. The
main difference between \fB\-\-searchopts\fP and the standard search terms is that the
former does not highlight results in the output and can be used for more
fine\-grained filtering\. Additionally, both of these can be added to \fB\|\.npmrc\fP for
default search filtering behavior\.
Additionally, using the \fB\-\-searchopts\fP and \fB\-\-searchexclude\fP options
paired with more search terms will include and exclude further patterns\.
The main difference between \fB\-\-searchopts\fP 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\.
.P
Search also allows targeting of maintainers in search results, by prefixing
their npm username with \fB=\fP\|\.
.P
If a term starts with \fB/\fP, then it's interpreted as a regular expression and
supports standard JavaScript RegExp syntax\. A trailing \fB/\fP will be ignored in
this case\. (Note that many regular expression characters must be escaped or
quoted in most shells\.)
.SS A Note on caching
If a term starts with \fB/\fP, then it's interpreted as a regular expression
and supports standard JavaScript RegExp syntax\. In this case search will
ignore a trailing \fB/\fP \. (Note you must escape or quote many regular
expression characters in most shells\.)
.SS Configuration
.P
All of the following can be defined in a \fB\|\.npmrc\fP file, or passed as
parameters to the cli prefixed with \fB\-\-\fP (e\.g\. \fB\-\-json\fP)
.SS description
.RS 0
.IP \(bu 2
@@ -40,10 +43,18 @@ Default: true
.IP \(bu 2
Type: Boolean
.RE
.SS color
.RS 0
.IP \(bu 2
Default: true
.IP \(bu 2
Type: Boolean
.RE
.P
Used as \fB\-\-no\-description\fP, disables search matching in package descriptions and
suppresses display of that field in results\.
Used as \fB\-\-no\-color\fP, disables color highlighting of matches in the
results\.
.SS json
.RS 0
.IP \(bu 2
@@ -74,9 +85,9 @@ Type: Boolean
.RE
.P
Display full package descriptions and other long text across multiple
lines\. When disabled (default) search results are truncated to fit
neatly on a single line\. Modules with extremely long names will
fall on multiple lines\.
lines\. When disabled (which is the default) the output will
truncate search results to fit neatly on a single line\. Modules with
extremely long names will fall on multiple lines\.
.SS searchopts
.RS 0
.IP \(bu 2
@@ -97,16 +108,6 @@ Type: String
.RE
.P
Space\-separated options that limit the results from search\.
.SS searchstaleness
.RS 0
.IP \(bu 2
Default: 900 (15 minutes)
.IP \(bu 2
Type: Number
.RE
.P
The age of the cache, in seconds, before another registry request is made\.
.SS registry
.RS 0
.IP \(bu 2
@@ -116,11 +117,28 @@ Type: url
.RE
.P
Search the specified registry for modules\. If you have configured npm to point
to a different default registry, such as your internal private module
repository, \fBnpm search\fP will default to that registry when searching\. Pass a
different registry url such as the default above in order to override this
setting\.
Search the specified registry for modules\. If you have configured npm to
point to a different default registry (such as your internal private
module repository), \fBnpm search\fP will also default to that registry when
searching\.
.SS A note on caching
.P
The npm cli caches search results with the same terms and options
locally in its cache\. You can use the following to change how and when
the cli uses this cache\. See npm help \fBcache\fP for more
on how the cache works\.
.SS prefer\-online
.P
Forced staleness checks for cached searches, making the cli look for
updates immediately even for fresh search results\.
.SS prefer\-offline
.P
Bypasses staleness checks for cached\. Missing data will still be
requested from the server\. To force full offline mode, use \fBoffline\fP\|\.
.SS offline
.P
Forces full offline mode\. Any searches not locally cached will result in
an error\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -131,5 +149,9 @@ npm help config
npm help npmrc
.IP \(bu 2
npm help view
.IP \(bu 2
npm help cache
.IP \(bu 2
https://npm\.im/npm\-registry\-fetch
.RE
deps/npm/man/man1/npm-shrinkwrap.1
Vendored
+7 -8
View File
@@ -11,10 +11,11 @@ npm shrinkwrap
.SS Description
.P
This command repurposes \fBpackage\-lock\.json\fP into a publishable
\fBnpm\-shrinkwrap\.json\fP or simply creates a new one\. The file created and updated
by this command will then take precedence over any other existing or future
\fBpackage\-lock\.json\fP files\. For a detailed explanation of the design and purpose
of package locks in npm, see npm help package\-locks\.
\fBnpm\-shrinkwrap\.json\fP or simply creates a new one\. The file created and
updated by this command will then take precedence over any other existing
or future \fBpackage\-lock\.json\fP files\. For a detailed explanation of the
design and purpose of package locks in npm, see
npm help package\-lock\-json\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -24,13 +25,11 @@ npm help run\-script
.IP \(bu 2
npm help scripts
.IP \(bu 2
npm help package\.js
.IP \(bu 2
npm help package\-locks
npm help package\.json
.IP \(bu 2
npm help package\-lock\.json
.IP \(bu 2
npm help shrinkwrap\.json
npm help npm\-shrinkwrap\.json
.IP \(bu 2
npm help ls
deps/npm/man/man1/npm-start.1
Vendored
+32 -3
View File
@@ -10,12 +10,41 @@ npm start [\-\- <args>]
.RE
.SS Description
.P
This runs an arbitrary command specified in the package's \fB"start"\fP property of
its \fB"scripts"\fP object\. If no \fB"start"\fP property is specified on the
\fB"scripts"\fP object, it will run \fBnode server\.js\fP\|\.
This runs a predefined command specified in the \fB"start"\fP property of
a package's \fB"scripts"\fP object\.
.P
If the \fB"scripts"\fP object does not define a \fB"start"\fP property, npm
will run \fBnode server\.js\fP\|\.
.P
Note that this is different from the default node behavior of running
the file specified in a package's \fB"main"\fP attribute when evoking with
\fBnode \.\fP
.P
As of \fBnpm@2\.0\.0\fP \fIhttps://blog\.npmjs\.org/post/98131109725/npm\-2\-0\-0\fR, you can
use custom arguments when executing scripts\. Refer to npm help \fBrun\-script\fP for more details\.
.SS Example
.P
.RS 2
.nf
{
"scripts": {
"start": "node foo\.js"
}
}
.fi
.RE
.P
.RS 2
.nf
npm start
> npm@x\.x\.x start
> node foo\.js
(foo\.js output would be here)
.fi
.RE
.SS See Also
.RS 0
.IP \(bu 2
deps/npm/man/man1/npm-stop.1
Vendored
+28 -1
View File
@@ -10,7 +10,34 @@ npm stop [\-\- <args>]
.RE
.SS Description
.P
This runs a package's "stop" script, if one was provided\.
This runs a predefined command specified in the "stop" property of a
package's "scripts" object\.
.P
Unlike with npm help start, there is no default script
that will run if the \fB"stop"\fP property is not defined\.
.SS Example
.P
.RS 2
.nf
{
"scripts": {
"stop": "node bar\.js"
}
}
.fi
.RE
.P
.RS 2
.nf
npm stop
> npm@x\.x\.x stop
> node bar\.js
(bar\.js output would be here)
.fi
.RE
.SS See Also
.RS 0
.IP \(bu 2
deps/npm/man/man1/npm-test.1
Vendored
+23 -1
View File
@@ -12,7 +12,29 @@ aliases: t, tst
.RE
.SS Description
.P
This runs a package's "test" script, if one was provided\.
This runs a predefined command specified in the \fB"test"\fP property of
a package's \fB"scripts"\fP object\.
.SS Example
.P
.RS 2
.nf
{
"scripts": {
"test": "node test\.js"
}
}
.fi
.RE
.P
.RS 2
.nf
npm test
> npm@x\.x\.x test
> node test\.js
(test\.js output would be here)
.fi
.RE
.SS See Also
.RS 0
.IP \(bu 2
deps/npm/man/man1/npm-token.1
Vendored
+18 -10
View File
@@ -16,8 +16,8 @@ This lets you list, create and revoke authentication tokens\.
.RS 0
.IP \(bu 2
\fBnpm token list\fP:
Shows a table of all active authentication tokens\. You can request this as
JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
Shows a table of all active authentication tokens\. You can request
this as JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
.RE
.P
@@ -45,10 +45,16 @@ JSON with \fB\-\-json\fP or tab\-separated values with \fB\-\-parseable\fP\|\.
.RS 0
.IP \(bu 2
\fBnpm token create [\-\-read\-only] [\-\-cidr=<cidr\-ranges>]\fP:
Create a new authentication token\. It can be \fB\-\-read\-only\fP or accept a list of
CIDR \fIhttps://en\.wikipedia\.org/wiki/Classless_Inter\-Domain_Routing\fR ranges to
limit use of this token to\. 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 \fB\-\-read\-only\fP, or accept
a list of
CIDR \fIhttps://en\.wikipedia\.org/wiki/Classless_Inter\-Domain_Routing\fR
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 \fIhttps://docs\.npmjs\.com/creating\-and\-viewing\-access\-tokens\fR
for more information on generating automation tokens\.
.RE
.P
@@ -68,9 +74,11 @@ two\-factor authentication enabled, an otp\.
.RS 0
.IP \(bu 2
\fBnpm token revoke <token|id>\fP:
This removes an authentication token, making it immediately unusable\. This can accept
both complete tokens (as you get back from \fBnpm token create\fP and will
find in your \fB\|\.npmrc\fP) and ids as seen in the \fBnpm token list\fP output\.
This will NOT accept the truncated token found in \fBnpm token list\fP 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 \fBnpm token create\fP, and those
found in your \fB\|\.npmrc\fP), and ids as seen in the parseable or json
output of \fBnpm token list\fP\|\. This will NOT accept the truncated token
found in the normal \fBnpm token list\fP output\.
.RE
deps/npm/man/man1/npm-uninstall.1
Vendored
+27 -29
View File
@@ -5,7 +5,7 @@
.P
.RS 2
.nf
npm uninstall [<@scope>/]<pkg>[@<version>]\.\.\. [\-S|\-\-save|\-D|\-\-save\-dev|\-O|\-\-save\-optional|\-\-no\-save]
npm uninstall [<@scope>/]<pkg>[@<version>]\.\.\. [\-S|\-\-save|\-\-no\-save]
aliases: remove, rm, r, un, unlink
.fi
@@ -15,7 +15,27 @@ aliases: remove, rm, r, un, unlink
This uninstalls a package, completely removing everything npm installed
on its behalf\.
.P
Example:
It also removes the package from the \fBdependencies\fP, \fBdevDependencies\fP,
\fBoptionalDependencies\fP, and \fBpeerDependencies\fP objects in your
\fBpackage\.json\fP\|\.
.P
Futher, if you have an \fBnpm\-shrinkwrap\.json\fP or \fBpackage\-lock\.json\fP, npm
will update those files as well\.
.P
\fB\-\-no\-save\fP will tell npm not to remove the package from your
\fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, or \fBpackage\-lock\.json\fP files\.
.P
\fB\-\-save\fP or \fB\-S\fP will tell npm to remove the package from your
\fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, and \fBpackage\-lock\.json\fP files\.
This is the default, but you may need to use this if you have for
instance \fBsave=false\fP in your \fBnpmrc\fP file
.P
In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
it uninstalls the current package context as a global package\.
\fB\-\-no\-save\fP is ignored in this case\.
.P
Scope is optional and follows the usual rules for npm help \fBscope\fP\|\.
.SS Examples
.P
.RS 2
.nf
@@ -23,39 +43,17 @@ npm uninstall sax
.fi
.RE
.P
In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
it uninstalls the current package context as a global package\.
.P
\fBnpm uninstall\fP takes 3 exclusive, optional flags which save or update
the package version in your main package\.json:
.RS 0
.IP \(bu 2
\fB\-S, \-\-save\fP: Package will be removed from your \fBdependencies\fP\|\.
.IP \(bu 2
\fB\-D, \-\-save\-dev\fP: Package will be removed from your \fBdevDependencies\fP\|\.
.IP \(bu 2
\fB\-O, \-\-save\-optional\fP: Package will be removed from your \fBoptionalDependencies\fP\|\.
.IP \(bu 2
\fB\-\-no\-save\fP: Package will not be removed from your \fBpackage\.json\fP file\.
.RE
.P
Further, if you have an \fBnpm\-shrinkwrap\.json\fP then it will be updated as
well\.
.P
Scope is optional and follows the usual rules for npm help \fBscope\fP\|\.
.P
Examples:
\fBsax\fP will no longer be in your \fBpackage\.json\fP, \fBnpm\-shrinkwrap\.json\fP, or
\fBpackage\-lock\.json\fP files\.
.P
.RS 2
.nf
npm uninstall sax \-\-save
npm uninstall @myorg/privatepackage \-\-save
npm uninstall node\-tap \-\-save\-dev
npm uninstall dtrace\-provider \-\-save\-optional
npm uninstall lodash \-\-no\-save
.fi
.RE
.P
\fBlodash\fP will not be removed from your \fBpackage\.json\fP,
\fBnpm\-shrinkwrap\.json\fP, or \fBpackage\-lock\.json\fP files\.
.SS See Also
.RS 0
.IP \(bu 2
deps/npm/man/man1/npm-unpublish.1
Vendored
+20 -9
View File
@@ -2,6 +2,10 @@
.SH "NAME"
\fBnpm-unpublish\fR \- Remove a package from the registry
.SS Synopsis
.P
To learn more about how the npm registry treats unpublish, see our <a
href="https://www\.npmjs\.com/policies/unpublish" target="_blank"
rel="noopener noreferrer"> unpublish policies</a>
.SS Unpublishing a single version of a package
.P
.RS 2
@@ -18,20 +22,25 @@ npm unpublish [<@scope>/]<pkg> \-\-force
.RE
.SS Warning
.P
Consider using the \fBdeprecate\fP command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package\.
Consider using the npm help \fBdeprecate\fP command instead,
if your intent is to encourage users to upgrade, or if you no longer
want to maintain a package\.
.SS Description
.P
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\.
.P
If no version is specified, or if all versions are removed then
the root package entry is removed from the registry entirely\.
The npm registry will return an error if you are not npm help logged
in\.
.P
Even if a package version is unpublished, that specific name and
version combination can never be reused\. In order to publish the
package again, a new version number must be used\. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed\.
If you 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\.
.P
To learn more about how unpublish is treated on the npm registry, see our <a href="https://www\.npmjs\.com/policies/unpublish" target="_blank" rel="noopener noreferrer"> unpublish policies</a>\|\.
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\.
.SS See Also
.RS 0
.IP \(bu 2
@@ -44,5 +53,7 @@ npm help registry
npm help adduser
.IP \(bu 2
npm help owner
.IP \(bu 2
npm help login
.RE
deps/npm/man/man1/npm.1
Vendored
+1 -1
View File
@@ -10,7 +10,7 @@ npm <command> [args]
.RE
.SS Version
.P
7\.4\.0
7\.4\.2
.SS Description
.P
npm is the package manager for the Node JavaScript platform\. It puts
deps/npm/man/man5/install.5
Vendored
+37 -14
View File
@@ -3,20 +3,30 @@
\fBinstall\fR \- Download and install node and npm
.SS Description
.P
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\. \fBWe strongly recommend using a Node version manager to install Node\.js and npm\.\fR 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\. \fBWe strongly recommend using a Node
version manager to install Node\.js and npm\.\fR 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\.
.SS Overview
.RS 0
.IP \(bu 2
Checking your version of npm and Node\.js \fI#checking\-your\-version\-of\-npm\-and\-node\-js\fR
Checking your version of npm and
Node\.js \fI#checking\-your\-version\-of\-npm\-and\-node\-js\fR
.IP \(bu 2
Using a Node version manager to install Node\.js and npm \fI#using\-a\-node\-version\-manager\-to\-install\-node\-js\-and\-npm\fR
Using a Node version manager to install Node\.js and
npm \fI#using\-a\-node\-version\-manager\-to\-install\-node\-js\-and\-npm\fR
.IP \(bu 2
Using a Node installer to install Node\.js and npm \fI#using\-a\-node\-installer\-to\-install\-node\-js\-and\-npm\fR
Using a Node installer to install Node\.js and
npm \fI#using\-a\-node\-installer\-to\-install\-node\-js\-and\-npm\fR
.RE
.SS Checking your version of npm and Node\.js
.P
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:
.P
.RS 2
.nf
@@ -26,7 +36,10 @@ npm \-v
.RE
.SS Using a Node version manager to install Node\.js and npm
.P
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\.
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\.
.SS OSX or Linux Node version managers
.RS 0
.IP \(bu 2
@@ -45,29 +58,39 @@ nvm\-windows \fIhttps://github\.com/coreybutler/nvm\-windows\fR
.RE
.SS Using a Node installer to install Node\.js and npm
.P
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\.
.RS 0
.IP \(bu 2
Node\.js installer \fIhttps://nodejs\.org/en/download/\fR
.IP \(bu 2
NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR\|\. If you use Linux, we recommend that you use a NodeSource installer\.
NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR\|\. If
you use Linux, we recommend that you use a NodeSource installer\.
.RE
.SS OS X or Windows Node installers
.P
If you're using OS X or Windows, use one of the installers from the Node\.js download page \fIhttps://nodejs\.org/en/download/\fR\|\. Be sure to install the version labeled \fBLTS\fR\|\. Other versions have not yet been tested with npm\.
If you're using OS X or Windows, use one of the installers from the
Node\.js download page \fIhttps://nodejs\.org/en/download/\fR\|\. Be sure to
install the version labeled \fBLTS\fR\|\. Other versions have not yet been
tested with npm\.
.SS Linux or other operating systems Node installers
.P
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:
.RS 0
.IP \(bu 2
NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR (recommended)
NodeSource installer \fIhttps://github\.com/nodesource/distributions\fR
(recommended)
.IP \(bu 2
One of the installers on the Node\.js download page \fIhttps://nodejs\.org/en/download/\fR
One of the installers on the Node\.js download
page \fIhttps://nodejs\.org/en/download/\fR
.RE
.P
Or see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR to install npm for Linux in the way many Linux developers prefer\.
Or see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR to
install npm for Linux in the way many Linux developers prefer\.
.SS Less\-common operating systems
.P
For more information on installing Node\.js on a variety of operating systems, see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR\|\.
For more information on installing Node\.js on a variety of operating
systems, see this page \fIhttps://nodejs\.org/en/download/package\-manager/\fR\|\.
deps/npm/man/man5/shrinkwrap-json.5 → deps/npm/man/man5/npm-shrinkwrap-json.5
Vendored
+13 -9
View File
@@ -1,23 +1,27 @@
.TH "SHRINKWRAP\.JSON" "5" "January 2021" "" ""
.TH "NPM\-SHRINKWRAP\.JSON" "5" "January 2021" "" ""
.SH "NAME"
\fBshrinkwrap.json\fR \- A publishable lockfile
\fBnpm-shrinkwrap.json\fR \- A publishable lockfile
.SS Description
.P
\fBnpm\-shrinkwrap\.json\fP is a file created by npm help \fBshrinkwrap\fP\|\. It is identical to
\fBnpm\-shrinkwrap\.json\fP is a file created by npm help \fBnpm
shrinkwrap\fP\|\. It is identical to
\fBpackage\-lock\.json\fP, with one major caveat: Unlike \fBpackage\-lock\.json\fP,
\fBnpm\-shrinkwrap\.json\fP may be included when publishing a package\.
.P
The recommended use\-case for \fBnpm\-shrinkwrap\.json\fP is applications deployed
through the publishing process on the registry: for example, daemons and
command\-line tools intended as global installs or \fBdevDependencies\fP\|\. It's
strongly discouraged for library authors to publish this file, since that would
prevent end users from having control over transitive dependency updates\.
strongly discouraged for library authors to publish this file, since that
would prevent end users from having control over transitive dependency
updates\.
.P
Additionally, if both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present
in a package root, \fBpackage\-lock\.json\fP will be ignored in favor of this file\.
If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in a
package root, \fBnpm\-shrinkwrap\.json\fP will be preferred over the
\fBpackage\-lock\.json\fP file\.
.P
For full details and description of the \fBnpm\-shrinkwrap\.json\fP file format, refer
to the manual page for npm help package\-lock\.json\.
For full details and description of the \fBnpm\-shrinkwrap\.json\fP file format,
refer to the manual page for
npm help package\-lock\.json\.
.SS See also
.RS 0
.IP \(bu 2
deps/npm/man/man5/npmrc.5
Vendored
+27 -26
View File
@@ -3,13 +3,14 @@
\fBnpmrc\fR \- The npm config files
.SS Description
.P
npm gets its config settings from the command line, environment
variables, and \fBnpmrc\fP files\.
npm gets its config settings from the command line, environment variables,
and \fBnpmrc\fP files\.
.P
The \fBnpm config\fP command can be used to update and edit the contents
of the user and global npmrc files\.
The \fBnpm config\fP command can be used to update and edit the contents of the
user and global npmrc files\.
.P
For a list of available configuration options, see npm help config\.
For a list of available configuration options, see
npm help config\.
.SS Files
.P
The four relevant files are:
@@ -25,9 +26,9 @@ npm builtin config file (/path/to/npm/npmrc)
.RE
.P
All npm config files are an ini\-formatted list of \fBkey = value\fP
parameters\. Environment variables can be replaced using
\fB${VARIABLE_NAME}\fP\|\. For example:
All npm config files are an ini\-formatted list of \fBkey = value\fP parameters\.
Environment variables can be replaced using \fB${VARIABLE_NAME}\fP\|\. For
example:
.P
.RS 2
.nf
@@ -35,12 +36,11 @@ prefix = ${HOME}/\.npm\-packages
.fi
.RE
.P
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\.
.P
Array values are specified by adding "[]" after the key name\. For
example:
Array values are specified by adding "[]" after the key name\. For example:
.P
.RS 2
.nf
@@ -50,7 +50,9 @@ key[] = "second value"
.RE
.SS Comments
.P
Lines in \fB\|\.npmrc\fP files are interpreted as comments when they begin with a \fB;\fP or \fB#\fP character\. \fB\|\.npmrc\fP files are parsed by npm/ini \fIhttps://github\.com/npm/ini\fR, which specifies this comment syntax\.
Lines in \fB\|\.npmrc\fP files are interpreted as comments when they begin with a
\fB;\fP or \fB#\fP character\. \fB\|\.npmrc\fP files are parsed by
npm/ini \fIhttps://github\.com/npm/ini\fR, which specifies this comment syntax\.
.P
For example:
.P
@@ -67,31 +69,30 @@ When working locally in a project, a \fB\|\.npmrc\fP file in the root of the
project (ie, a sibling of \fBnode_modules\fP and \fBpackage\.json\fP) will set
config values specific to this project\.
.P
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\.
.P
Additionally, this file is not read in global mode, such as when running
\fBnpm install \-g\fP\|\.
.SS Per\-user config file
.P
\fB$HOME/\.npmrc\fP (or the \fBuserconfig\fP param, if set in the environment
or on the command line)
\fB$HOME/\.npmrc\fP (or the \fBuserconfig\fP param, if set in the environment or on
the command line)
.SS Global config file
.P
\fB$PREFIX/etc/npmrc\fP (or the \fBglobalconfig\fP param, if set above):
This file is an ini\-file formatted list of \fBkey = value\fP parameters\.
Environment variables can be replaced as above\.
\fB$PREFIX/etc/npmrc\fP (or the \fBglobalconfig\fP param, if set above): This file
is an ini\-file formatted list of \fBkey = value\fP parameters\. Environment
variables can be replaced as above\.
.SS Built\-in config file
.P
\fBpath/to/npm/itself/npmrc\fP
.P
This is an unchangeable "builtin" configuration file that npm keeps
consistent across updates\. Set fields in here using the \fB\|\./configure\fP
script that comes with npm\. This is primarily for distribution
maintainers to override default configs in a standard and consistent
manner\.
script that comes with npm\. This is primarily for distribution maintainers
to override default configs in a standard and consistent manner\.
.SS See also
.RS 0
.IP \(bu 2
deps/npm/man/man5/package-json.5
Vendored
+406 -329
View File
File diff suppressed because it is too large. Load diff
deps/npm/man/man5/package-lock-json.5
Vendored
+203 -98
View File
@@ -12,138 +12,243 @@ This file is intended to be committed into source repositories, and serves
various purposes:
.RS 0
.IP \(bu 2
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\.
.IP \(bu 2
Provide a facility for users to "time\-travel" to previous states of \fBnode_modules\fP without having to commit the directory itself\.
Provide a facility for users to "time\-travel" to previous states of
\fBnode_modules\fP without having to commit the directory itself\.
.IP \(bu 2
To facilitate greater visibility of tree changes through readable source control diffs\.
Facilitate greater visibility of tree changes through readable source
control diffs\.
.IP \(bu 2
And 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\.
.IP \(bu 2
As of npm v7, lockfiles include enough information to gain a complete
picture of the package tree, reducing the need to read \fBpackage\.json\fP
files, and allowing for significant performance improvements\.
.RE
.SS \fBpackage\-lock\.json\fP vs \fBnpm\-shrinkwrap\.json\fP
.P
Both of these files have the same format, and perform similar functions in
the root of a project\.
.P
The difference is that \fBpackage\-lock\.json\fP is that it cannot be published,
and it will be ignored if found in any place other than the root project\.
.P
In contrast, npm help 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\.
.P
If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in the
root of a project, \fBnpm\-shrinkwrap\.json\fP will take precedence and
\fBpackage\-lock\.json\fP will be ignored\.
.SS Hidden Lockfiles
.P
In order to avoid processing the \fBnode_modules\fP folder repeatedly, npm as
of v7 uses a "hidden" lockfile present in
\fBnode_modules/\.package\-lock\.json\fP\|\. This contains information about the
tree, and is used in lieu of reading the entire \fBnode_modules\fP hierarchy
provided that the following conditions are met:
.RS 0
.IP \(bu 2
All package folders it references exist in the \fBnode_modules\fP hierarchy\.
.IP \(bu 2
No package folders exist in the \fBnode_modules\fP hierarchy that are not
listed in the lockfile\.
.IP \(bu 2
The modified time of the file is at least as recent as all of the package
folders it references\.
.RE
.P
One key detail about \fBpackage\-lock\.json\fP is that it cannot be published, and it
will be ignored if found in any place other than the toplevel package\. It shares
a format with npm help npm\-shrinkwrap\.json, which is essentially the same file, but
allows publication\. This is not recommended unless deploying a CLI tool or
otherwise using the publication process for producing production packages\.
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\.
.P
If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in the root of
a package, \fBpackage\-lock\.json\fP will be completely ignored\.
Note that it \fIis\fR possible to manually change the \fIcontents\fR 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 \fBnode_modules/foo/lib/bar\.js\fP, then the
modified time on \fBnode_modules/foo\fP will not reflect this change\. If you
are manually editing files in \fBnode_modules\fP, it is generally best to
delete the file at \fBnode_modules/\.package\-lock\.json\fP\|\.
.P
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 \fBlockfileVersion: 3\fP, rather than
\fBlockfileVersion: 2\fP\|\.
.SS Handling Old Lockfiles
.P
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 \fBnode_modules\fP tree or (in the case of empty
\fBnode_modules\fP trees or very old lockfile formats) the npm registry\.
.SS File Format
.SS name
.SS \fBname\fP
.P
The name of the package this is a package\-lock for\. This must match what's in
\fBpackage\.json\fP\|\.
.SS version
The name of the package this is a package\-lock for\. This will match what's
in \fBpackage\.json\fP\|\.
.SS \fBversion\fP
.P
The version of the package this is a package\-lock for\. This must match what's in
\fBpackage\.json\fP\|\.
.SS lockfileVersion
The version of the package this is a package\-lock for\. This will match
what's in \fBpackage\.json\fP\|\.
.SS \fBlockfileVersion\fP
.P
An integer version, starting at \fB1\fP with the version number of this document
whose semantics were used when generating this \fBpackage\-lock\.json\fP\|\.
.SS packageIntegrity
An integer version, starting at \fB1\fP with the version number of this
document whose semantics were used when generating this
\fBpackage\-lock\.json\fP\|\.
.P
This is a subresource
integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR value
created from the \fBpackage\.json\fP\|\. No preprocessing of the \fBpackage\.json\fP should
be done\. Subresource integrity strings can be produced by modules like
\fBssri\fP \fIhttps://www\.npmjs\.com/package/ssri\fR\|\.
.SS preserveSymlinks
.P
Indicates that the install was done with the environment variable
\fBNODE_PRESERVE_SYMLINKS\fP enabled\. The installer should insist that the value of
this property match that environment variable\.
.SS dependencies
.P
A mapping of package name to dependency object\. Dependency objects have the
following properties:
.SS version
.P
This is a specifier that uniquely identifies this package and should be
usable in fetching a new copy of it\.
Note that the file format changed significantly in npm v7 to track
information that would have otherwise required looking in \fBnode_modules\fP or
the npm registry\. Lockfiles generated by npm v7 will contain
\fBlockfileVersion: 2\fP\|\.
.RS 0
.IP \(bu 2
bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes\.
No version provided: an "ancient" shrinkwrap file from a version of npm
prior to npm v5\.
.IP \(bu 2
\fB1\fP: The lockfile version used by npm v5 and v6\.
.IP \(bu 2
\fB2\fP: The lockfile version used by npm v7, which is backwards compatible
to v1 lockfiles\.
.IP \(bu 2
\fB3\fP: The lockfile version used by npm v7, \fIwithout\fR backwards
compatibility affordances\. This is used for the hidden lockfile at
\fBnode_modules/\.package\-lock\.json\fP, and will likely be used in a future
version of npm, once support for npm v6 is no longer relevant\.
.RE
.P
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\.
.SS \fBpackages\fP
.P
This is an object that maps package locations to an object containing the
information about that package\.
.P
The root project is typically listed with a key of \fB""\fP, and all other
packages are listed with their relative paths from the root project folder\.
.P
Package descriptors have the following fields:
.RS 0
.IP \(bu 2
version: The version found in \fBpackage\.json\fP
.IP \(bu 2
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\.
.IP \(bu 2
integrity: A \fBsha512\fP or \fBsha1\fP Standard Subresource
Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR
string for the artifact that was unpacked in this location\.
.IP \(bu 2
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\.
.IP \(bu 2
dev, optional, devOptional: If the package is strictly part of the
\fBdevDependencies\fP tree, then \fBdev\fP will be true\. If it is strictly part
of the \fBoptionalDependencies\fP tree, then \fBoptional\fP will be set\. If it
is both a \fBdev\fP dependency \fIand\fR an \fBoptional\fP dependency of a non\-dev
dependency, then \fBdevOptional\fP will be set\. (An \fBoptional\fP dependency of
a \fBdev\fP dependency will have both \fBdev\fP and \fBoptional\fP set\.)
.IP \(bu 2
inBundle: A flag to indicate that the package is a bundled dependency\.
.IP \(bu 2
hasInstallScript: A flag to indicate that the package has a \fBpreinstall\fP,
\fBinstall\fP, or \fBpostinstall\fP script\.
.IP \(bu 2
hasShrinkwrap: A flag to indicate that the package has an
\fBnpm\-shrinkwrap\.json\fP file\.
.IP \(bu 2
bin, license, engines, dependencies, optionalDependencies: fields from
\fBpackage\.json\fP
.RE
.SS dependencies
.P
Legacy data for supporting versions of npm that use \fBlockfileVersion: 1\fP\|\.
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\.
.P
npm v7 ignores this section entirely if a \fBpackages\fP section is present,
but does keep it up to date in order to support switching between npm v6
and npm v7\.
.P
Dependency objects have the following fields:
.RS 0
.IP \(bu 2
version: a specifier that varies depending on the nature of the package,
and is usable in fetching a new copy of it\.
.RS
.IP \(bu 2
bundled dependencies: Regardless of source, this is a version number
that is purely for informational purposes\.
.IP \(bu 2
registry sources: This is a version number\. (eg, \fB1\.2\.3\fP)
.IP \(bu 2
git sources: This is a git specifier with resolved committish\. (eg, \fBgit+https://example\.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e\fP)
git sources: This is a git specifier with resolved committish\. (eg,
\fBgit+https://example\.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e\fP)
.IP \(bu 2
http tarball sources: This is the URL of the tarball\. (eg, \fBhttps://example\.com/example\-1\.3\.0\.tgz\fP)
http tarball sources: This is the URL of the tarball\. (eg,
\fBhttps://example\.com/example\-1\.3\.0\.tgz\fP)
.IP \(bu 2
local tarball sources: This is the file URL of the tarball\. (eg \fBfile:///opt/storage/example\-1\.3\.0\.tgz\fP)
local tarball sources: This is the file URL of the tarball\. (eg
\fBfile:///opt/storage/example\-1\.3\.0\.tgz\fP)
.IP \(bu 2
local link sources: This is the file URL of the link\. (eg \fBfile:libs/our\-module\fP)
local link sources: This is the file URL of the link\. (eg
\fBfile:libs/our\-module\fP)
.RE
.SS integrity
.P
This is a Standard Subresource
Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR for this
resource\.
.RS 0
.IP \(bu 2
For bundled dependencies this is not included, regardless of source\.
integrity: A \fBsha512\fP or \fBsha1\fP Standard Subresource
Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR
string for the artifact that was unpacked in this location\. For git
dependencies, this is the commit sha\.
.IP \(bu 2
For registry sources, this is the \fBintegrity\fP that the registry provided, or if one wasn't provided the SHA1 in \fBshasum\fP\|\.
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\.
.IP \(bu 2
For git sources this is the specific commit hash we cloned from\.
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\.
.IP \(bu 2
For remote tarball sources this is an integrity based on a SHA512 of
the file\.
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\.
.IP \(bu 2
For local tarball sources: This is an integrity field based on the SHA512 of the file\.
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\.
.IP \(bu 2
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 \fBdependencies\fP or in a level higher than us\.
.IP \(bu 2
dependencies: The dependencies of this dependency, exactly as at the top
level\.
.RE
.SS resolved
.RS 0
.IP \(bu 2
For bundled dependencies this is not included, regardless of source\.
.IP \(bu 2
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\.
.RE
.SS bundled
.P
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\.
.SS dev
.P
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\.
.SS optional
.P
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\.
.P
All optional dependencies should be included even if they're uninstallable
on the current platform\.
.SS requires
.P
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
\fBdependencies\fP or in a level higher than us\.
.SS dependencies
.P
The dependencies of this dependency, exactly as at the top level\.
.SS See also
.RS 0
.IP \(bu 2
npm help shrinkwrap
.IP \(bu 2
npm help shrinkwrap\.json
.IP \(bu 2
npm help package\-locks
npm help npm\-shrinkwrap\.json
.IP \(bu 2
npm help package\.json
.IP \(bu 2
deps/npm/man/man5/package-locks.5
Vendored
-200
View File
@@ -1,200 +0,0 @@
.TH "PACKAGE\-LOCKS" "5" "January 2021" "" ""
.SH "NAME"
\fBpackage-locks\fR \- An explanation of npm lockfiles
.SS Description
.P
Conceptually, the "input" to npm help \fBinstall\fP is a npm help package\.json, while its
"output" is a fully\-formed \fBnode_modules\fP tree: a representation of the
dependencies you declared\. In an ideal world, npm would work like a pure
function: the same \fBpackage\.json\fP should produce the exact same \fBnode_modules\fP
tree, any time\. In some cases, this is indeed true\. But in many others, npm is
unable to do this\. There are multiple reasons for this:
.RS 0
.IP \(bu 2
different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms\.
.IP \(bu 2
a new version of a direct semver\-range package may have been published since the last time your packages were installed, and thus a newer version will be used\.
.IP \(bu 2
A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (\fB1\.2\.3\fP instead of \fB^1\.2\.3\fP)
.IP \(bu 2
The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now\.
.RE
.P
As an example, consider package A:
.P
.RS 2
.nf
{
"name": "A",
"version": "0\.1\.0",
"dependencies": {
"B": "<0\.1\.0"
}
}
.fi
.RE
.P
package B:
.P
.RS 2
.nf
{
"name": "B",
"version": "0\.0\.1",
"dependencies": {
"C": "<0\.1\.0"
}
}
.fi
.RE
.P
and package C:
.P
.RS 2
.nf
{
"name": "C",
"version": "0\.0\.1"
}
.fi
.RE
.P
If these are the only versions of A, B, and C available in the
registry, then a normal \fBnpm install A\fP will install:
.P
.RS 2
.nf
A@0\.1\.0
`\-\- B@0\.0\.1
`\-\- C@0\.0\.1
.fi
.RE
.P
However, if B@0\.0\.2 is published, then a fresh \fBnpm install A\fP will
install:
.P
.RS 2
.nf
A@0\.1\.0
`\-\- B@0\.0\.2
`\-\- C@0\.0\.1
.fi
.RE
.P
assuming the new version did not modify B's dependencies\. Of course,
the new version of B could include a new version of C and any number
of new dependencies\. If such changes are undesirable, the author of A
could specify a dependency on B@0\.0\.1\|\. However, if A's author and B's
author are not the same person, there's no way for A's author to say
that he or she does not want to pull in newly published versions of C
when B hasn't changed at all\.
.P
To prevent this potential issue, npm uses npm help package\-lock\.json or, if present, npm help npm\-shrinkwrap\.json\. These files are called package locks, or lockfiles\.
.P
Whenever you run \fBnpm install\fP, npm generates or updates your package lock,
which will look something like this:
.P
.RS 2
.nf
{
"name": "A",
"version": "0\.1\.0",
\.\.\.metadata fields\.\.\.
"dependencies": {
"B": {
"version": "0\.0\.1",
"resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz",
"integrity": "sha512\-DeAdb33F+"
"dependencies": {
"C": {
"version": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
}
}
}
}
}
.fi
.RE
.P
This file describes an \fIexact\fR, and more importantly \fIreproducible\fR
\fBnode_modules\fP tree\. Once it's present, any future installation will base its
work off this file, instead of recalculating dependency versions off
npm help package\.json\.
.P
The presence of a package lock changes the installation behavior such that:
.RS 0
.IP 1. 3
The module tree described by the package lock is reproduced\. This means
reproducing the structure described in the file, using the specific files
referenced in "resolved" if available, falling back to normal package resolution
using "version" if one isn't\.
.IP 2. 3
The tree is walked and any missing dependencies are installed in the usual
fashion\.
.RE
.P
If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP
property of the \fBpackage\.json\fP, they will be executed in order\. \fBpreshrinkwrap\fP
and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is
executed afterwards\. These scripts run for both \fBpackage\-lock\.json\fP and
\fBnpm\-shrinkwrap\.json\fP\|\. For example to run some postprocessing on the generated
file:
.P
.RS 2
.nf
"scripts": {
"postshrinkwrap": "json \-I \-e \\"this\.myMetadata = $MY_APP_METADATA\\""
}
.fi
.RE
.SS Using locked packages
.P
Using a locked package is no different than using any package without a package
lock: any commands that update \fBnode_modules\fP and/or \fBpackage\.json\fP\|'s
dependencies will automatically sync the existing lockfile\. This includes \fBnpm
install\fP, \fBnpm rm\fP, \fBnpm update\fP, etc\. To prevent this update from happening,
you can use the \fB\-\-no\-save\fP option to prevent saving altogether, or
\fB\-\-no\-shrinkwrap\fP to allow \fBpackage\.json\fP to be updated while leaving
\fBpackage\-lock\.json\fP or \fBnpm\-shrinkwrap\.json\fP intact\.
.P
It is highly recommended you commit the generated package lock to source
control: this will allow anyone else on your team, your deployments, your
CI/continuous integration, and anyone else who runs \fBnpm install\fP in your
package source to get the exact same dependency tree that you were developing
on\. Additionally, the diffs from these changes are human\-readable and will
inform you of any changes npm has made to your \fBnode_modules\fP, so you can notice
if any transitive dependencies were updated, hoisted, etc\.
.SS Resolving lockfile conflicts
.P
Occasionally, two separate npm install will create package locks that cause
merge conflicts in source control systems\. As of \fBnpm@5\.7\.0\fP, these conflicts
can be resolved by manually fixing any \fBpackage\.json\fP conflicts, and then
running \fBnpm install [\-\-package\-lock\-only]\fP again\. npm will automatically
resolve any conflicts for you and write a merged package lock that includes all
the dependencies from both branches in a reasonable tree\. If
\fB\-\-package\-lock\-only\fP is provided, it will do this without also modifying your
local \fBnode_modules/\fP\|\.
.P
To make this process seamless on git, consider installing
\fBnpm\-merge\-driver\fP \fIhttps://npm\.im/npm\-merge\-driver\fR, which will teach git how
to do this itself without any user interaction\. In short: \fB$ npx
npm\-merge\-driver install \-g\fP will let you do this, and even works with
pre\-\fBnpm@5\.7\.0\fP versions of npm 5, albeit a bit more noisily\. Note that if
\fBpackage\.json\fP itself conflicts, you will have to resolve that by hand and run
\fBnpm install\fP manually, even with the merge driver\.
.SS See Also
.RS 0
.IP \(bu 2
https://medium\.com/@sdboyer/so\-you\-want\-to\-write\-a\-package\-manager\-4ae9c17d9527
.IP \(bu 2
npm help package\.json
.IP \(bu 2
npm help package\-lock\.json
.IP \(bu 2
npm help shrinkwrap\.json
.IP \(bu 2
npm help shrinkwrap
.RE
deps/npm/node_modules/@npmcli/arborist/lib/arborist/index.js
Generated Vendored
+1
View File
@@ -53,6 +53,7 @@ class Arborist extends Base {
...options,
path: options.path || '.',
cache: options.cache || `${homedir()}/.npm/_cacache`,
packumentCache: new Map(),
}
this.cache = resolve(this.options.cache)
this.path = resolve(this.options.path)
deps/npm/node_modules/@npmcli/arborist/lib/arborist/load-actual.js
Generated Vendored
+13 -2
View File
@@ -111,7 +111,7 @@ module.exports = cls => class ActualLoader extends cls {
pkg: {},
global,
})
return this[_loadActualActually]({root, ignoreMissing})
return this[_loadActualActually]({root, ignoreMissing, global})
}
// not in global mode, hidden lockfile is allowed, load root pkg too
@@ -154,7 +154,7 @@ module.exports = cls => class ActualLoader extends cls {
return this[_actualTree]
}
async [_loadActualActually] ({ root, ignoreMissing }) {
async [_loadActualActually] ({ root, ignoreMissing, global }) {
await this[_loadFSTree](this[_actualTree])
if (!ignoreMissing)
await this[_findMissingEdges]()
@@ -162,6 +162,17 @@ module.exports = cls => class ActualLoader extends cls {
this[_transplant](root)
await this[_loadWorkspaces](this[_actualTree])
if (global) {
// need to depend on the children, or else all of them
// will end up being flagged as extraneous, since the
// global root isn't a "real" project
const tree = this[_actualTree]
const actualRoot = tree.isLink ? tree.target : tree
const { dependencies = {} } = actualRoot.package
for (const name of actualRoot.children.keys())
dependencies[name] = dependencies[name] || '*'
actualRoot.package = { ...actualRoot.package, dependencies }
}
// only reset root flags if we're not re-rooting, otherwise leave as-is
calcDepFlags(this[_actualTree], !root)
return this[_actualTree]
deps/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js
Generated Vendored
+1 -1
View File
@@ -136,7 +136,7 @@ module.exports = cls => class Reifier extends cls {
async [_validatePath] () {
// don't create missing dirs on dry runs
if (this[_packageLockOnly] || this[_dryRun] || this[_global])
if (this[_packageLockOnly] || this[_dryRun])
return
await mkdirp(resolve(this.path))
deps/npm/node_modules/@npmcli/arborist/lib/diff.js
Generated Vendored
+5
View File
@@ -72,6 +72,11 @@ const allChildren = node => {
if (!node)
return new Map()
// if the node is a global root, and also a link, then what we really
// want is to traverse the target's children
if (node.global && node.isRoot && node.isLink)
return allChildren(node.target)
const kids = new Map()
for (const n of [node, ...node.fsChildren]) {
for (const kid of n.children.values())
deps/npm/node_modules/@npmcli/arborist/lib/edge.js
Generated Vendored
+24
View File
@@ -1,6 +1,7 @@
// An edge in the dependency graph
// Represents a dependency relationship of some kind
const util = require('util')
const npa = require('npm-package-arg')
const depValid = require('./dep-valid.js')
const _from = Symbol('_from')
@@ -24,6 +25,21 @@ const types = new Set([
'workspace',
])
class ArboristEdge {}
const printableEdge = (edge) => {
const edgeFrom = edge.from && edge.from.location
const edgeTo = edge.to && edge.to.location
return Object.assign(new ArboristEdge(), {
name: edge.name,
spec: edge.spec,
type: edge.type,
...(edgeFrom != null ? { from: edgeFrom } : {}),
...(edgeTo ? { to: edgeTo } : {}),
...(edge.error ? { error: edge.error } : {}),
})
}
class Edge {
constructor (options) {
const { type, name, spec, accept, from } = options
@@ -185,6 +201,14 @@ class Edge {
get to () {
return this[_to]
}
toJSON () {
return printableEdge(this)
}
[util.inspect.custom] () {
return this.toJSON()
}
}
Edge.types = [...types]
deps/npm/node_modules/@npmcli/arborist/lib/index.js
Generated Vendored
+1
View File
@@ -2,5 +2,6 @@ module.exports = require('./arborist/index.js')
module.exports.Arborist = module.exports
module.exports.Node = require('./node.js')
module.exports.Link = require('./link.js')
module.exports.Edge = require('./edge.js')
// XXX export the other classes, too. shrinkwrap, diff, etc.
// they're handy!
deps/npm/node_modules/@npmcli/arborist/lib/node.js
Generated Vendored
+74
View File
@@ -40,6 +40,7 @@ const treeCheck = require('./tree-check.js')
const walkUp = require('walk-up-path')
const {resolve, relative, dirname, basename} = require('path')
const util = require('util')
const _package = Symbol('_package')
const _parent = Symbol('_parent')
const _target = Symbol.for('_target')
@@ -63,6 +64,71 @@ const _meta = Symbol('_meta')
const relpath = require('./relpath.js')
const consistentResolve = require('./consistent-resolve.js')
// helper function to output a clearer visualization
// of the current node and its descendents
class ArboristNode {}
const printableTree = (tree, path = []) =>
(path.includes(tree) ? { location: tree.location } : (path.push(tree), Object.assign(new ArboristNode(), {
name: tree.name,
...(tree.package && tree.package.version
? { version: tree.package.version }
: {}),
location: tree.location,
path: tree.path,
realpath: tree.realpath,
...(tree.isLink ? { target: printableTree(tree.target, path) } : {}),
...(tree.resolved != null ? { resolved: tree.resolved } : {}),
...(tree.extraneous ? { extraneous: true } : {
...(tree.dev ? { dev: true } : {}),
...(tree.optional ? { optional: true } : {}),
...(tree.devOptional && !tree.dev && !tree.optional
? { devOptional: true } : {}),
...(tree.peer ? { peer: true } : {}),
}),
...(tree.inBundle ? { bundled: true } : {}),
// handle top-level tree error
...(tree.error
? {
error: {
code: tree.error.code,
...(tree.error.path
? { path: tree.error.path }
: {}),
},
} : {}),
// handle errors for each node
...(tree.errors && tree.errors.length
? {
errors: tree.errors.map(error => ({
code: error.code,
...(error.path
? { path: error.path }
: {}),
})),
} : {}),
...(tree.edgesIn && tree.edgesIn.size ? {
edgesIn: new Set([...tree.edgesIn]
.sort((a, b) => a.from.location.localeCompare(b.from.location))),
} : {}),
...(tree.edgesOut && tree.edgesOut.size ? {
edgesOut: new Map([...tree.edgesOut.entries()]
.sort((a, b) => a[0].localeCompare(b[0]))),
} : {}),
...(tree.fsChildren && tree.fsChildren.size ? {
fsChildren: new Set([...tree.fsChildren]
.sort((a, b) => a.path.localeCompare(b.path))
.map(tree => printableTree(tree, path))),
} : {}),
...(tree.target || !tree.children || !tree.children.size
? {}
: {
children: new Map([...tree.children.entries()]
.sort((a, b) => a[0].localeCompare(b[0]))
.map(([name, tree]) => [name, printableTree(tree, path)])),
}),
})))
class Node {
constructor (options) {
// NB: path can be null if it's a link target
@@ -1145,6 +1211,14 @@ class Node {
const base = scoped ? `${basename(d)}/${basename(rp)}` : basename(rp)
return base === name && basename(nm) === 'node_modules' ? dir : false
}
toJSON () {
return printableTree(this)
}
[util.inspect.custom] () {
return this.toJSON()
}
}
module.exports = Node
deps/npm/node_modules/@npmcli/arborist/lib/shrinkwrap.js
Generated Vendored
+4 -4
View File
@@ -200,9 +200,9 @@ class Shrinkwrap {
return s[_maybeStat]().then(([sw, lock]) => {
s.filename = resolve(s.path,
(s.hiddenLockfile ? 'node_modules/.package-lock'
: s.shrinkwrapOnly || sw && !lock ? 'npm-shrinkwrap'
: s.shrinkwrapOnly || sw ? 'npm-shrinkwrap'
: 'package-lock') + '.json')
s.loadedFromDisk = sw || lock
s.loadedFromDisk = !!(sw || lock)
s.type = basename(s.filename)
return s
})
@@ -353,14 +353,14 @@ class Shrinkwrap {
// we don't need to load package-lock.json except for top of tree nodes,
// only npm-shrinkwrap.json.
return this[_maybeRead]().then(([sw, lock, yarn]) => {
const data = lock || sw || ''
const data = sw || lock || ''
// use shrinkwrap only for deps, otherwise prefer package-lock
// and ignore npm-shrinkwrap if both are present.
// TODO: emit a warning here or something if both are present.
this.filename = resolve(this.path,
(this.hiddenLockfile ? 'node_modules/.package-lock'
: this.shrinkwrapOnly || sw && !lock ? 'npm-shrinkwrap'
: this.shrinkwrapOnly || sw ? 'npm-shrinkwrap'
: 'package-lock') + '.json')
this.type = basename(this.filename)
deps/npm/node_modules/@npmcli/arborist/package.json
Generated Vendored
+5 -4
View File
@@ -1,12 +1,12 @@
{
"name": "@npmcli/arborist",
"version": "2.0.3",
"version": "2.0.5",
"description": "Manage node_modules trees",
"dependencies": {
"@npmcli/installed-package-contents": "^1.0.5",
"@npmcli/map-workspaces": "^1.0.1",
"@npmcli/metavuln-calculator": "^1.0.0",
"@npmcli/move-file": "^1.0.1",
"@npmcli/metavuln-calculator": "^1.0.1",
"@npmcli/move-file": "^1.1.0",
"@npmcli/name-from-folder": "^1.0.1",
"@npmcli/node-gyp": "^1.0.1",
"@npmcli/run-script": "^1.8.1",
@@ -19,7 +19,8 @@
"npm-install-checks": "^4.0.0",
"npm-package-arg": "^8.1.0",
"npm-pick-manifest": "^6.1.0",
"pacote": "^11.1.14",
"npm-registry-fetch": "^9.0.0",
"pacote": "^11.2.1",
"parse-conflict-json": "^1.1.1",
"promise-all-reject-late": "^1.0.0",
"promise-call-limit": "^1.0.1",
deps/npm/node_modules/@npmcli/metavuln-calculator/lib/advisory.js
Generated Vendored
+120 -11
View File
@@ -65,7 +65,7 @@ class Advisory {
// load up the data from a cache entry and a fetched packument
load (cached, packument) {
// basic data integrity gutchecks
// basic data integrity gutcheck
if (!cached || typeof cached !== 'object') {
throw new TypeError('invalid cached data, expected object')
}
@@ -148,7 +148,42 @@ class Advisory {
}
[_calculateRange] () {
const metavuln = this.vulnerableVersions.join(' || ').trim()
// calling semver.simplifyRange with a massive list of versions, and those
// versions all concatenated with `||` is a geometric CPU explosion!
// we can try to be a *little* smarter up front by doing x-y for all
// contiguous version sets in the list
const ranges = []
this.versions = semver.sort(this.versions)
this.vulnerableVersions = semver.sort(this.vulnerableVersions)
for (let v = 0, vulnVer = 0; v < this.versions.length; v++) {
// figure out the vulnerable subrange
const vr = [this.versions[v]]
while (v < this.versions.length) {
if (this.versions[v] !== this.vulnerableVersions[vulnVer]) {
// we don't test prerelease versions, so just skip past it
if (/-/.test(this.versions[v])) {
v++
continue
}
break
}
if (vr.length > 1)
vr[1] = this.versions[v]
else
vr.push(this.versions[v])
v++
vulnVer++
}
// it'll either be just the first version, which means no overlap,
// or the start and end versions, which might be the same version
if (vr.length > 1) {
const tail = this.versions[this.versions.length - 1]
ranges.push(vr[1] === tail ? `>=${vr[0]}`
: vr[0] === vr[1] ? vr[0]
: vr.join(' - '))
}
}
const metavuln = ranges.join(' || ').trim()
this.range = !metavuln ? '<0.0.0-0'
: semver.simplifyRange(this.versions, metavuln, semverOpt)
}
@@ -271,25 +306,99 @@ class Advisory {
}
for (const list of versionSets) {
const headVuln = this.testVersion(list[0])
const tailVuln = this.testVersion(list[list.length - 1])
// it's common to have version lists like:
// 1.0.0
// 1.0.1-alpha.0
// 1.0.1-alpha.1
// ...
// 1.0.1-alpha.999
// 1.0.1
// 1.0.2-alpha.0
// ...
// 1.0.2-alpha.99
// 1.0.2
// with a huge number of prerelease versions that are not installable
// anyway.
// If mid has a prerelease tag, and list[0] does not, then walk it
// back until we hit a non-prerelease version
// If mid has a prerelease tag, and list[list.length-1] does not,
// then walk it forward until we hit a version without a prerelease tag
// Similarly, if the head/tail is a prerelease, but there is a non-pr
// version in the list, then start there instead.
let h = 0
const origHeadVuln = this.testVersion(list[h])
while (h < list.length && /-/.test(String(list[h])))
h++
// don't filter out the whole list! they might all be pr's
if (h === list.length)
h = 0
else if (origHeadVuln) {
// if the original was vulnerable, assume so are all of these
for (let hh = 0; hh < h; hh++)
this[_markVulnerable](list[hh])
}
let t = list.length - 1
const origTailVuln = this.testVersion(list[t])
while (t > h && /-/.test(String(list[t])))
t--
// don't filter out the whole list! might all be pr's
if (t === h)
t = list.length - 1
else if (origTailVuln) {
// if original tail was vulnerable, assume these are as well
for (let tt = list.length - 1; tt > t; tt--)
this[_markVulnerable](list[tt])
}
const headVuln = h === 0 ? origHeadVuln
: this.testVersion(list[h])
const tailVuln = t === list.length - 1 ? origTailVuln
: this.testVersion(list[t])
// if head and tail both vulnerable, whole list is thrown out
if (headVuln && tailVuln) {
for (const v of list.slice(1, -1)) {
this[_markVulnerable](v)
}
for (let v = h; v < t; v++)
this[_markVulnerable](list[v])
continue
}
// if length is 2 or 1, then we marked them all already
if (list.length <= 2)
if (t < h + 2)
continue
const mid = Math.floor(list.length / 2)
// leave out the ends, since we tested those already
versionSets.add(list.slice(0, mid))
versionSets.add(list.slice(mid))
const pre = list.slice(0, mid)
const post = list.slice(mid)
// if the parent list wasn't prereleases, then drop pr tags
// from end of the pre list, and beginning of the post list,
// marking as vulnerable if the midpoint item we picked is.
if (!/-/.test(String(pre[0]))) {
const midVuln = this.testVersion(pre[pre.length - 1])
while (/-/.test(String(pre[pre.length-1]))) {
const v = pre.pop()
if (midVuln)
this[_markVulnerable](v)
}
}
if (!/-/.test(String(post[post.length-1]))) {
const midVuln = this.testVersion(post[0])
while (/-/.test(String(post[0]))) {
const v = post.shift()
if (midVuln)
this[_markVulnerable](v)
}
}
versionSets.add(pre)
versionSets.add(post)
}
}
}
module.exports = Advisory
deps/npm/node_modules/@npmcli/metavuln-calculator/package.json
Generated Vendored
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@npmcli/metavuln-calculator",
"version": "1.0.0",
"version": "1.0.2",
"main": "lib/index.js",
"files": [
"lib"
deps/npm/node_modules/@npmcli/move-file/README.md
Generated Vendored
+5 -4
View File
@@ -3,7 +3,7 @@
A fork of [move-file](https://github.com/sindresorhus/move-file) with
compatibility with all node 10.x versions.
> Move a file
> Move a file (or directory)
The built-in
[`fs.rename()`](https://nodejs.org/api/fs.html#fs_fs_rename_oldpath_newpath_callback)
@@ -18,6 +18,7 @@ would have expected `fs.rename()` to be.
- Optionally prevent overwriting an existing file.
- Creates non-existent destination directories for you.
- Support for Node versions that lack built-in recursive `fs.mkdir()`
- Automatically recurses when source is a directory.
## Install
@@ -48,13 +49,13 @@ Returns a `Promise` that resolves when the file has been moved.
Type: `string`
File you want to move.
File, or directory, you want to move.
#### destination
Type: `string`
Where you want the file moved.
Where you want the file or directory moved.
#### options
@@ -65,4 +66,4 @@ Type: `object`
Type: `boolean`\
Default: `true`
Overwrite existing destination file.
Overwrite existing destination file(s).
deps/npm/node_modules/@npmcli/move-file/index.js
Generated Vendored
+76 -7
View File
@@ -1,4 +1,5 @@
const { dirname } = require('path')
const { dirname, join, resolve, relative, isAbsolute } = require('path')
const rimraf_ = require('rimraf')
const { promisify } = require('util')
const {
access: access_,
@@ -7,14 +8,31 @@ const {
copyFileSync,
unlink: unlink_,
unlinkSync,
readdir: readdir_,
readdirSync,
rename: rename_,
renameSync,
stat: stat_,
statSync,
lstat: lstat_,
lstatSync,
symlink: symlink_,
symlinkSync,
readlink: readlink_,
readlinkSync
} = require('fs')
const access = promisify(access_)
const copyFile = promisify(copyFile_)
const unlink = promisify(unlink_)
const readdir = promisify(readdir_)
const rename = promisify(rename_)
const stat = promisify(stat_)
const lstat = promisify(lstat_)
const symlink = promisify(symlink_)
const readlink = promisify(readlink_)
const rimraf = promisify(rimraf_)
const rimrafSync = rimraf_.sync
const mkdirp = require('mkdirp')
@@ -36,7 +54,7 @@ const pathExistsSync = path => {
}
}
module.exports = async (source, destination, options = {}) => {
const moveFile = async (source, destination, options = {}, root = true, symlinks = []) => {
if (!source || !destination) {
throw new TypeError('`source` and `destination` file required')
}
@@ -56,15 +74,38 @@ module.exports = async (source, destination, options = {}) => {
await rename(source, destination)
} catch (error) {
if (error.code === 'EXDEV') {
await copyFile(source, destination)
await unlink(source)
const sourceStat = await lstat(source)
if (sourceStat.isDirectory()) {
const files = await readdir(source)
await Promise.all(files.map((file) => moveFile(join(source, file), join(destination, file), options, false, symlinks)))
} else if (sourceStat.isSymbolicLink()) {
symlinks.push({ source, destination })
} else {
await copyFile(source, destination)
}
} else {
throw error
}
}
if (root) {
await Promise.all(symlinks.map(async ({ source, destination }) => {
let target = await readlink(source)
// junction symlinks in windows will be absolute paths, so we need to make sure they point to the destination
if (isAbsolute(target))
target = resolve(destination, relative(source, target))
// try to determine what the actual file is so we can create the correct type of symlink in windows
let targetStat
try {
targetStat = await stat(resolve(dirname(source), target))
} catch (err) {}
await symlink(target, destination, targetStat && targetStat.isDirectory() ? 'junction' : 'file')
}))
await rimraf(source)
}
}
module.exports.sync = (source, destination, options = {}) => {
const moveFileSync = (source, destination, options = {}, root = true, symlinks = []) => {
if (!source || !destination) {
throw new TypeError('`source` and `destination` file required')
}
@@ -84,10 +125,38 @@ module.exports.sync = (source, destination, options = {}) => {
renameSync(source, destination)
} catch (error) {
if (error.code === 'EXDEV') {
copyFileSync(source, destination)
unlinkSync(source)
const sourceStat = lstatSync(source)
if (sourceStat.isDirectory()) {
const files = readdirSync(source)
for (const file of files) {
moveFileSync(join(source, file), join(destination, file), options, false, symlinks)
}
} else if (sourceStat.isSymbolicLink()) {
symlinks.push({ source, destination })
} else {
copyFileSync(source, destination)
}
} else {
throw error
}
}
if (root) {
for (const { source, destination } of symlinks) {
let target = readlinkSync(source)
// junction symlinks in windows will be absolute paths, so we need to make sure they point to the destination
if (isAbsolute(target))
target = resolve(destination, relative(source, target))
// try to determine what the actual file is so we can create the correct type of symlink in windows
let targetStat
try {
targetStat = statSync(resolve(dirname(source), target))
} catch (err) {}
symlinkSync(target, destination, targetStat && targetStat.isDirectory() ? 'junction' : 'file')
}
rimrafSync(source)
}
}
module.exports = moveFile
module.exports.sync = moveFileSync
deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/LICENSE
Generated Vendored
+15
View File
@@ -0,0 +1,15 @@
The ISC License
Copyright (c) Isaac Z. Schlueter and Contributors
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/README.md
Generated Vendored
+101
View File
@@ -0,0 +1,101 @@
[![Build Status](https://travis-ci.org/isaacs/rimraf.svg?branch=master)](https://travis-ci.org/isaacs/rimraf) [![Dependency Status](https://david-dm.org/isaacs/rimraf.svg)](https://david-dm.org/isaacs/rimraf) [![devDependency Status](https://david-dm.org/isaacs/rimraf/dev-status.svg)](https://david-dm.org/isaacs/rimraf#info=devDependencies)
The [UNIX command](http://en.wikipedia.org/wiki/Rm_(Unix)) `rm -rf` for node.
Install with `npm install rimraf`, or just drop rimraf.js somewhere.
## API
`rimraf(f, [opts], callback)`
The first parameter will be interpreted as a globbing pattern for files. If you
want to disable globbing you can do so with `opts.disableGlob` (defaults to
`false`). This might be handy, for instance, if you have filenames that contain
globbing wildcard characters.
The callback will be called with an error if there is one. Certain
errors are handled for you:
* Windows: `EBUSY` and `ENOTEMPTY` - rimraf will back off a maximum of
`opts.maxBusyTries` times before giving up, adding 100ms of wait
between each attempt. The default `maxBusyTries` is 3.
* `ENOENT` - If the file doesn't exist, rimraf will return
successfully, since your desired outcome is already the case.
* `EMFILE` - Since `readdir` requires opening a file descriptor, it's
possible to hit `EMFILE` if too many file descriptors are in use.
In the sync case, there's nothing to be done for this. But in the
async case, rimraf will gradually back off with timeouts up to
`opts.emfileWait` ms, which defaults to 1000.
## options
* unlink, chmod, stat, lstat, rmdir, readdir,
unlinkSync, chmodSync, statSync, lstatSync, rmdirSync, readdirSync
In order to use a custom file system library, you can override
specific fs functions on the options object.
If any of these functions are present on the options object, then
the supplied function will be used instead of the default fs
method.
Sync methods are only relevant for `rimraf.sync()`, of course.
For example:
```javascript
var myCustomFS = require('some-custom-fs')
rimraf('some-thing', myCustomFS, callback)
```
* maxBusyTries
If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error code is encountered
on Windows systems, then rimraf will retry with a linear backoff
wait of 100ms longer on each try. The default maxBusyTries is 3.
Only relevant for async usage.
* emfileWait
If an `EMFILE` error is encountered, then rimraf will retry
repeatedly with a linear backoff of 1ms longer on each try, until
the timeout counter hits this max. The default limit is 1000.
If you repeatedly encounter `EMFILE` errors, then consider using
[graceful-fs](http://npm.im/graceful-fs) in your program.
Only relevant for async usage.
* glob
Set to `false` to disable [glob](http://npm.im/glob) pattern
matching.
Set to an object to pass options to the glob module. The default
glob options are `{ nosort: true, silent: true }`.
Glob version 6 is used in this module.
Relevant for both sync and async usage.
* disableGlob
Set to any non-falsey value to disable globbing entirely.
(Equivalent to setting `glob: false`.)
## rimraf.sync
It can remove stuff synchronously, too. But that's not so good. Use
the async API. It's better.
## CLI
If installed with `npm install rimraf -g` it can be used as a global
command `rimraf <path> [<path> ...]` which is useful for cross platform support.
## mkdirp
If you need to create a directory recursively, check out
[mkdirp](https://github.com/substack/node-mkdirp).
deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/bin.js
Generated Vendored Executable
+50
View File
@@ -0,0 +1,50 @@
#!/usr/bin/env node
var rimraf = require('./')
var help = false
var dashdash = false
var noglob = false
var args = process.argv.slice(2).filter(function(arg) {
if (dashdash)
return !!arg
else if (arg === '--')
dashdash = true
else if (arg === '--no-glob' || arg === '-G')
noglob = true
else if (arg === '--glob' || arg === '-g')
noglob = false
else if (arg.match(/^(-+|\/)(h(elp)?|\?)$/))
help = true
else
return !!arg
})
if (help || args.length === 0) {
// If they didn't ask for help, then this is not a "success"
var log = help ? console.log : console.error
log('Usage: rimraf <path> [<path> ...]')
log('')
log(' Deletes all files and folders at "path" recursively.')
log('')
log('Options:')
log('')
log(' -h, --help Display this usage info')
log(' -G, --no-glob Do not expand glob patterns in arguments')
log(' -g, --glob Expand glob patterns in arguments (default)')
process.exit(help ? 0 : 1)
} else
go(0)
function go (n) {
if (n >= args.length)
return
var options = {}
if (noglob)
options = { glob: false }
rimraf(args[n], options, function (er) {
if (er)
throw er
go(n+1)
})
}
deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/package.json
Generated Vendored
+29
View File
@@ -0,0 +1,29 @@
{
"name": "rimraf",
"version": "2.7.1",
"main": "rimraf.js",
"description": "A deep deletion module for node (like `rm -rf`)",
"author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me/)",
"license": "ISC",
"repository": "git://github.com/isaacs/rimraf.git",
"scripts": {
"preversion": "npm test",
"postversion": "npm publish",
"postpublish": "git push origin --all; git push origin --tags",
"test": "tap test/*.js"
},
"bin": "./bin.js",
"dependencies": {
"glob": "^7.1.3"
},
"files": [
"LICENSE",
"README.md",
"bin.js",
"rimraf.js"
],
"devDependencies": {
"mkdirp": "^0.5.1",
"tap": "^12.1.1"
}
}
deps/npm/node_modules/@npmcli/move-file/node_modules/rimraf/rimraf.js
Generated Vendored
+372
View File
@@ -0,0 +1,372 @@
module.exports = rimraf
rimraf.sync = rimrafSync
var assert = require("assert")
var path = require("path")
var fs = require("fs")
var glob = undefined
try {
glob = require("glob")
} catch (_err) {
// treat glob as optional.
}
var _0666 = parseInt('666', 8)
var defaultGlobOpts = {
nosort: true,
silent: true
}
// for EMFILE handling
var timeout = 0
var isWindows = (process.platform === "win32")
function defaults (options) {
var methods = [
'unlink',
'chmod',
'stat',
'lstat',
'rmdir',
'readdir'
]
methods.forEach(function(m) {
options[m] = options[m] || fs[m]
m = m + 'Sync'
options[m] = options[m] || fs[m]
})
options.maxBusyTries = options.maxBusyTries || 3
options.emfileWait = options.emfileWait || 1000
if (options.glob === false) {
options.disableGlob = true
}
if (options.disableGlob !== true && glob === undefined) {
throw Error('glob dependency not found, set `options.disableGlob = true` if intentional')
}
options.disableGlob = options.disableGlob || false
options.glob = options.glob || defaultGlobOpts
}
function rimraf (p, options, cb) {
if (typeof options === 'function') {
cb = options
options = {}
}
assert(p, 'rimraf: missing path')
assert.equal(typeof p, 'string', 'rimraf: path should be a string')
assert.equal(typeof cb, 'function', 'rimraf: callback function required')
assert(options, 'rimraf: invalid options argument provided')
assert.equal(typeof options, 'object', 'rimraf: options should be object')
defaults(options)
var busyTries = 0
var errState = null
var n = 0
if (options.disableGlob || !glob.hasMagic(p))
return afterGlob(null, [p])
options.lstat(p, function (er, stat) {
if (!er)
return afterGlob(null, [p])
glob(p, options.glob, afterGlob)
})
function next (er) {
errState = errState || er
if (--n === 0)
cb(errState)
}
function afterGlob (er, results) {
if (er)
return cb(er)
n = results.length
if (n === 0)
return cb()
results.forEach(function (p) {
rimraf_(p, options, function CB (er) {
if (er) {
if ((er.code === "EBUSY" || er.code === "ENOTEMPTY" || er.code === "EPERM") &&
busyTries < options.maxBusyTries) {
busyTries ++
var time = busyTries * 100
// try again, with the same exact callback as this one.
return setTimeout(function () {
rimraf_(p, options, CB)
}, time)
}
// this one won't happen if graceful-fs is used.
if (er.code === "EMFILE" && timeout < options.emfileWait) {
return setTimeout(function () {
rimraf_(p, options, CB)
}, timeout ++)
}
// already gone
if (er.code === "ENOENT") er = null
}
timeout = 0
next(er)
})
})
}
}
// Two possible strategies.
// 1. Assume it's a file. unlink it, then do the dir stuff on EPERM or EISDIR
// 2. Assume it's a directory. readdir, then do the file stuff on ENOTDIR
//
// Both result in an extra syscall when you guess wrong. However, there
// are likely far more normal files in the world than directories. This
// is based on the assumption that a the average number of files per
// directory is >= 1.
//
// If anyone ever complains about this, then I guess the strategy could
// be made configurable somehow. But until then, YAGNI.
function rimraf_ (p, options, cb) {
assert(p)
assert(options)
assert(typeof cb === 'function')
// sunos lets the root user unlink directories, which is... weird.
// so we have to lstat here and make sure it's not a dir.
options.lstat(p, function (er, st) {
if (er && er.code === "ENOENT")
return cb(null)
// Windows can EPERM on stat. Life is suffering.
if (er && er.code === "EPERM" && isWindows)
fixWinEPERM(p, options, er, cb)
if (st && st.isDirectory())
return rmdir(p, options, er, cb)
options.unlink(p, function (er) {
if (er) {
if (er.code === "ENOENT")
return cb(null)
if (er.code === "EPERM")
return (isWindows)
? fixWinEPERM(p, options, er, cb)
: rmdir(p, options, er, cb)
if (er.code === "EISDIR")
return rmdir(p, options, er, cb)
}
return cb(er)
})
})
}
function fixWinEPERM (p, options, er, cb) {
assert(p)
assert(options)
assert(typeof cb === 'function')
if (er)
assert(er instanceof Error)
options.chmod(p, _0666, function (er2) {
if (er2)
cb(er2.code === "ENOENT" ? null : er)
else
options.stat(p, function(er3, stats) {
if (er3)
cb(er3.code === "ENOENT" ? null : er)
else if (stats.isDirectory())
rmdir(p, options, er, cb)
else
options.unlink(p, cb)
})
})
}
function fixWinEPERMSync (p, options, er) {
assert(p)
assert(options)
if (er)
assert(er instanceof Error)
try {
options.chmodSync(p, _0666)
} catch (er2) {
if (er2.code === "ENOENT")
return
else
throw er
}
try {
var stats = options.statSync(p)
} catch (er3) {
if (er3.code === "ENOENT")
return
else
throw er
}
if (stats.isDirectory())
rmdirSync(p, options, er)
else
options.unlinkSync(p)
}
function rmdir (p, options, originalEr, cb) {
assert(p)
assert(options)
if (originalEr)
assert(originalEr instanceof Error)
assert(typeof cb === 'function')
// try to rmdir first, and only readdir on ENOTEMPTY or EEXIST (SunOS)
// if we guessed wrong, and it's not a directory, then
// raise the original error.
options.rmdir(p, function (er) {
if (er && (er.code === "ENOTEMPTY" || er.code === "EEXIST" || er.code === "EPERM"))
rmkids(p, options, cb)
else if (er && er.code === "ENOTDIR")
cb(originalEr)
else
cb(er)
})
}
function rmkids(p, options, cb) {
assert(p)
assert(options)
assert(typeof cb === 'function')
options.readdir(p, function (er, files) {
if (er)
return cb(er)
var n = files.length
if (n === 0)
return options.rmdir(p, cb)
var errState
files.forEach(function (f) {
rimraf(path.join(p, f), options, function (er) {
if (errState)
return
if (er)
return cb(errState = er)
if (--n === 0)
options.rmdir(p, cb)
})
})
})
}
// this looks simpler, and is strictly *faster*, but will
// tie up the JavaScript thread and fail on excessively
// deep directory trees.
function rimrafSync (p, options) {
options = options || {}
defaults(options)
assert(p, 'rimraf: missing path')
assert.equal(typeof p, 'string', 'rimraf: path should be a string')
assert(options, 'rimraf: missing options')
assert.equal(typeof options, 'object', 'rimraf: options should be object')
var results
if (options.disableGlob || !glob.hasMagic(p)) {
results = [p]
} else {
try {
options.lstatSync(p)
results = [p]
} catch (er) {
results = glob.sync(p, options.glob)
}
}
if (!results.length)
return
for (var i = 0; i < results.length; i++) {
var p = results[i]
try {
var st = options.lstatSync(p)
} catch (er) {
if (er.code === "ENOENT")
return
// Windows can EPERM on stat. Life is suffering.
if (er.code === "EPERM" && isWindows)
fixWinEPERMSync(p, options, er)
}
try {
// sunos lets the root user unlink directories, which is... weird.
if (st && st.isDirectory())
rmdirSync(p, options, null)
else
options.unlinkSync(p)
} catch (er) {
if (er.code === "ENOENT")
return
if (er.code === "EPERM")
return isWindows ? fixWinEPERMSync(p, options, er) : rmdirSync(p, options, er)
if (er.code !== "EISDIR")
throw er
rmdirSync(p, options, er)
}
}
}
function rmdirSync (p, options, originalEr) {
assert(p)
assert(options)
if (originalEr)
assert(originalEr instanceof Error)
try {
options.rmdirSync(p)
} catch (er) {
if (er.code === "ENOENT")
return
if (er.code === "ENOTDIR")
throw originalEr
if (er.code === "ENOTEMPTY" || er.code === "EEXIST" || er.code === "EPERM")
rmkidsSync(p, options)
}
}
function rmkidsSync (p, options) {
assert(p)
assert(options)
options.readdirSync(p).forEach(function (f) {
rimrafSync(path.join(p, f), options)
})
// We only end up here once we got ENOTEMPTY at least once, and
// at this point, we are guaranteed to have removed all the kids.
// So, we know that it won't be ENOENT or ENOTDIR or anything else.
// try really hard to delete stuff on windows, because it has a
// PROFOUNDLY annoying habit of not closing handles promptly when
// files are deleted, resulting in spurious ENOTEMPTY errors.
var retries = isWindows ? 100 : 1
var i = 0
do {
var threw = true
try {
var ret = options.rmdirSync(p, options)
threw = false
return ret
} finally {
if (++i < retries && threw)
continue
}
} while (true)
}
deps/npm/node_modules/@npmcli/move-file/package.json
Generated Vendored
+3 -2
View File
@@ -1,12 +1,13 @@
{
"name": "@npmcli/move-file",
"version": "1.0.1",
"version": "1.1.0",
"files": [
"index.js"
],
"description": "move a file (fork of move-file)",
"dependencies": {
"mkdirp": "^1.0.4"
"mkdirp": "^1.0.4",
"rimraf": "^2.7.1"
},
"devDependencies": {
"require-inject": "^1.4.4",
deps/npm/node_modules/make-fetch-happen/index.js
Generated Vendored
+4
View File
@@ -285,6 +285,10 @@ function remoteFetch (uri, opts) {
size: opts.size,
counter: opts.counter,
timeout: opts.timeout,
ca: opts.ca,
cert: opts.cert,
key: opts.key,
rejectUnauthorized: opts.strictSSL,
}
return retry(
deps/npm/node_modules/make-fetch-happen/package.json
Generated Vendored
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "make-fetch-happen",
"version": "8.0.12",
"version": "8.0.13",
"description": "Opinionated, caching, retrying fetch client",
"main": "index.js",
"files": [
deps/npm/node_modules/pacote/README.md
Generated Vendored
+5
View File
@@ -162,6 +162,11 @@ resolved, and other properties, as they are determined.
including information not strictly required for installation (author,
description, etc.) Defaults to `true` when `before` is set, since the
version publish time is part of the extended packument metadata.
* `packumentCache` For registry packuments only, you may provide a `Map`
object which will be used to cache packument requests between pacote
calls. This allows you to easily avoid hitting the registry multiple
times (even just to validate the cache) for a given packument, since it
is unlikely to change in the span of a single command.
## Extracted File Modes
deps/npm/node_modules/pacote/lib/fetcher.js
Generated Vendored
+1
View File
@@ -60,6 +60,7 @@ class FetcherBase {
// clone the opts object so that others aren't upset when we mutate it
// by adding/modifying the integrity value.
this.opts = {...opts}
this.cache = opts.cache || cacheDir()
this.resolved = opts.resolved || null
deps/npm/node_modules/pacote/lib/registry.js
Generated Vendored
+23 -2
View File
@@ -20,6 +20,14 @@ class RegistryFetcher extends Fetcher {
constructor (spec, opts) {
super(spec, opts)
// you usually don't want to fetch the same packument multiple times in
// the span of a given script or command, no matter how many pacote calls
// are made, so this lets us avoid doing that. It's only relevant for
// registry fetchers, because other types simulate their packument from
// the manifest, which they memoize on this.package, so it's very cheap
// already.
this.packumentCache = this.opts.packumentCache || null
// handle case when npm-package-arg guesses wrong.
if (this.spec.type === 'tag' &&
this.spec.rawSpec === '' &&
@@ -64,11 +72,17 @@ class RegistryFetcher extends Fetcher {
}
}
packument () {
async packument () {
// note this might be either an in-flight promise for a request,
// or the actual packument, but we never want to make more than
// one request at a time for the same thing regardless.
if (this.packumentCache && this.packumentCache.has(this.packumentUrl))
return this.packumentCache.get(this.packumentUrl)
// npm-registry-fetch the packument
// set the appropriate header for corgis if fullMetadata isn't set
// return the res.json() promise
return fetch(this.packumentUrl, {
const p = fetch(this.packumentUrl, {
...this.opts,
headers: this[_headers](),
spec: this.spec,
@@ -77,8 +91,12 @@ class RegistryFetcher extends Fetcher {
}).then(res => res.json().then(packument => {
packument._cached = res.headers.has('x-local-cache')
packument._contentLength = +res.headers.get('content-length')
if (this.packumentCache)
this.packumentCache.set(this.packumentUrl, packument)
return packument
})).catch(er => {
if (this.packumentCache)
this.packumentCache.delete(this.packumentUrl)
if (er.code === 'E404' && !this.fullMetadata) {
// possible that corgis are not supported by this registry
this.fullMetadata = true
@@ -86,6 +104,9 @@ class RegistryFetcher extends Fetcher {
}
throw er
})
if (this.packumentCache)
this.packumentCache.set(this.packumentUrl, p)
return p
}
manifest () {
deps/npm/node_modules/pacote/package.json
Generated Vendored
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "pacote",
"version": "11.1.14",
"version": "11.2.1",
"description": "JavaScript package downloader",
"author": "Isaac Z. Schlueter <i@izs.me> (https://izs.me)",
"bin": {
@@ -13,7 +13,7 @@
"snap": "tap",
"preversion": "npm test",
"postversion": "npm publish",
"postpublish": "git push origin --follow-tags"
"prepublishOnly": "git push origin --follow-tags"
},
"tap": {
"timeout": 300,
deps/npm/package.json
Vendored
+4 -4
View File
@@ -1,5 +1,5 @@
{
"version": "7.4.0",
"version": "7.4.2",
"name": "npm",
"description": "a package manager for JavaScript",
"keywords": [
@@ -42,7 +42,7 @@
"./package.json": "./package.json"
},
"dependencies": {
"@npmcli/arborist": "^2.0.3",
"@npmcli/arborist": "^2.0.5",
"@npmcli/ci-detect": "^1.2.0",
"@npmcli/config": "^1.2.8",
"@npmcli/run-script": "^1.8.1",
@@ -74,7 +74,7 @@
"libnpmsearch": "^3.1.0",
"libnpmteam": "^2.0.2",
"libnpmversion": "^1.0.7",
"make-fetch-happen": "^8.0.12",
"make-fetch-happen": "^8.0.13",
"minipass": "^3.1.3",
"minipass-pipeline": "^1.2.4",
"mkdirp": "^1.0.4",
@@ -90,7 +90,7 @@
"npm-user-validate": "^1.0.1",
"npmlog": "~4.1.2",
"opener": "^1.5.2",
"pacote": "^11.1.14",
"pacote": "^11.2.1",
"parse-conflict-json": "^1.1.1",
"qrcode-terminal": "^0.12.0",
"read": "~1.0.7",
deps/npm/tap-snapshots/test-lib-link.js-TAP.test.js
Vendored
+5
View File
@@ -19,6 +19,11 @@ exports[`test/lib/link.js TAP link pkg already in global space > should create a
`
exports[`test/lib/link.js TAP link pkg already in global space when prefix is a symlink > should create a local symlink to global pkg 1`] = `
{CWD}/test/lib/link-link-pkg-already-in-global-space-when-prefix-is-a-symlink/my-project/node_modules/@myscope/linked -> {CWD}/test/lib/link-link-pkg-already-in-global-space-when-prefix-is-a-symlink/scoped-linked
`
exports[`test/lib/link.js TAP link to globalDir when in current working dir of pkg and no args > should create a global link to current pkg 1`] = `
{CWD}/test/lib/link-link-to-globalDir-when-in-current-working-dir-of-pkg-and-no-args/global-prefix/lib/node_modules/test-pkg-link -> {CWD}/test/lib/link-link-to-globalDir-when-in-current-working-dir-of-pkg-and-no-args/test-pkg-link
deps/npm/test/lib/link.js
Vendored
+58
View File
@@ -259,6 +259,64 @@ t.test('link pkg already in global space', (t) => {
})
})
t.test('link pkg already in global space when prefix is a symlink', (t) => {
t.plan(3)
const testdir = t.testdir({
'global-prefix': t.fixture('symlink', './real-global-prefix'),
'real-global-prefix': {
lib: {
node_modules: {
'@myscope': {
linked: t.fixture('symlink', '../../../../scoped-linked'),
},
},
},
},
'scoped-linked': {
'package.json': JSON.stringify({
name: '@myscope/linked',
version: '1.0.0',
}),
},
'my-project': {
'package.json': JSON.stringify({
name: 'my-project',
version: '1.0.0',
}),
},
})
npm.globalDir = resolve(testdir, 'global-prefix', 'lib', 'node_modules')
npm.prefix = resolve(testdir, 'my-project')
npm.config.find = () => 'default'
const _cwd = process.cwd()
process.chdir(npm.prefix)
reifyOutput = async () => {
reifyOutput = undefined
process.chdir(_cwd)
npm.config.find = () => null
const links = await printLinks({
path: npm.prefix,
})
t.equal(
require(resolve(testdir, 'my-project', 'package.json')).dependencies,
undefined,
'should not save to package.json upon linking'
)
t.matchSnapshot(links, 'should create a local symlink to global pkg')
}
link(['@myscope/linked'], (err) => {
t.ifError(err, 'should not error out')
})
})
t.test('completion', (t) => {
const testdir = t.testdir({
'global-prefix': {
deps/npm/test/lib/ls.js
Vendored
+1
View File
@@ -3795,6 +3795,7 @@ t.test('ls --json', (t) => {
t.deepEqual(
jsonParse(result),
{
name: 'ls-ls-json-global',
dependencies: {
a: {
version: '1.0.0',
deps/npm/test/lib/outdated.js
Vendored
+3
View File
@@ -131,6 +131,9 @@ t.test('should display outdated deps', t => {
devDependencies: {
zeta: '^1.0.0',
},
optionalDependencies: {
lorem: '^1.0.0',
},
peerDependencies: {
beta: '^1.0.0',
},