diff --git a/docs/content/cli-commands/npm-dedupe.md b/docs/content/cli-commands/npm-dedupe.md index 84ccb772fb9bc..c96b1f0d1d16c 100644 --- a/docs/content/cli-commands/npm-dedupe.md +++ b/docs/content/cli-commands/npm-dedupe.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-dedupe description: Reduce duplication --- @@ -25,7 +25,7 @@ be more effectively shared by multiple dependent packages. For example, consider this dependency graph: -```bash +``` a +-- b <-- depends on c@1.0.x | `-- c@1.0.3 @@ -46,20 +46,35 @@ Because of the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree. -The deduplication algorithm walks the tree, moving each dependency as far -up in the tree as possible, even if duplicates are not found. This will -result in both a flat and deduplicated tree. +In some cases, you may have a dependency graph like this: + +``` +a ++-- b <-- depends on c@1.0.x ++-- c@1.0.3 +`-- d <-- depends on c@1.x + `-- c@1.9.9 +``` + +During the installation process, the `c@1.0.3` dependency for `b` was +placed in the root of the tree. Though `d`'s dependency on `c@1.x` could +have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used, +because npm favors updates by default, even when doing so causes +duplication. + +Running `npm dedupe` will cause npm to note the duplication and +re-evaluate, deleting the nested `c` module, because the one in the root is +sufficient. -If a suitable version exists at the target location in the tree -already, then it will be left untouched, but the other duplicates will -be deleted. +To prefer deduplication over novelty during the installation process, run +`npm install --prefer-dedupe` or `npm config set prefer-dedupe true`. Arguments are ignored. Dedupe always acts on the entire tree. Note that this operation transforms the dependency tree, but will never result in new modules being installed. -Using `npm find-dupes` will run the command in dryRun mode. +Using `npm find-dupes` will run the command in `--dry-run` mode. ### See Also diff --git a/docs/content/cli-commands/npm-deprecate.md b/docs/content/cli-commands/npm-deprecate.md index 252c0e7037079..943719ac9bfba 100644 --- a/docs/content/cli-commands/npm-deprecate.md +++ b/docs/content/cli-commands/npm-deprecate.md @@ -3,22 +3,25 @@ section: cli-commands title: npm-deprecate description: Deprecate a version of a package --- + # npm-deprecate(1) ## Deprecate a version of a package ### Synopsis + ```bash npm deprecate [@] ``` ### Description -This command will update the npm registry entry for a package, providing -a deprecation warning to all who attempt to install it. +This command will update the npm registry entry for a package, providing a +deprecation warning to all who attempt to install it. -It works on [version ranges](https://semver.npmjs.com/) as well as specific +It works on [version ranges](https://semver.npmjs.com/) as well as specific versions, so you can do something like this: + ```bash npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" ``` @@ -34,3 +37,5 @@ format an empty string. * [npm publish](/cli-commands/publish) * [npm registry](/using-npm/registry) +* [npm owner](/cli-commands/owner) +* [npm owner](/cli-commands/adduser) diff --git a/docs/content/cli-commands/npm-dist-tag.md b/docs/content/cli-commands/npm-dist-tag.md index 4f7fcb9f58f1b..826d394e791a6 100644 --- a/docs/content/cli-commands/npm-dist-tag.md +++ b/docs/content/cli-commands/npm-dist-tag.md @@ -1,5 +1,5 @@ - --- -section: cli-commands +--- +section: cli-commands title: npm-dist-tag description: Modify package distribution tags --- @@ -8,8 +8,8 @@ description: Modify package distribution tags ## Modify package distribution tags - ### Synopsis + ```bash npm dist-tag add @ [] npm dist-tag rm @@ -22,17 +22,18 @@ aliases: dist-tags Add, remove, and enumerate distribution tags on a package: -* add: - Tags the specified version of the package with the specified tag, or the - `--tag` config if not specified. If you have two-factor authentication on - auth-and-writes then you’ll need to include a one-time password on the - command line with `--otp `. +* add: Tags the specified version of the package with the specified tag, or + the `--tag` config if not specified. If you have two-factor + authentication on auth-and-writes then you’ll need to include a one-time + password on the command line with `--otp `, or at the + OTP prompt. -* rm: - Clear a tag that is no longer in use from the package. +* rm: Clear a tag that is no longer in use from the package. If you have + two-factor authentication on auth-and-writes then you’ll need to include + a one-time password on the command line with `--otp `, + or at the OTP prompt. -* ls: - Show all of the dist-tags for a package, defaulting to the package in +* ls: Show all of the dist-tags for a package, defaulting to the package in the current prefix. This is the default action if none is specified. A tag can be used when installing packages as a reference to a version instead @@ -48,7 +49,8 @@ When installing dependencies, a preferred tagged version may be specified: npm install --tag ``` -This also applies to `npm dedupe`. +(This also applies to any other commands that resolve and install +dependencies, such as `npm dedupe`, `npm update`, and `npm audit fix`.) Publishing a package sets the `latest` tag to the published version unless the `--tag` option is used. For example, `npm publish --tag=beta`. @@ -61,34 +63,34 @@ specifier) installs the `latest` tag. Tags can be used to provide an alias instead of version numbers. For example, a project might choose to have multiple streams of development -and use a different tag for each stream, -e.g., `stable`, `beta`, `dev`, `canary`. +and use a different tag for each stream, e.g., `stable`, `beta`, `dev`, +`canary`. -By default, the `latest` tag is used by npm to identify the current version of -a package, and `npm install ` (without any `@` or `@` -specifier) installs the `latest` tag. Typically, projects only use the `latest` -tag for stable release versions, and use other tags for unstable versions such -as prereleases. +By default, the `latest` tag is used by npm to identify the current version +of a package, and `npm install ` (without any `@` or `@` +specifier) installs the `latest` tag. Typically, projects only use the +`latest` tag for stable release versions, and use other tags for unstable +versions such as prereleases. The `next` tag is used by some projects to identify the upcoming version. -By default, other than `latest`, no tag has any special significance to npm -itself. +Other than `latest`, no tag has any special significance to npm itself. ### Caveats -This command used to be known as `npm tag`, which only created new tags, and so -had a different syntax. +This command used to be known as `npm tag`, which only created new tags, +and so had a different syntax. -Tags must share a namespace with version numbers, because they are specified in -the same slot: `npm install @` vs `npm install @`. +Tags must share a namespace with version numbers, because they are +specified in the same slot: `npm install @` vs `npm install +@`. Tags that can be interpreted as valid semver ranges will be rejected. For -example, `v1.4` cannot be used as a tag, because it is interpreted by semver as -`>=1.4.0 <1.5.0`. See . +example, `v1.4` cannot be used as a tag, because it is interpreted by +semver as `>=1.4.0 <1.5.0`. See . -The simplest way to avoid semver problems with tags is to use tags that do not -begin with a number or the letter `v`. +The simplest way to avoid semver problems with tags is to use tags that do +not begin with a number or the letter `v`. ### See Also diff --git a/docs/content/cli-commands/npm-docs.md b/docs/content/cli-commands/npm-docs.md index ffa5db5ac6612..14976bfa4382b 100644 --- a/docs/content/cli-commands/npm-docs.md +++ b/docs/content/cli-commands/npm-docs.md @@ -1,12 +1,12 @@ --- -section: cli-commands +section: cli-commands title: npm-docs description: Docs for a package in a web browser maybe --- -# npm-docs(1) +# npm-docs(1) -## Docs for a package in a web browser maybe +## Open documentation for a package in a web browser ### Synopsis @@ -19,10 +19,10 @@ aliases: home ### Description This command tries to guess at the likely location of a package's -documentation URL, and then tries to open it using the `--browser` -config param. You can pass multiple package names at once. If no -package name is provided, it will search for a `package.json` in -the current folder and use the `name` property. +documentation URL, and then tries to open it using the `--browser` config +param. You can pass multiple package names at once. If no package name is +provided, it will search for a `package.json` in the current folder and use +the `name` property. ### Configuration @@ -45,7 +45,6 @@ Set to `true` to use default system URL opener. The base URL of the npm package registry. - ### See Also * [npm view](/cli-commands/view) diff --git a/docs/content/cli-commands/npm-doctor.md b/docs/content/cli-commands/npm-doctor.md index 60a57ea4765a2..af94c46820301 100644 --- a/docs/content/cli-commands/npm-doctor.md +++ b/docs/content/cli-commands/npm-doctor.md @@ -6,7 +6,7 @@ description: Check your environments # npm-doctor(1) -## Check your environments +## Check your npm environment ### Synopsis @@ -17,92 +17,92 @@ npm doctor ### Description `npm doctor` runs a set of checks to ensure that your npm installation has -what it needs to manage your JavaScript packages. npm is mostly a standalone tool, but it does -have some basic requirements that must be met: +what it needs to manage your JavaScript packages. npm is mostly a +standalone tool, but it does have some basic requirements that must be met: + Node.js and git must be executable by npm. -+ The primary npm registry, `registry.npmjs.com`, or another service that uses - the registry API, is available. -+ The directories that npm uses, `node_modules` (both locally and globally), - exist and can be written by the current user. ++ The primary npm registry, `registry.npmjs.com`, or another service that + uses the registry API, is available. ++ The directories that npm uses, `node_modules` (both locally and + globally), exist and can be written by the current user. + The npm cache exists, and the package tarballs within it aren't corrupt. -Without all of these working properly, npm may not work properly. Many issues -are often attributable to things that are outside npm's code base, so `npm -doctor` confirms that the npm installation is in a good state. +Without all of these working properly, npm may not work properly. Many +issues are often attributable to things that are outside npm's code base, +so `npm doctor` confirms that the npm installation is in a good state. -Also, in addition to this, there are also very many issue reports due to using -old versions of npm. Since npm is constantly improving, running `npm@latest` is -better than an old version. +Also, in addition to this, there are also very many issue reports due to +using old versions of npm. Since npm is constantly improving, running +`npm@latest` is better than an old version. -`npm doctor` verifies the following items in your environment, and if there are -any recommended changes, it will display them. +`npm doctor` verifies the following items in your environment, and if there +are any recommended changes, it will display them. #### `npm ping` -By default, npm installs from the primary npm registry, `registry.npmjs.org`. -`npm doctor` hits a special ping endpoint within the registry. This can also be -checked with `npm ping`. If this check fails, you may be using a proxy that -needs to be configured, or may need to talk to your IT staff to get access over -HTTPS to `registry.npmjs.org`. +By default, npm installs from the primary npm registry, +`registry.npmjs.org`. `npm doctor` hits a special ping endpoint within the +registry. This can also be checked with `npm ping`. If this check fails, +you may be using a proxy that needs to be configured, or may need to talk +to your IT staff to get access over HTTPS to `registry.npmjs.org`. -This check is done against whichever registry you've configured (you can see -what that is by running `npm config get registry`), and if you're using a -private registry that doesn't support the `/whoami` endpoint supported by the -primary registry, this check may fail. +This check is done against whichever registry you've configured (you can +see what that is by running `npm config get registry`), and if you're using +a private registry that doesn't support the `/whoami` endpoint supported by +the primary registry, this check may fail. #### `npm -v` While Node.js may come bundled with a particular version of npm, it's the policy of the CLI team that we recommend all users run `npm@latest` if they -can. As the CLI is maintained by a small team of contributors, there are only -resources for a single line of development, so npm's own long-term support -releases typically only receive critical security and regression fixes. The -team believes that the latest tested version of npm is almost always likely to -be the most functional and defect-free version of npm. +can. As the CLI is maintained by a small team of contributors, there are +only resources for a single line of development, so npm's own long-term +support releases typically only receive critical security and regression +fixes. The team believes that the latest tested version of npm is almost +always likely to be the most functional and defect-free version of npm. #### `node -v` For most users, in most circumstances, the best version of Node will be the latest long-term support (LTS) release. Those of you who want access to new -ECMAscript features or bleeding-edge changes to Node's standard library may be -running a newer version, and some of you may be required to run an older -version of Node because of enterprise change control policies. That's OK! But -in general, the npm team recommends that most users run Node.js LTS. +ECMAscript features or bleeding-edge changes to Node's standard library may +be running a newer version, and some may be required to run an older +version of Node because of enterprise change control policies. That's OK! +But in general, the npm team recommends that most users run Node.js LTS. #### `npm config get registry` -Some of you may be installing from private package registries for your project -or company. That's great! Others of you may be following tutorials or -StackOverflow questions in an effort to troubleshoot problems you may be -having. Sometimes, this may entail changing the registry you're pointing at. -This part of `npm doctor` just lets you, and maybe whoever's helping you with +You may be installing from private package registries for your project or +company. That's great! Others may be following tutorials or StackOverflow +questions in an effort to troubleshoot problems you may be having. +Sometimes, this may entail changing the registry you're pointing at. This +part of `npm doctor` just lets you, and maybe whoever's helping you with support, know that you're not using the default registry. #### `which git` -While it's documented in the README, it may not be obvious that npm needs Git -installed to do many of the things that it does. Also, in some cases -– especially on Windows – you may have Git set up in such a way that it's not -accessible via your `PATH` so that npm can find it. This check ensures that Git -is available. +While it's documented in the README, it may not be obvious that npm needs +Git installed to do many of the things that it does. Also, in some cases +– especially on Windows – you may have Git set up in such a way that it's +not accessible via your `PATH` so that npm can find it. This check ensures +that Git is available. #### Permissions checks * Your cache must be readable and writable by the user running npm. * Global package binaries must be writable by the user running npm. -* Your local `node_modules` path, if you're running `npm doctor` with a project - directory, must be readable and writable by the user running npm. +* Your local `node_modules` path, if you're running `npm doctor` with a + project directory, must be readable and writable by the user running npm. #### Validate the checksums of cached packages -When an npm package is published, the publishing process generates a checksum -that npm uses at install time to verify that the package didn't get corrupted -in transit. `npm doctor` uses these checksums to validate the package tarballs -in your local cache (you can see where that cache is located with `npm config -get cache`, and see what's in that cache with `npm cache ls` – probably more -than you were expecting!). In the event that there are corrupt packages in your -cache, you should probably run `npm cache clean` and reset the cache. +When an npm package is published, the publishing process generates a +checksum that npm uses at install time to verify that the package didn't +get corrupted in transit. `npm doctor` uses these checksums to validate the +package tarballs in your local cache (you can see where that cache is +located with `npm config get cache`). In the event that there are corrupt +packages in your cache, you should probably run `npm cache clean -f` and +reset the cache. ### See Also diff --git a/docs/content/cli-commands/npm-edit.md b/docs/content/cli-commands/npm-edit.md index d4b9bbb819b94..1a4d6600b35a6 100644 --- a/docs/content/cli-commands/npm-edit.md +++ b/docs/content/cli-commands/npm-edit.md @@ -11,15 +11,14 @@ description: Edit an installed package ### Synopsis ```bash -npm edit [/...] +npm edit ``` ### Description -Selects a (sub)dependency in the current -working directory and opens the package folder in the default editor -(or whatever you've configured as the npm `editor` config -- see -[`npm-config`](npm-config).) +Selects a dependency in the current project and opens the package folder in +the default editor (or whatever you've configured as the npm `editor` +config -- see [`npm-config`](npm-config).) After it has been edited, the package is rebuilt so as to pick up any changes in compiled packages. diff --git a/docs/content/cli-commands/npm-exec.md b/docs/content/cli-commands/npm-exec.md index 29b7a06e51863..921def12653c1 100644 --- a/docs/content/cli-commands/npm-exec.md +++ b/docs/content/cli-commands/npm-exec.md @@ -12,9 +12,9 @@ description: Run a command from a local or remote npm package ```bash npm exec -- [@] [args...] -npm exec -p [@] -- [args...] +npm exec --package=[@] -- [args...] npm exec -c ' [args...]' -npm exec -p foo -c ' [args...]' +npm exec --package=foo -c ' [args...]' npx [@] [args...] npx -p [@] [args...] @@ -23,7 +23,8 @@ npx -p [@] -c ' [args...]' alias: npm x, npx --p --package= (may be specified multiple times) +--package= (may be specified multiple times) +-p is a shorthand for --package only when using npx executable -c --call= (may not be mixed with positional arguments) ``` diff --git a/docs/content/cli-commands/npm-explore.md b/docs/content/cli-commands/npm-explore.md index dfa4d9c073741..f037eeb194880 100644 --- a/docs/content/cli-commands/npm-explore.md +++ b/docs/content/cli-commands/npm-explore.md @@ -1,5 +1,5 @@ - --- -section: cli-commands +--- +section: cli-commands title: npm-explore description: Browse an installed package --- diff --git a/docs/content/cli-commands/npm-fund.md b/docs/content/cli-commands/npm-fund.md index 0aa45e8bd0ed9..01d94674d442d 100644 --- a/docs/content/cli-commands/npm-fund.md +++ b/docs/content/cli-commands/npm-fund.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-fund description: Retrieve funding information --- @@ -11,22 +11,22 @@ description: Retrieve funding information ### Synopsis ```bash - npm fund [] +npm fund [] ``` ### Description -This command retrieves information on how to fund the dependencies of -a given project. If no package name is provided, it will list all -dependencies that are looking for funding in a tree-structure in which -are listed the type of funding and the url to visit. If a package name -is provided then it tries to open its funding url using the `--browser` -config param; if there are multiple funding sources for the package, the -user will be instructed to pass the `--which` command to disambiguate. +This command retrieves information on how to fund the dependencies of a +given project. If no package name is provided, it will list all +dependencies that are looking for funding in a tree structure, listing the +type of funding and the url to visit. If a package name is provided then it +tries to open its funding url using the `--browser` config param; if there +are multiple funding sources for the package, the user will be instructed +to pass the `--which` option to disambiguate. -The list will avoid duplicated entries and will stack all packages -that share the same url as a single entry. Given this nature the -list is not going to have the same shape of the output from `npm ls`. +The list will avoid duplicated entries and will stack all packages that +share the same url as a single entry. Thus, the list does not have the same +shape of the output from `npm ls`. ### Configuration @@ -65,4 +65,3 @@ If there are multiple funding sources, which 1-indexed source URL to open. * [npm config](/cli-commands/config) * [npm install](/cli-commands/install) * [npm ls](/cli-commands/ls) - diff --git a/docs/content/cli-commands/npm-help-search.md b/docs/content/cli-commands/npm-help-search.md index 9678185655138..e69f0ccf31f67 100644 --- a/docs/content/cli-commands/npm-help-search.md +++ b/docs/content/cli-commands/npm-help-search.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-help-search description: Search npm help documentation --- @@ -16,14 +16,14 @@ npm help-search ### Description -This command will search the npm markdown documentation files for the -terms provided, and then list the results, sorted by relevance. +This command will search the npm markdown documentation files for the terms +provided, and then list the results, sorted by relevance. If only one result is found, then it will show that help topic. -If the argument to `npm help` is not a known help topic, then it will -call `help-search`. It is rarely if ever necessary to call this -command directly. +If the argument to `npm help` is not a known help topic, then it will call +`help-search`. It is rarely if ever necessary to call this command +directly. ### Configuration diff --git a/docs/content/cli-commands/npm-help.md b/docs/content/cli-commands/npm-help.md index 358010c05ece3..8d83c319e95d9 100644 --- a/docs/content/cli-commands/npm-help.md +++ b/docs/content/cli-commands/npm-help.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-help description: Get help on npm --- @@ -18,10 +18,10 @@ npm help [] If supplied a topic, then show the appropriate documentation page. -If the topic does not exist, or if multiple terms are provided, then run -the `help-search` command to find a match. Note that, if `help-search` -finds a single subject, then it will run `help` on that topic, so unique -matches are equivalent to specifying a topic name. +If the topic does not exist, or if multiple terms are provided, then npm +will run the `help-search` command to find a match. Note that, if +`help-search` finds a single subject, then it will run `help` on that +topic, so unique matches are equivalent to specifying a topic name. ### Configuration diff --git a/docs/content/cli-commands/npm-hook.md b/docs/content/cli-commands/npm-hook.md index ce4bbccb3593b..f3189a64882c3 100644 --- a/docs/content/cli-commands/npm-hook.md +++ b/docs/content/cli-commands/npm-hook.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-hook description: Manage registry hooks --- @@ -17,64 +17,74 @@ npm hook update [secret] npm hook rm ``` +### Description + +Allows you to manage [npm +hooks](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm), +including adding, removing, listing, and updating. + +Hooks allow you to configure URL endpoints that will be notified whenever a +change happens to any of the supported entity types. Three different types +of entities can be watched by hooks: packages, owners, and scopes. + +To create a package hook, simply reference the package name. + +To create an owner hook, prefix the owner name with `~` (as in, +`~youruser`). + +To create a scope hook, prefix the scope name with `@` (as in, +`@yourscope`). + +The hook `id` used by `update` and `rm` are the IDs listed in `npm hook ls` +for that particular hook. + +The shared secret will be sent along to the URL endpoint so you can verify +the request came from your own configured hook. + ### Example Add a hook to watch a package for changes: + ```bash $ npm hook add lodash https://example.com/ my-shared-secret ``` Add a hook to watch packages belonging to the user `substack`: + ```bash $ npm hook add ~substack https://example.com/ my-shared-secret ``` Add a hook to watch packages in the scope `@npm` + ```bash $ npm hook add @npm https://example.com/ my-shared-secret ``` List all your active hooks: + ```bash $ npm hook ls ``` List your active hooks for the `lodash` package: + ```bash $ npm hook ls lodash ``` Update an existing hook's url: + ```bash $ npm hook update id-deadbeef https://my-new-website.here/ ``` Remove a hook: + ```bash $ npm hook rm id-deadbeef ``` -### Description - -Allows you to manage [npm hooks](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm), -including adding, removing, listing, and updating. - -Hooks allow you to configure URL endpoints that will be notified whenever a -change happens to any of the supported entity types. Three different types of -entities can be watched by hooks: packages, owners, and scopes. - -To create a package hook, simply reference the package name. - -To create an owner hook, prefix the owner name with `~` (as in, `~youruser`). - -To create a scope hook, prefix the scope name with `@` (as in, `@yourscope`). - -The hook `id` used by `update` and `rm` are the IDs listed in `npm hook ls` for -that particular hook. - -The shared secret will be sent along to the URL endpoint so you can verify the -request came from your own configured hook. - ### See Also * ["Introducing Hooks" blog post](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm) diff --git a/docs/content/cli-commands/npm-init.md b/docs/content/cli-commands/npm-init.md index d88637cdf590f..b3886078954c1 100644 --- a/docs/content/cli-commands/npm-init.md +++ b/docs/content/cli-commands/npm-init.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-init description: create a package.json file --- @@ -9,26 +9,60 @@ description: create a package.json file ## create a package.json file ### Synopsis + ```bash npm init [--force|-f|--yes|-y|--scope] npm init <@scope> (same as `npx <@scope>/create`) npm init [<@scope>/] (same as `npx [<@scope>/]create-`) ``` +### Description + +`npm init ` can be used to set up a new or existing npm +package. + +`initializer` in this case is an npm package named `create-`, +which will be installed by [`npx`](https://npm.im/npx), and then have its +main bin executed -- presumably creating or updating `package.json` and +running any other initialization-related operations. + +The init command is transformed to a corresponding `npx` operation as +follows: + +* `npm init foo` -> `npx create-foo` +* `npm init @usr/foo` -> `npx @usr/create-foo` +* `npm init @usr` -> `npx @usr/create` + +Any additional options will be passed directly to the command, so `npm init +foo -- --hello` will map to `npx create-foo --hello`. + +If the initializer is omitted (by just calling `npm init`), init will fall +back to legacy init behavior. It will ask you a bunch of questions, and +then write a package.json for you. It will attempt to make reasonable +guesses based on existing fields, dependencies, and options selected. It is +strictly additive, so it will keep any fields and values that were already +set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If +you pass `--scope`, it will create a scoped package. + ### Examples -Create a new React-based project using [`create-react-app`](https://npm.im/create-react-app): +Create a new React-based project using +[`create-react-app`](https://npm.im/create-react-app): + ```bash $ npm init react-app ./my-react-app ``` -Create a new `esm`-compatible package using [`create-esm`](https://npm.im/create-esm): +Create a new `esm`-compatible package using +[`create-esm`](https://npm.im/create-esm): + ```bash $ mkdir my-esm-lib && cd my-esm-lib $ npm init esm --yes ``` Generate a plain old package.json using legacy init: + ```bash $ mkdir my-npm-pkg && cd my-npm-pkg $ git init @@ -36,39 +70,14 @@ $ npm init ``` Generate it without having it ask any questions: + ```bash $ npm init -y ``` -### Description - -`npm init ` can be used to set up a new or existing npm package. - -`initializer` in this case is an npm package named `create-`, which -will be installed by [`npx`](https://npm.im/npx), and then have its main bin -executed -- presumably creating or updating `package.json` and running any other -initialization-related operations. - -The init command is transformed to a corresponding `npx` operation as follows: - -* `npm init foo` -> `npx create-foo` -* `npm init @usr/foo` -> `npx @usr/create-foo` -* `npm init @usr` -> `npx @usr/create` - -Any additional options will be passed directly to the command, so `npm init foo ---hello` will map to `npx create-foo --hello`. - -If the initializer is omitted (by just calling `npm init`), init will fall back -to legacy init behavior. It will ask you a bunch of questions, and then write a -package.json for you. It will attempt to make reasonable guesses based on -existing fields, dependencies, and options selected. It is strictly additive, so -it will keep any fields and values that were already set. You can also use -`-y`/`--yes` to skip the questionnaire altogether. If you pass `--scope`, it -will create a scoped package. - ### See Also -* +* [init-package-json module](http://npm.im/init-package-json) * [package.json](/configuring-npm/package-json) * [npm version](/cli-commands/version) * [npm scope](/using-npm/scope) diff --git a/docs/content/cli-commands/npm-install-ci-test.md b/docs/content/cli-commands/npm-install-ci-test.md index 09d738c79fbed..7ea4038e154fd 100644 --- a/docs/content/cli-commands/npm-install-ci-test.md +++ b/docs/content/cli-commands/npm-install-ci-test.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-install-ci-test description: Install a project with a clean slate and run tests --- @@ -18,9 +18,10 @@ alias: npm cit ### Description -This command runs an `npm ci` followed immediately by an `npm test`. +This command runs `npm ci` followed immediately by `npm test`. ### See Also +* [npm install-test](/cli-commands/install-test) * [npm ci](/cli-commands/ci) * [npm test](/cli-commands/test) diff --git a/docs/content/cli-commands/npm-install-test.md b/docs/content/cli-commands/npm-install-test.md index 58b8844b4fcff..2cac23f74e76e 100644 --- a/docs/content/cli-commands/npm-install-test.md +++ b/docs/content/cli-commands/npm-install-test.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-install-test description: Install package(s) and run tests --- @@ -32,4 +32,5 @@ takes exactly the same arguments as `npm install`. ### See Also * [npm install](/cli-commands/install) +* [npm install-ci-test](/cli-commands/install-ci-test) * [npm test](/cli-commands/test) diff --git a/docs/content/cli-commands/npm-install.md b/docs/content/cli-commands/npm-install.md index 20ae45850d81c..7b4b9317c6c54 100644 --- a/docs/content/cli-commands/npm-install.md +++ b/docs/content/cli-commands/npm-install.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-install description: Install a package --- @@ -30,30 +30,34 @@ common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional|--save-peer] [- ### Description This command installs a package and any packages that it depends on. If the -package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, the -installation of dependencies will be driven by that, respecting the following -order of precedence: +package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, +the installation of dependencies will be driven by that, respecting the +following order of precedence: * `npm-shrinkwrap.json` * `package-lock.json` * `yarn.lock` -See [package-lock.json](/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/cli-commands/shrinkwrap). +See [package-lock.json](/configuring-npm/package-lock-json) and [`npm +shrinkwrap`](/cli-commands/shrinkwrap). A `package` is: -* a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file +* a) a folder containing a program described by a + [`package.json`](/configuring-npm/package-json) file * b) a gzipped tarball containing (a) * c) a url that resolves to (b) -* d) a `@` that is published on the registry (see [`registry`](/using-npm/registry)) with (c) -* e) a `@` (see [`npm dist-tag`](/cli-commands/dist-tag)) that points to (d) +* d) a `@` that is published on the registry (see + [`registry`](/using-npm/registry)) with (c) +* e) a `@` (see [`npm dist-tag`](/cli-commands/dist-tag)) that + points to (d) * f) a `` that has a "latest" tag satisfying (e) * g) a `` that resolves to (a) -Even if you never publish your package, you can still get a lot of -benefits of using npm if you just want to write a node program (a), and -perhaps if you also want to be able to easily install it elsewhere -after packing it up into a tarball (b). +Even if you never publish your package, you can still get a lot of benefits +of using npm if you just want to write a node program (a), and perhaps if +you also want to be able to easily install it elsewhere after packing it up +into a tarball (b). * `npm install` (in a package directory, no arguments): @@ -64,40 +68,47 @@ after packing it up into a tarball (b). it installs the current package context (ie, the current working directory) as a global package. - By default, `npm install` will install all modules listed as dependencies - in [`package.json`](/configuring-npm/package-json). + By default, `npm install` will install all modules listed as + dependencies in [`package.json`](/configuring-npm/package-json). - With the `--production` flag (or when the `NODE_ENV` environment variable - is set to `production`), npm will not install modules listed in - `devDependencies`. To install all modules listed in both `dependencies` - and `devDependencies` when `NODE_ENV` environment variable is set to `production`, - you can use `--production=false`. + With the `--production` flag (or when the `NODE_ENV` environment + variable is set to `production`), npm will not install modules listed + in `devDependencies`. To install all modules listed in both + `dependencies` and `devDependencies` when `NODE_ENV` environment + variable is set to `production`, you can use `--production=false`. > NOTE: The `--production` flag has no particular meaning when adding a dependency to a project. * `npm install `: - Install the package in the directory as a symlink in the current project. - Its dependencies will be installed before it's linked. If `` sits - inside the root of your project, its dependencies may be hoisted to the - top-level `node_modules` as they would for other types of dependencies. + Install the package in the directory as a symlink in the current + project. Its dependencies will be installed before it's linked. If + `` sits inside the root of your project, its dependencies may + be hoisted to the top-level `node_modules` as they would for other + types of dependencies. * `npm install `: - Install a package that is sitting on the filesystem. Note: if you just want - to link a dev directory into your npm root, you can do this more easily by - using [`npm link`](/cli-commands/npm-link). + Install a package that is sitting on the filesystem. Note: if you just + want to link a dev directory into your npm root, you can do this more + easily by using [`npm link`](/cli-commands/npm-link). Tarball requirements: - * The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as - the extension. - * The package contents should reside in a subfolder inside the tarball (usually it is called `package/`). npm strips one directory layer when installing the package (an equivalent of `tar x --strip-components=1` is run). - * The package must contain a `package.json` file with `name` and `version` properties. + * The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as the + extension. + * The package contents should reside in a subfolder inside the tarball + (usually it is called `package/`). npm strips one directory layer + when installing the package (an equivalent of `tar x + --strip-components=1` is run). + * The package must contain a `package.json` file with `name` and + `version` properties. Example: - npm install ./package.tgz + ```bash + npm install ./package.tgz + ``` * `npm install `: @@ -106,7 +117,9 @@ after packing it up into a tarball (b). Example: - npm install https://github.com/indexzero/forever/tarball/v0.5.6 + ```bash + npm install https://github.com/indexzero/forever/tarball/v0.5.6 + ``` * `npm install [<@scope>/]`: @@ -118,18 +131,21 @@ after packing it up into a tarball (b). Example: - npm install sax + ```bash + npm install sax + ``` `npm install` saves any specified packages into `dependencies` by default. Additionally, you can control where and how they get saved with some additional flags: - * `-P, --save-prod`: Package will appear in your `dependencies`. This is the - default unless `-D` or `-O` are present. + * `-P, --save-prod`: Package will appear in your `dependencies`. This + is the default unless `-D` or `-O` are present. * `-D, --save-dev`: Package will appear in your `devDependencies`. - * `-O, --save-optional`: Package will appear in your `optionalDependencies`. + * `-O, --save-optional`: Package will appear in your + `optionalDependencies`. * `--no-save`: Prevents saving to `dependencies`. @@ -137,17 +153,18 @@ after packing it up into a tarball (b). package.json, there are two additional, optional flags: * `-E, --save-exact`: Saved dependencies will be configured with an - exact version rather than using npm's default semver range - operator. + exact version rather than using npm's default semver range operator. - * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list. + * `-B, --save-bundle`: Saved dependencies will also be added to your + `bundleDependencies` list. - Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it - will be updated as well. + Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` + then it will be updated as well. `` is optional. The package will be downloaded from the registry associated with the specified scope. If no registry is associated with - the given scope the default registry is assumed. See [`scope`](/using-npm/scope). + the given scope the default registry is assumed. See + [`scope`](/using-npm/scope). Note: if you do not include the @-symbol on your scope name, npm will interpret this as a GitHub repository instead, see below. Scopes names @@ -181,11 +198,12 @@ after packing it up into a tarball (b). Examples: - npm install my-react@npm:react - npm install jquery2@npm:jquery@2 - npm install jquery3@npm:jquery@3 - npm install npa@npm:npm-package-arg - + ```bash + npm install my-react@npm:react + npm install jquery2@npm:jquery@2 + npm install jquery3@npm:jquery@3 + npm install npa@npm:npm-package-arg + ``` * `npm install [<@scope>/]@`: @@ -214,13 +232,15 @@ after packing it up into a tarball (b). * `npm install [<@scope>/]@`: - Install a version of the package matching the specified version range. This - will follow the same rules for resolving dependencies described in [`package.json`](/configuring-npm/package-json). + Install a version of the package matching the specified version range. + This will follow the same rules for resolving dependencies described in + [`package.json`](/configuring-npm/package-json). - Note that most version ranges must be put in quotes so that your shell will - treat it as a single argument. + Note that most version ranges must be put in quotes so that your shell + will treat it as a single argument. Example: + ```bash npm install sax@">=0.1.0 <0.2.0" npm install @myorg/privatepackage@"16 - 17" @@ -228,32 +248,33 @@ after packing it up into a tarball (b). * `npm install `: - Installs the package from the hosted git provider, cloning it with `git`. - For a full git remote url, only that URL will be attempted. + Installs the package from the hosted git provider, cloning it with + `git`. For a full git remote url, only that URL will be attempted. ```bash - ://[[:]@][:][:][/][# | #semver:] + ://[[:]@][:][:][/][# | #semver:] ``` `` is one of `git`, `git+ssh`, `git+http`, `git+https`, or `git+file`. If `#` is provided, it will be used to clone exactly that - commit. If the commit-ish has the format `#semver:`, `` can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither `#` or `#semver:` is - specified, then the default branch of the repository is used. + commit. If the commit-ish has the format `#semver:`, `` + can be any valid semver range or exact version, and npm will look for + any tags or refs matching that range in the remote repository, much as + it would for a registry dependency. If neither `#` or + `#semver:` is specified, then the default branch of the + repository is used. - If the repository makes use of submodules, those submodules will be cloned - as well. + If the repository makes use of submodules, those submodules will be + cloned as well. If the package being installed contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed. - The following git environment variables are recognized by npm and will be - added to the environment when running git: + The following git environment variables are recognized by npm and will + be added to the environment when running git: * `GIT_ASKPASS` * `GIT_EXEC_PATH` @@ -283,18 +304,18 @@ after packing it up into a tarball (b). attempting to clone it using `git`. If `#` is provided, it will be used to clone exactly that - commit. If the commit-ish has the format `#semver:`, `` can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither `#` or `#semver:` is - specified, then `master` is used. + commit. If the commit-ish has the format `#semver:`, `` + can be any valid semver range or exact version, and npm will look for + any tags or refs matching that range in the remote repository, much as + it would for a registry dependency. If neither `#` or + `#semver:` is specified, then `master` is used. - As with regular git dependencies, `dependencies` and `devDependencies` will - be installed if the package has a `prepare` script before the package is - done installing. + As with regular git dependencies, `dependencies` and `devDependencies` + will be installed if the package has a `prepare` script before the + package is done installing. Examples: - + ```bash npm install mygithubuser/myproject npm install github:mygithubuser/myproject @@ -311,7 +332,7 @@ after packing it up into a tarball (b). done installing. Example: - + ```bash npm install gist:101a11beef ``` @@ -333,7 +354,7 @@ after packing it up into a tarball (b). done installing. Example: - + ```bash npm install bitbucket:mybitbucketuser/myproject ``` @@ -355,7 +376,7 @@ after packing it up into a tarball (b). done installing. Example: - + ```bash npm install gitlab:mygitlabuser/myproject npm install gitlab:myusr/myproj#semver:^5.0 @@ -368,82 +389,117 @@ For example: npm install sax@">=0.1.0 <0.2.0" bench supervisor ``` -The `--tag` argument will apply to all of the specified install targets. If a -tag with the given name exists, the tagged version is preferred over newer -versions. +The `--tag` argument will apply to all of the specified install targets. If +a tag with the given name exists, the tagged version is preferred over +newer versions. -The `--dry-run` argument will report in the usual way what the install would -have done without actually installing anything. +The `--dry-run` argument will report in the usual way what the install +would have done without actually installing anything. -The `--package-lock-only` argument will only update the `package-lock.json`, -instead of checking `node_modules` and downloading dependencies. +The `--package-lock-only` argument will only update the +`package-lock.json`, instead of checking `node_modules` and downloading +dependencies. -The `-f` or `--force` argument will force npm to fetch remote resources even if a -local copy exists on disk. +The `-f` or `--force` argument will force npm to fetch remote resources +even if a local copy exists on disk. ```bash npm install sax --force ``` -The `-g` or `--global` argument will cause npm to install the package globally -rather than locally. See [folders](/configuring-npm/folders). +### Configuration + +See the [`config`](/using-npm/config) help doc. Many of the configuration +params have some effect on installation, since that's most of what npm +does. + +These are some of the most common options related to installation. + +#### Configuration Options Affecting Dependency Resolution And Tree Design + +* `-g` or `--global`: install the package globally rather than locally. + See [folders](/configuring-npm/folders). + +* `--global-style`: install the package into your local `node_modules` + folder with the same layout it uses with the global `node_modules` + folder. Only your direct dependencies will show in `node_modules` and + everything they depend on will be flattened in their `node_modules` + folders. This obviously will eliminate some deduping. + +* `--legacy-bundling`: install the package in the style of versions of npm + prior to 1.4, where dependencies are not automatically deduped up to the + shallowest level in the tree possible. This is extremely + disk-inefficient. + +* `--legacy-peer-deps`: ignore all `peerDependencies` when installing, in + the style of npm version 4 through version 6. + +* `--strict-peer-deps`: fail and abort the install process for any + conflicting peerDependencies when encountered. By default, npm will only + crash for peerDependencies conflicts caused by the direct dependencies of + the root project. + +* `--no-package-lock` (alias: `--no-shrinkwrap`): do not read the + lockfile (`package-lock.json` or `npm-shrinkwrap.json`) for the intended + package tree, and do not save the resulting package tree back to a + lockfile. + +#### Omitting Dependency Types + +You may omit certain types of dependencies by using the `--omit=` +config option. This may be specified multiple types on the command line. +To enter `omit` options in `.npmrc` files, use the following syntax: + +```ini +omit[] = dev +omit[] = optional +; etc... +``` -The `--global-style` argument will cause npm to install the package into -your local `node_modules` folder with the same layout it uses with the -global `node_modules` folder. Only your direct dependencies will show in -`node_modules` and everything they depend on will be flattened in their -`node_modules` folders. This obviously will eliminate some deduping. +The dependency types that may be omitted or included are: -The `--ignore-scripts` argument will cause npm to not execute any -scripts defined in the package.json. See [`scripts`](/using-npm/scripts). +* `peer`: any `peerDependencies`, including those with a + `peerDependenciesMeta` entry specifying `optional: true` +* `optional`: dependencies listed in `optionalDependencies` +* `dev`: dependencies listed in `devDependencies` -The `--legacy-bundling` argument will cause npm to install the package such -that versions of npm prior to 1.4, such as the one included with node 0.8, -can install the package. This eliminates all automatic deduping. +To re-include dependency, use the `--include` option, which may also be +specified multiple times. -The `--legacy-peer-deps` argument will cause npm to ignore all -`peerDependencies` when installing, similar to npm@6 and older. +Legacy shorthands for `omit` settings are: -The `--link` argument will cause npm to link global installs into the -local space whenever packages from the global space may satisfy a dependency -required version. +* `--no-optional`: prevent optionalDependencies from being installed. Note + that their presence is still entered in the `package-lock.json` file, and + the tree is designed such that they _can_ be installed in the future. -The `--no-audit` argument can be used to disable sending audit reports to -the configured registries. See [`npm-audit`](npm-audit) for details on what -is sent. +* `--prod`: prevent devDependencies from being installed. -The `--no-bin-links` argument will prevent npm from creating symlinks for -any binaries the package might contain. +* `--only=prod`: omit `devDependencies` -The `--no-fund` argument will hide the message displayed at the end of each -install that acknowledges the number of dependencies looking for funding. -See [`npm-fund`](/cli-commands/npm-fund) +* `--also=dev`: include `devDependencies` -The `--no-optional` argument will prevent optional dependencies from -being installed. +#### Configuration Options Affecting Build Process -The `--no-shrinkwrap` argument, which will ignore an available -package-lock or shrinkwrap file and use the package.json instead. +* `--ignore-scripts`: do not execute any scripts defined in the + package.json. See [`scripts`](/using-npm/scripts). -The `--no-package-lock` argument will prevent npm from creating a -`package-lock.json` file. When running with package-lock's disabled npm -will not automatically prune your node modules when installing. +* `--no-audit`: disable sending audit reports to the configured registries. + See [`npm-audit`](npm-audit) for details on what is sent. -The `--nodedir=/path/to/node/source` argument will allow npm to find the -node source code so that npm can compile native modules. +* `--no-bin-links`: prevent npm from creating symlinks for any binaries the + package might contain. -The `--only={prod[uction]|dev[elopment]}` argument will cause either only -`devDependencies` or only non-`devDependencies` to be installed regardless -of the `NODE_ENV`. +* `--no-fund`: suppress the message displayed at the end of each install + that acknowledges the number of dependencies looking for funding. See + [`npm-fund`](/cli-commands/npm-fund) -The `--strict-peer-deps` argument will cause the install to fail on any -`peerDependencies` conflict, even if it's possible to use a heuristic to -provide a least-surprising resolution to a given conflict. +* `--dry-run`: Do not actually install anything into the `node_modules` + folder. Just build the intended tree in memory, and report on it. -See [`config`](/using-npm/config). Many of the configuration params have some -effect on installation, since that's most of what npm does. +* `--no-save`: Do not save installed dependencies to `package.json` or + `package-lock.json`. -#### Algorithm +### Algorithm Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`, the npm install algorithm produces: @@ -455,9 +511,9 @@ A +-- D ``` -That is, the dependency from B to C is satisfied by the fact that A -already caused C to be installed at a higher level. D is still installed -at the top level because nothing conflicts with it. +That is, the dependency from B to C is satisfied by the fact that A already +caused C to be installed at a higher level. D is still installed at the top +level because nothing conflicts with it. For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces: @@ -469,13 +525,13 @@ A +-- D@1 ``` -Because B's D@1 will be installed in the top-level, C now has to install D@2 -privately for itself. This algorithm is deterministic, but different trees may -be produced if two dependencies are requested for installation in a different -order. +Because B's D@1 will be installed in the top-level, C now has to install +D@2 privately for itself. This algorithm is deterministic, but different +trees may be produced if two dependencies are requested for installation in +a different order. -See [folders](/configuring-npm/folders) for a more detailed description of the -specific folder structures that npm creates. +See [folders](/configuring-npm/folders) for a more detailed description of +the specific folder structures that npm creates. ### See Also diff --git a/docs/content/cli-commands/npm-link.md b/docs/content/cli-commands/npm-link.md index 3f513868dfebd..c4b0f0e910745 100644 --- a/docs/content/cli-commands/npm-link.md +++ b/docs/content/cli-commands/npm-link.md @@ -1,5 +1,5 @@ --- -section: cli-commands +section: cli-commands title: npm-link description: Symlink a package folder --- diff --git a/lib/utils/flat-options.js b/lib/utils/flat-options.js index 721bbbde76651..1e169535ab8f0 100644 --- a/lib/utils/flat-options.js +++ b/lib/utils/flat-options.js @@ -164,7 +164,9 @@ const flatOptions = npm => npm.flatOptions || Object.freeze({ // configs that affect how we build trees binLinks: npm.config.get('bin-links'), rebuildBundle: npm.config.get('rebuild-bundle'), - packageLock: npm.config.get('package-lock'), + // --no-shrinkwrap is the same as --no-package-lock + packageLock: npm.config.get('package-lock') === false || + npm.config.get('shrinkwrap') === false ? false : true, packageLockOnly: npm.config.get('package-lock-only'), globalStyle: npm.config.get('global-style'), legacyBundling: npm.config.get('legacy-bundling'),