diff options
author | isaacs <i@izs.me> | 2020-12-11 21:44:38 +0300 |
---|---|---|
committer | isaacs <i@izs.me> | 2020-12-11 22:33:58 +0300 |
commit | e340cf64ba31ef329a9049b60c32ffd0342cfb7d (patch) | |
tree | 72199ba3e77f36f3e8e1a6163d908d0f03f589ca /docs | |
parent | 7a4f0c96c2ab9f264f7bda2caf7e72c881571270 (diff) |
docs: explain through run-script
PR-URL: https://github.com/npm/cli/pull/2330
Credit: @isaacs
Close: #2330
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/commands/npm-explain.md | 2 | ||||
-rw-r--r-- | docs/content/commands/npm-link.md | 69 | ||||
-rw-r--r-- | docs/content/commands/npm-logout.md | 12 | ||||
-rw-r--r-- | docs/content/commands/npm-ls.md | 60 | ||||
-rw-r--r-- | docs/content/commands/npm-org.md | 7 | ||||
-rw-r--r-- | docs/content/commands/npm-outdated.md | 62 | ||||
-rw-r--r-- | docs/content/commands/npm-owner.md | 22 | ||||
-rw-r--r-- | docs/content/commands/npm-pack.md | 12 | ||||
-rw-r--r-- | docs/content/commands/npm-ping.md | 1 | ||||
-rw-r--r-- | docs/content/commands/npm-profile.md | 41 | ||||
-rw-r--r-- | docs/content/commands/npm-prune.md | 25 | ||||
-rw-r--r-- | docs/content/commands/npm-publish.md | 100 | ||||
-rw-r--r-- | docs/content/commands/npm-rebuild.md | 15 | ||||
-rw-r--r-- | docs/content/commands/npm-repo.md | 6 | ||||
-rw-r--r-- | docs/content/commands/npm-restart.md | 23 | ||||
-rw-r--r-- | docs/content/commands/npm-root.md | 10 | ||||
-rw-r--r-- | docs/content/commands/npm-run-script.md | 43 | ||||
-rw-r--r-- | docs/content/using-npm/developers.md | 75 |
18 files changed, 351 insertions, 234 deletions
diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md index fe7485d61..ec63ec34f 100644 --- a/docs/content/commands/npm-explain.md +++ b/docs/content/commands/npm-explain.md @@ -8,6 +8,8 @@ description: Explain installed packages ```bash npm explain <folder | specifier> + +alias: why ``` ### Description diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md index 7c55f18c5..1a835001f 100644 --- a/docs/content/commands/npm-link.md +++ b/docs/content/commands/npm-link.md @@ -15,41 +15,44 @@ alias: npm ln ### Description +This is handy for installing your own stuff, so that you can work on it and +test iteratively without having to continually rebuild. + Package linking is a two-step process. -First, `npm link` in a package folder will create a symlink in the global folder -`{prefix}/lib/node_modules/<package>` that links to the package where the `npm -link` command was executed. It will also link any bins in the package to `{prefix}/bin/{name}`. -Note that `npm link` uses the global prefix (see `npm prefix -g` for its value). +First, `npm link` in a package folder will create a symlink in the global +folder `{prefix}/lib/node_modules/<package>` that links to the package +where the `npm link` command was executed. It will also link any bins in +the package to `{prefix}/bin/{name}`. Note that `npm link` uses the global +prefix (see `npm prefix -g` for its value). Next, in some other location, `npm link package-name` will create a -symbolic link from globally-installed `package-name` to `node_modules/` -of the current folder. +symbolic link from globally-installed `package-name` to `node_modules/` of +the current folder. -Note that `package-name` is taken from `package.json`, -not from directory name. +Note that `package-name` is taken from `package.json`, _not_ from the +directory name. -The package name can be optionally prefixed with a scope. See [`scope`](/using-npm/scope). -The scope must be preceded by an @-symbol and followed by a slash. +The package name can be optionally prefixed with a scope. See +[`scope`](/using-npm/scope). The scope must be preceded by an @-symbol and +followed by a slash. When creating tarballs for `npm publish`, the linked packages are -"snapshotted" to their current state by resolving the symbolic links. - -This is handy for installing your own stuff, so that you can work on it and -test it iteratively without having to continually rebuild. +"snapshotted" to their current state by resolving the symbolic links, if +they are included in `bundleDependencies`. For example: ```bash - cd ~/projects/node-redis # go into the package directory - npm link # creates global link - cd ~/projects/node-bloggy # go into some other package directory. - npm link redis # link-install the package +cd ~/projects/node-redis # go into the package directory +npm link # creates global link +cd ~/projects/node-bloggy # go into some other package directory. +npm link redis # link-install the package ``` -Now, any changes to ~/projects/node-redis will be reflected in -~/projects/node-bloggy/node_modules/node-redis/. Note that the link should -be to the package name, not the directory name for that package. +Now, any changes to `~/projects/node-redis` will be reflected in +`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link +should be to the package name, not the directory name for that package. You may also shortcut the two steps in one. For example, to do the above use-case in a shorter way: @@ -69,15 +72,33 @@ npm link redis That is, it first creates a global link, and then links the global installation target into your project's `node_modules` folder. -Note that in this case, you are referring to the directory name, `node-redis`, -rather than the package name `redis`. +Note that in this case, you are referring to the directory name, +`node-redis`, rather than the package name `redis`. -If your linked package is scoped (see [`scope`](/using-npm/scope)) your link command must include that scope, e.g. +If your linked package is scoped (see [`scope`](/using-npm/scope)) your +link command must include that scope, e.g. ```bash npm link @myorg/privatepackage ``` +### Caveat + +Note that package dependencies linked in this way are _not_ saved to +`package.json` by default, on the assumption that the intention is to have +a link stand in for a regular non-link dependency. Otherwise, for example, +if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace +the `^3.0.1` dependency with `file:../path/to/node-redis`, which you +probably don't want! Additionally, other users or developers on your +project would run into issues if they do not have their folders set up +exactly the same as yours. + +If you are adding a _new_ dependency as a link, you should add it to the +relevant metadata by running `npm install <dep> --package-lock-only`. + +If you _want_ to save the `file:` reference in your `package.json` and +`package-lock.json` files, you can use `npm link <dep> --save` to do so. + ### See Also * [npm developers](/using-npm/developers) diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md index b1f344af5..7fa858a99 100644 --- a/docs/content/commands/npm-logout.md +++ b/docs/content/commands/npm-logout.md @@ -12,13 +12,13 @@ npm logout [--registry=<url>] [--scope=<@scope>] ### Description -When logged into a registry that supports token-based authentication, tell the -server to end this token's session. This will invalidate the token everywhere -you're using it, not just for the current environment. +When logged into a registry that supports token-based authentication, tell +the server to end this token's session. This will invalidate the token +everywhere you're using it, not just for the current environment. -When logged into a legacy registry that uses username and password authentication, this will -clear the credentials in your user configuration. In this case, it will _only_ affect -the current environment. +When logged into a legacy registry that uses username and password +authentication, this will clear the credentials in your user configuration. +In this case, it will _only_ affect the current environment. If `--scope` is provided, this will find the credentials for the registry connected to that scope, if set. diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md index c6e2af331..54787bd63 100644 --- a/docs/content/commands/npm-ls.md +++ b/docs/content/commands/npm-ls.md @@ -15,17 +15,21 @@ aliases: list, la, ll ### Description This command will print to stdout all the versions of packages that are -installed, as well as their dependencies, in a tree-structure. +installed, as well as their dependencies when `--all` is specified, in a +tree structure. -Positional arguments are `name@version-range` identifiers, which will -limit the results to only the paths to the packages named. Note that -nested packages will *also* show the paths to the specified packages. -For example, running `npm ls promzard` in npm's source tree will show: +Note: to get a "bottoms up" view of why a given package is included in the +tree at all, use [`npm explain`](/commands/npm-explain). + +Positional arguments are `name@version-range` identifiers, which will limit +the results to only the paths to the packages named. Note that nested +packages will *also* show the paths to the specified packages. For +example, running `npm ls promzard` in npm's source tree will show: ```bash - npm@@VERSION@ /path/to/npm - └─┬ init-package-json@0.0.4 - └── promzard@0.1.5 +npm@@VERSION@ /path/to/npm +└─┬ init-package-json@0.0.4 + └── promzard@0.1.5 ``` It will print out extraneous, missing, and invalid packages. @@ -35,12 +39,49 @@ in parentheses after the name@version to make it easier for users to recognize potential forks of a project. The tree shown is the logical dependency tree, based on package -dependencies, not the physical layout of your node_modules folder. +dependencies, not the physical layout of your `node_modules` folder. When run as `ll` or `la`, it shows extended information by default. +### Note: Design Changes Pending + +The `npm ls` command's output and behavior made a _ton_ of sense when npm +created a `node_modules` folder that naively nested every dependency. In +such a case, the logical dependency graph and physical tree of packages on +disk would be roughly identical. + +With the advent of automatic install-time deduplication of dependencies in +npm v3, the `ls` output was modified to display the logical dependency +graph as a tree structure, since this was more useful to most users. +However, without using `npm ls -l`, it became impossible show _where_ a +package was actually installed much of the time! + +With the advent of automatic installation of `peerDependencies` in npm v7, +this gets even more curious, as `peerDependencies` are logically +"underneath" their dependents in the dependency graph, but are always +physically at or above their location on disk. + +Also, in the years since npm got an `ls` command (in version 0.0.2!), +dependency graphs have gotten much larger as a general rule. Therefor, in +order to avoid dumping an excessive amount of content to the terminal, `npm +ls` now only shows the _top_ level dependencies, unless `--all` is +provided. + +A thorough re-examination of the use cases, intention, behavior, and output +of this command, is currently underway. Expect significant changes to at +least the default human-readable `npm ls` output in npm v8. + ### Configuration +#### all + +* Default: `false` +* Type: Boolean + +When running `npm outdated` and `npm ls`, setting `--all` will show all +outdated or installed packages, rather than only those directly depended +upon by the current project. + #### json * Default: false @@ -115,6 +156,7 @@ Set it to false in order to use all-ansi output. ### See Also +* [npm explain](/commands/npm-explain) * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) * [npm folders](/configuring-npm/folders) diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md index 2f3c6b480..18047d109 100644 --- a/docs/content/commands/npm-org.md +++ b/docs/content/commands/npm-org.md @@ -52,10 +52,11 @@ $ npm org ls my-org @mx-santos ### Description -You can use the `npm org` commands to manage and view users of an organization. -It supports adding and removing users, changing their roles, listing them, and -finding specific ones and their roles. +You can use the `npm org` commands to manage and view users of an +organization. It supports adding and removing users, changing their roles, +listing them, and finding specific ones and their roles. ### See Also +* [using orgs](/using-npm/orgs) * [Documentation on npm Orgs](https://docs.npmjs.com/orgs/) diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md index 01ad78086..ee1157f33 100644 --- a/docs/content/commands/npm-outdated.md +++ b/docs/content/commands/npm-outdated.md @@ -15,25 +15,34 @@ npm outdated [[<@scope>/]<pkg> ...] This command will check the registry to see if any (or, specific) installed packages are currently outdated. +By default, only the direct dependencies of the root project are shown. +Use `--all` to find all outdated meta-dependencies as well. + In the output: * `wanted` is the maximum version of the package that satisfies the semver - range specified in `package.json`. If there's no available semver range (i.e. - you're running `npm outdated --global`, or the package isn't included in - `package.json`), then `wanted` shows the currently-installed version. + range specified in `package.json`. If there's no available semver range + (i.e. you're running `npm outdated --global`, or the package isn't + included in `package.json`), then `wanted` shows the currently-installed + version. * `latest` is the version of the package tagged as latest in the registry. - Running `npm publish` with no special configuration will publish the package - with a dist-tag of `latest`. This may or may not be the maximum version of - the package, or the most-recently published version of the package, depending - on how the package's developer manages the latest [dist-tag](npm-dist-tag). + Running `npm publish` with no special configuration will publish the + package with a dist-tag of `latest`. This may or may not be the maximum + version of the package, or the most-recently published version of the + package, depending on how the package's developer manages the latest + [dist-tag](/commands/npm-dist-tag). * `location` is where in the physical tree the package is located. * `depended by` shows which package depends on the displayed dependency -* `package type` (when using `--long` / `-l`) tells you whether this package is - a `dependency` or a dev/peer/optional dependency. Packages not included in `package.json` - are always marked `dependencies`. -* `homepage` (when using `--long` / `-l`) is the `homepage` value contained in the package's packument -* Red means there's a newer version matching your semver requirements, so you should update now. -* Yellow indicates that there's a newer version above your semver requirements (usually new major, or new 0.x minor) so proceed with caution. +* `package type` (when using `--long` / `-l`) tells you whether this + package is a `dependency` or a dev/peer/optional dependency. Packages not + included in `package.json` are always marked `dependencies`. +* `homepage` (when using `--long` / `-l`) is the `homepage` value contained + in the package's packument +* Red means there's a newer version matching your semver requirements, so + you should update now. +* Yellow indicates that there's a newer version _above_ your semver + requirements (usually new major, or new 0.x minor) so proceed with + caution. ### An example @@ -59,19 +68,20 @@ With these `dependencies`: A few things to note: -* `glob` requires `^5`, which prevents npm from installing `glob@6`, which is - outside the semver range. -* Git dependencies will always be reinstalled, because of how they're specified. - The installed committish might satisfy the dependency specifier (if it's - something immutable, like a commit SHA), or it might not, so `npm outdated` and - `npm update` have to fetch Git repos to check. This is why currently doing a - reinstall of a Git dependency always forces a new clone and install. -* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because npm - uses dist-tags to manage its `latest` and `next` release channels. `npm update` - will install the _newest_ version, but `npm install npm` (with no semver range) - will install whatever's tagged as `latest`. -* `once` is just plain out of date. Reinstalling `node_modules` from scratch or - running `npm update` will bring it up to spec. +* `glob` requires `^5`, which prevents npm from installing `glob@6`, which + is outside the semver range. +* Git dependencies will always be reinstalled, because of how they're + specified. The installed committish might satisfy the dependency + specifier (if it's something immutable, like a commit SHA), or it might + not, so `npm outdated` and `npm update` have to fetch Git repos to check. + This is why currently doing a reinstall of a Git dependency always forces + a new clone and install. +* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because + npm uses dist-tags to manage its `latest` and `next` release channels. + `npm update` will install the _newest_ version, but `npm install npm` + (with no semver range) will install whatever's tagged as `latest`. +* `once` is just plain out of date. Reinstalling `node_modules` from + scratch or running `npm update` will bring it up to spec. ### Configuration diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md index 3c984ebd8..6479f3bdd 100644 --- a/docs/content/commands/npm-owner.md +++ b/docs/content/commands/npm-owner.md @@ -18,26 +18,24 @@ aliases: author Manage ownership of published packages. -* ls: - List all the users who have access to modify a package and push new versions. - Handy when you need to know who to bug for help. -* add: - Add a new user as a maintainer of a package. This user is enabled to modify - metadata, publish new versions, and add other owners. -* rm: - Remove a user from the package owner list. This immediately revokes their - privileges. +* ls: List all the users who have access to modify a package and push new + versions. Handy when you need to know who to bug for help. +* add: Add a new user as a maintainer of a package. This user is enabled + to modify metadata, publish new versions, and add other owners. +* rm: Remove a user from the package owner list. This immediately revokes + their privileges. Note that there is only one level of access. Either you can modify a package, or you can't. Future versions may contain more fine-grained access levels, but that is not implemented at this time. -If you have two-factor authentication enabled with `auth-and-writes` then -you'll need to include an otp on the command line when changing ownership -with `--otp`. +If you have two-factor authentication enabled with `auth-and-writes` (see +[`npm-profile`](/commands/npm-profile)) then you'll need to include an otp +on the command line when changing ownership with `--otp`. ### See Also +* [npm profile](/commands/npm-profile) * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) * [npm adduser](/commands/npm-adduser) diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md index adb5d3083..cc6b669ef 100644 --- a/docs/content/commands/npm-pack.md +++ b/docs/content/commands/npm-pack.md @@ -13,10 +13,10 @@ npm pack [[<@scope>/]<pkg>...] [--dry-run] ### Description For anything that's installable (that is, a package folder, tarball, -tarball url, name@tag, name@version, name, or scoped name), this -command will fetch it to the cache, and then copy the tarball to the -current working directory as `<name>-<version>.tgz`, and then write -the filenames out to stdout. +tarball url, git url, name@tag, name@version, name, or scoped name), this +command will fetch it to the cache, copy the tarball to the current working +directory as `<name>-<version>.tgz`, and then write the filenames out to +stdout. If the same package is specified multiple times, then the file will be overwritten the second time. @@ -24,10 +24,12 @@ overwritten the second time. If no arguments are supplied, then npm packs the current package folder. The `--dry-run` argument will do everything that pack usually does without -actually packing anything. Reports on what would have gone into the tarball. +actually packing anything. That is, it reports on what would have gone +into the tarball, but nothing else. ### See Also +* [npm-packlist package](http://npm.im/npm-packlist) * [npm cache](/commands/npm-cache) * [npm publish](/commands/npm-publish) * [npm config](/commands/npm-config) diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md index bc2233da7..8de06aa18 100644 --- a/docs/content/commands/npm-ping.md +++ b/docs/content/commands/npm-ping.md @@ -25,5 +25,6 @@ Ping error: {*Detail about error} ### See Also +* [npm doctor](/commands/npm-doctor) * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-profile.md b/docs/content/commands/npm-profile.md index d44c99416..88edf26d8 100644 --- a/docs/content/commands/npm-profile.md +++ b/docs/content/commands/npm-profile.md @@ -16,12 +16,12 @@ npm profile disable-2fa ### Description -Change your profile information on the registry. This not be available if -you're using a non-npmjs registry. +Change your profile information on the registry. Note that this command +depends on the registry implementation, so third-party registries may not +support this interface. -* `npm profile get [<property>]`: - Display all of the properties of your profile, or one or more specific - properties. It looks like: +* `npm profile get [<property>]`: Display all of the properties of your + profile, or one or more specific properties. It looks like: ```bash +-----------------+---------------------------+ @@ -46,27 +46,26 @@ you're using a non-npmjs registry. | updated | 2017-10-02T21:29:45.922Z | +-----------------+---------------------------+ ``` - -* `npm profile set <property> <value>`: - Set the value of a profile property. You can set the following properties this way: - email, fullname, homepage, freenode, twitter, github -* `npm profile set password`: - Change your password. This is interactive, you'll be prompted for your - current password and a new password. You'll also be prompted for an OTP - if you have two-factor authentication enabled. +* `npm profile set <property> <value>`: Set the value of a profile + property. You can set the following properties this way: email, fullname, + homepage, freenode, twitter, github -* `npm profile enable-2fa [auth-and-writes|auth-only]`: - Enables two-factor authentication. Defaults to `auth-and-writes` mode. Modes are: +* `npm profile set password`: Change your password. This is interactive, + you'll be prompted for your current password and a new password. You'll + also be prompted for an OTP if you have two-factor authentication + enabled. + +* `npm profile enable-2fa [auth-and-writes|auth-only]`: Enables two-factor + authentication. Defaults to `auth-and-writes` mode. Modes are: * `auth-only`: Require an OTP when logging in or making changes to your account's authentication. The OTP will be required on both the website and the command line. - * `auth-and-writes`: Requires an OTP at all the times `auth-only` does, and also requires one when - publishing a module, setting the `latest` dist-tag, or changing access - via `npm access` and `npm owner`. + * `auth-and-writes`: Requires an OTP at all the times `auth-only` does, + and also requires one when publishing a module, setting the `latest` + dist-tag, or changing access via `npm access` and `npm owner`. -* `npm profile disable-2fa`: - Disables two-factor authentication. +* `npm profile disable-2fa`: Disables two-factor authentication. ### Details @@ -76,4 +75,6 @@ available on non npmjs.com registries. ### See Also +* [npm adduser](/commands/npm-adduser) +* [npm logout](/commands/npm-logout) * [npm config](/commands/npm-config) diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md index 1a100e9d8..088c1c347 100644 --- a/docs/content/commands/npm-prune.md +++ b/docs/content/commands/npm-prune.md @@ -12,29 +12,26 @@ npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json] ### Description -This command removes "extraneous" packages. If a package name is -provided, then only packages matching one of the supplied names are -removed. +This command removes "extraneous" packages. If a package name is provided, +then only packages matching one of the supplied names are removed. -Extraneous packages are packages that are not listed on the parent -package's dependencies list. +Extraneous packages are those present in the `node_modules` folder that are +not listed as any package's dependency list. If the `--production` flag is specified or the `NODE_ENV` environment variable is set to `production`, this command will remove the packages -specified in your `devDependencies`. Setting `--no-production` will -negate `NODE_ENV` being set to `production`. +specified in your `devDependencies`. Setting `--no-production` will negate +`NODE_ENV` being set to `production`. If the `--dry-run` flag is used then no changes will actually be made. -If the `--json` flag is used then the changes `npm prune` made (or would +If the `--json` flag is used, then the changes `npm prune` made (or would have made with `--dry-run`) are printed as a JSON object. -In normal operation with package-locks enabled, extraneous modules are -pruned automatically when modules are installed and you'll only need -this command with the `--production` flag. - -If you've disabled package-locks then extraneous modules will not be removed -and it's up to you to run `npm prune` from time-to-time to remove them. +In normal operation, extraneous modules are pruned automatically, so you'll +only need this command with the `--production` flag. However, in the real +world, operation is not always "normal". When crashes or mistakes happen, +this command can help clean up any resulting garbage. ### See Also diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md index 3dcdc6f30..fc13e6722 100644 --- a/docs/content/commands/npm-publish.md +++ b/docs/content/commands/npm-publish.md @@ -15,59 +15,91 @@ Sets tag 'latest' if no --tag specified ### Description -Publishes a package to the registry so that it can be installed by name. All -files in the package directory are included if no local `.gitignore` or -`.npmignore` file exists. If both files exist and a file is ignored by -`.gitignore` but not by `.npmignore` then it will be included. See -[`developers`](/using-npm/developers) for full details on what's included in the published package, as well as details on how the package is built. +Publishes a package to the registry so that it can be installed by name. -By default npm will publish to the public registry. This can be overridden by -specifying a different default registry or using a [`scope`](/using-npm/scope) in the name (see [`package.json`](/configuring-npm/package-json)). +By default npm will publish to the public registry. This can be overridden +by specifying a different default registry or using a +[`scope`](/using-npm/scope) in the name (see +[`package.json`](/configuring-npm/package-json)). -* `<folder>`: - A folder containing a package.json file +* `<folder>`: A folder containing a package.json file -* `<tarball>`: - A url or file path to a gzipped tar archive containing a single folder - with a package.json file inside. +* `<tarball>`: A url or file path to a gzipped tar archive containing a + single folder with a package.json file inside. -* `[--tag <tag>]` - Registers the published package with the given tag, such that - `npm install <name>@<tag>` will install this version. By default, +* `[--tag <tag>]`: Registers the published package with the given tag, such + that `npm install <name>@<tag>` will install this version. By default, `npm publish` updates and `npm install` installs the `latest` tag. See [`npm-dist-tag`](npm-dist-tag) for details about tags. -* `[--access <public|restricted>]` - Tells the registry whether this package should be published as public or - restricted. Only applies to scoped packages, which default to `restricted`. - If you don't have a paid account, you must publish with `--access public` - to publish scoped packages. +* `[--access <public|restricted>]`: Tells the registry whether this package + should be published as public or restricted. Only applies to scoped + packages, which default to `restricted`. If you don't have a paid + account, you must publish with `--access public` to publish scoped + packages. -* `[--otp <otpcode>]` - If you have two-factor authentication enabled in `auth-and-writes` mode - then you can provide a code from your authenticator with this. If you - don't include this and you're running from a TTY then you'll be prompted. +* `[--otp <otpcode>]`: If you have two-factor authentication enabled in + `auth-and-writes` mode then you can provide a code from your + authenticator with this. If you don't include this and you're running + from a TTY then you'll be prompted. -* `[--dry-run]` - As of `npm@6`, does everything publish would do except actually publishing - to the registry. Reports the details of what would have been published. +* `[--dry-run]`: As of `npm@6`, does everything publish would do except + actually publishing to the registry. Reports the details of what would + have been published. -Fails if the package name and version combination already exists in -the specified registry. +The publish will fail if the package name and version combination already +exists in the specified registry. -Once a package is published with a given name and version, that -specific name and version combination can never be used again, even if -it is removed with [`npm unpublish`](/commands/npm-unpublish). +Once a package is published with a given name and version, that specific +name and version combination can never be used again, even if it is removed +with [`npm unpublish`](/commands/npm-unpublish). As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the tarball will be submitted to the registry during publication. Subsequent installs will use the strongest supported algorithm to verify downloads. -Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures out the files to be -included and packs them into a tarball to be uploaded to the registry. +Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures +out the files to be included and packs them into a tarball to be uploaded +to the registry. + +### Files included in package + +To see what will be included in your package, run `npx npm-packlist`. All +files are included by default, with the following exceptions: + +- Certain files that are relevant to package installation and distribution + are always included. For example, `package.json`, `README.md`, + `LICENSE`, and so on. + +- If there is a "files" list in + [`package.json`](/configuring-npm/package-json), then only the files + specified will be included. (If directories are specified, then they + will be walked recursively and their contents included, subject to the + same ignore rules.) + +- If there is a `.gitignore` or `.npmignore` file, then ignored files in + that and all child directories will be excluded from the package. If + _both_ files exist, then the `.gitignore` is ignored, and only the + `.npmignore` is used. + + `.npmignore` files follow the [same pattern + rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) + as `.gitignore` files + +- If the file matches certain patterns, then it will _never_ be included, + unless explicitly added to the `"files"` list in `package.json`, or + un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file. + +- Symbolic links are never included in npm packages. + + +See [`developers`](/using-npm/developers) for full details on what's +included in the published package, as well as details on how the package is +built. ### See Also +* [npm-packlist package](http://npm.im/npm-packlist) * [npm registry](/using-npm/registry) * [npm scope](/using-npm/scope) * [npm adduser](/commands/npm-adduser) diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md index 5b6b816f6..0a7ade6b1 100644 --- a/docs/content/commands/npm-rebuild.md +++ b/docs/content/commands/npm-rebuild.md @@ -7,16 +7,23 @@ description: Rebuild a package ### Synopsis ```bash -npm rebuild [[<@scope>/<name>]...] +npm rebuild [[<@scope>/]<name>[@<version>] ...] -alias: npm rb +alias: rb ``` ### Description -This command runs the `npm build` command on the matched folders. This is useful when you install a new version of node, and must recompile all your C++ addons with the new binary. +This command runs the `npm build` command on the matched folders. This is +useful when you install a new version of node, and must recompile all your +C++ addons with the new binary. It is also useful when installing with +`--ignore-scripts` and `--no-bin-links`, to explicitly choose which +packages to build and/or link bins. + +If one or more package names (and optionally version ranges) are provided, +then only packages with a name and version matching one of the specifiers +will be rebuilt. ### See Also -* [npm build](/commands/npm-build) * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md index c6fdf36f1..670345bec 100644 --- a/docs/content/commands/npm-repo.md +++ b/docs/content/commands/npm-repo.md @@ -13,9 +13,9 @@ npm repo [<pkgname> [<pkgname> ...]] ### Description This command tries to guess at the likely location of a package's -repository URL, and then tries to open it using the `--browser` -config param. If no package name is provided, it will search for -a `package.json` in the current folder and use the `name` property. +repository URL, and then tries to open it using the `--browser` config +param. If no package name is provided, it will search for a `package.json` +in the current folder and use the `repository` property. ### Configuration diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md index a80c54273..097c9fee7 100644 --- a/docs/content/commands/npm-restart.md +++ b/docs/content/commands/npm-restart.md @@ -12,29 +12,28 @@ npm restart [-- <args>] ### Description -This restarts a package. +This restarts a project. It is equivalent to running `npm run-script +restart`. -This runs a package's "stop", "restart", and "start" scripts, and associated -pre- and post- scripts, in the order given below: +If the current project has a `"restart"` script specified in +`package.json`, then the following scripts will be run: + +1. prerestart +2. restart +3. postrestart + +If it does _not_ have a `"restart"` script specified, but it does have +`stop` and/or `start` scripts, then the following scripts will be run: 1. prerestart 2. prestop 3. stop 4. poststop -5. restart 6. prestart 7. start 8. poststart 9. postrestart -### Note - -Note that the "restart" script is run **in addition to** the "stop" -and "start" scripts, not instead of them. - -This is the behavior as of `npm` major version 2. A change in this -behavior will be accompanied by an increase in major version number - ### See Also * [npm run-script](/commands/npm-run-script) diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md index 317ef9d85..0d694ac87 100644 --- a/docs/content/commands/npm-root.md +++ b/docs/content/commands/npm-root.md @@ -5,6 +5,7 @@ description: Display npm root --- ### Synopsis + ```bash npm root [-g] ``` @@ -13,6 +14,15 @@ npm root [-g] Print the effective `node_modules` folder to standard out. +Useful for using npm in shell scripts that do things with the +`node_modules` folder. For example: + +```bash +#!/bin/bash +global_node_modules="$(npm root --global)" +echo "Global packages installed in: ${global_node_modules}" +``` + ### See Also * [npm prefix](/commands/npm-prefix) diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md index 06b6e9383..05f6380c2 100644 --- a/docs/content/commands/npm-run-script.md +++ b/docs/content/commands/npm-run-script.md @@ -7,23 +7,25 @@ description: Run arbitrary package scripts ### Synopsis ```bash -npm run-script <command> [--silent] [-- <args>...] +npm run-script <command> [--if-present] [--silent] [-- <args>] -alias: npm run +aliases: run, rum, urn ``` ### Description This runs an arbitrary command from a package's `"scripts"` object. If no -`"command"` is provided, it will list the available scripts. `run[-script]` is -used by the test, start, restart, and stop commands, but can be called -directly, as well. When the scripts in the package are printed out, they're -separated into lifecycle (test, start, restart) and directly-run scripts. +`"command"` is provided, it will list the available scripts. -As of [`npm@2.0.0`](https://blog.npmjs.org/post/98131109725/npm-2-0-0), you can -use custom arguments when executing scripts. The special option `--` is used by -[getopt](https://goo.gl/KxMmtG) to delimit the end of the options. npm will pass -all the arguments after the `--` directly to your script: +`run[-script]` is used by the test, start, restart, and stop commands, but +can be called directly, as well. When the scripts in the package are +printed out, they're separated into lifecycle (test, start, restart) and +directly-run scripts. + +Any positional arguments are passed to the specified script. Use `--` to +pass `-`-prefixed flags and options which would otherwise be parsed by npm. + +For example: ```bash npm run test -- --grep="pattern" @@ -38,31 +40,28 @@ environment variables that will be available to the script at runtime. If an built-in. In addition to the shell's pre-existing `PATH`, `npm run` adds -`node_modules/.bin` to the `PATH` provided to scripts. Any binaries provided by -locally-installed dependencies can be used without the `node_modules/.bin` -prefix. For example, if there is a `devDependency` on `tap` in your package, -you should write: +`node_modules/.bin` to the `PATH` provided to scripts. Any binaries +provided by locally-installed dependencies can be used without the +`node_modules/.bin` prefix. For example, if there is a `devDependency` on +`tap` in your package, you should write: ```bash -"scripts": {"test": "tap test/\*.js"} +"scripts": {"test": "tap test/*.js"} ``` instead of ```bash -"scripts": {"test": "node_modules/.bin/tap test/\*.js"} +"scripts": {"test": "node_modules/.bin/tap test/*.js"} ``` -to run your tests. - The actual shell your script is run within is platform dependent. By default, on Unix-like systems it is the `/bin/sh` command, on Windows it is the `cmd.exe`. The actual shell referred to by `/bin/sh` also depends on the system. -As of [`npm@5.1.0`](https://github.com/npm/npm/releases/tag/v5.1.0) you can -customize the shell with the `script-shell` configuration. +You can customize the shell with the `script-shell` configuration. -Scripts are run from the root of the module, regardless of what your current -working directory is when you call `npm run`. If you want your script to +Scripts are run from the root of the module, regardless of what the current +working directory is when `npm run` is called. If you want your script to use different behavior based on what subdirectory you're in, you can use the `INIT_CWD` environment variable, which holds the full path you were in when you ran `npm run`. diff --git a/docs/content/using-npm/developers.md b/docs/content/using-npm/developers.md index 7e47b76f6..bce615cfe 100644 --- a/docs/content/using-npm/developers.md +++ b/docs/content/using-npm/developers.md @@ -47,69 +47,64 @@ git+https://user@hostname/project/blah.git#commit-ish ``` The `commit-ish` can be any tag, sha, or branch which can be supplied as -an argument to `git checkout`. The default is `master`. +an argument to `git checkout`. The default is whatever the repository uses +as its default branch. ### The package.json File You need to have a `package.json` file in the root of your project to do much of anything with npm. That is basically the whole interface. -See [`package.json`](/configuring-npm/package-json) for details about what goes in that file. At the very -least, you need: +See [`package.json`](/configuring-npm/package-json) for details about what +goes in that file. At the very least, you need: -* name: - This should be a string that identifies your project. Please do not - use the name to specify that it runs on node, or is in JavaScript. - You can use the "engines" field to explicitly state the versions of - node (or whatever else) that your program requires, and it's pretty - well assumed that it's JavaScript. +* name: This should be a string that identifies your project. Please do + not use the name to specify that it runs on node, or is in JavaScript. + You can use the "engines" field to explicitly state the versions of node + (or whatever else) that your program requires, and it's pretty well + assumed that it's JavaScript. It does not necessarily need to match your github repository name. So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. -* version: - A semver-compatible version. +* version: A semver-compatible version. -* engines: - Specify the versions of node (or whatever else) that your program - runs on. The node API changes a lot, and there may be bugs or new - functionality that you depend on. Be explicit. +* engines: Specify the versions of node (or whatever else) that your + program runs on. The node API changes a lot, and there may be bugs or + new functionality that you depend on. Be explicit. -* author: - Take some credit. +* author: Take some credit. -* scripts: - If you have a special compilation or installation script, then you - should put it in the `scripts` object. You should definitely have at - least a basic smoke-test command as the "scripts.test" field. - See [scripts](/using-npm/scripts). +* scripts: If you have a special compilation or installation script, then + you should put it in the `scripts` object. You should definitely have at + least a basic smoke-test command as the "scripts.test" field. See + [scripts](/using-npm/scripts). -* main: - If you have a single module that serves as the entry point to your - program (like what the "foo" package gives you at require("foo")), - then you need to specify that in the "main" field. +* main: If you have a single module that serves as the entry point to your + program (like what the "foo" package gives you at require("foo")), then + you need to specify that in the "main" field. -* directories: - This is an object mapping names to folders. The best ones to include are - "lib" and "doc", but if you use "man" to specify a folder full of man pages, - they'll get installed just like these ones. +* directories: This is an object mapping names to folders. The best ones + to include are "lib" and "doc", but if you use "man" to specify a folder + full of man pages, they'll get installed just like these ones. You can use `npm init` in the root of your package in order to get you -started with a pretty basic package.json file. See -[`npm init`](/commands/npm-init) for more info. +started with a pretty basic package.json file. See [`npm +init`](/commands/npm-init) for more info. ### Keeping files *out* of your package -Use a `.npmignore` file to keep stuff out of your package. If there's -no `.npmignore` file, but there *is* a `.gitignore` file, then npm will -ignore the stuff matched by the `.gitignore` file. If you *want* to -include something that is excluded by your `.gitignore` file, you can -create an empty `.npmignore` file to override it. Like `git`, `npm` looks -for `.npmignore` and `.gitignore` files in all subdirectories of your -package, not only the root directory. +Use a `.npmignore` file to keep stuff out of your package. If there's no +`.npmignore` file, but there *is* a `.gitignore` file, then npm will ignore +the stuff matched by the `.gitignore` file. If you *want* to include +something that is excluded by your `.gitignore` file, you can create an +empty `.npmignore` file to override it. Like `git`, `npm` looks for +`.npmignore` and `.gitignore` files in all subdirectories of your package, +not only the root directory. -`.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) +`.npmignore` files follow the [same pattern +rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) as `.gitignore` files: * Blank lines or lines starting with `#` are ignored. |