From 279ea215ca597a6c1c8975abc59dfc2ed3297af1 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Sat, 4 Oct 2025 20:17:35 -0400 Subject: [PATCH 1/2] chore: Unwrap markdown docs Visual Studio Code search and replace. Search: (^[^`#\n][^\n]*[^-.:?!>\n]$)\n\s*([^-<\s\n`+|#*]) Replace: $1 $2 Flags: Case-sensitive, Regular expression Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- docs/lib/content/commands/npm-doctor.md | 27 +++++++++---------------- 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/docs/lib/content/commands/npm-doctor.md b/docs/lib/content/commands/npm-doctor.md index c7f09a818c2bb..3a007b4ee80f1 100644 --- a/docs/lib/content/commands/npm-doctor.md +++ b/docs/lib/content/commands/npm-doctor.md @@ -14,15 +14,12 @@ description: Check the health of your npm environment 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. +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. @@ -37,11 +34,9 @@ By default, npm installs from the primary npm registry, `registry.npmjs.org`. `npm doctor` hits a special connection testing endpoint within the registry. This can also be checked with `npm ping`. -If this check fails, you may be using a proxy that needs to be configured, or may need to talk to your IT staff to get access over -HTTPS to `registry.npmjs.org`. +If this check fails, you may be using a proxy that needs to be configured, or may need to talk to your IT staff to get access over HTTPS to `registry.npmjs.org`. -This check is done against whichever registry you've configured (you can see what that is by running `npm config get registry`), and if you're using -a private registry that doesn't support the `/whoami` endpoint supported by the primary registry, this check may fail. +This check is done against whichever registry you've configured (you can see what that is by running `npm config get registry`), and if you're using a private registry that doesn't support the `/whoami` endpoint supported by the primary registry, this check may fail. #### `Checking npm version` @@ -52,8 +47,7 @@ The team believes that the latest tested version of npm is almost always likely #### `Checking node version` For most users, in most circumstances, the best version of Node will be the latest long-term support (LTS) release. -Those of you who want access to new -ECMAscript features or bleeding-edge changes to Node's standard library may be running a newer version, and some may be required to run an older version of Node because of enterprise change control policies. +Those of you who want access to new ECMAscript features or bleeding-edge changes to Node's standard library may be running a newer version, and some may be required to run an older version of Node because of enterprise change control policies. That's OK! But in general, the npm team recommends that most users run Node.js LTS. @@ -66,18 +60,15 @@ This part of `npm doctor` just lets you, and maybe whoever's helping you with su #### `Checking for git executable in PATH` -While it's documented in the README, it may not be obvious that npm needs -Git installed to do many of the things that it does. -Also, in some cases -– especially on Windows – you may have Git set up in such a way that it's not accessible via your `PATH` so that npm can find it. +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 From a5eb025ebf5ad8e40b8a8ca4002dc41c7c8486c1 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Sat, 4 Oct 2025 20:50:52 -0400 Subject: [PATCH 2/2] chore: Unwrap markdown docs Visual Studio Code search and replace. Search: (^(?!title|section| *```|/[*/]|\s*[{}])[^`#\n;][^\n]*[^-.:?!>\n\s{]) *$\n *(?!npm install|cd |\d+\.)([^-<$\s\n`+|#*;]) Replace: $1 $2 Flags: Case-sensitive, Regular expression Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- docs/lib/content/commands/npm-access.md | 6 +- docs/lib/content/commands/npm-audit.md | 3 +- docs/lib/content/commands/npm-ci.md | 12 ++-- docs/lib/content/commands/npm-config.md | 3 +- docs/lib/content/commands/npm-dedupe.md | 3 +- docs/lib/content/commands/npm-deprecate.md | 6 +- docs/lib/content/commands/npm-docs.md | 3 +- docs/lib/content/commands/npm-edit.md | 3 +- docs/lib/content/commands/npm-fund.md | 6 +- docs/lib/content/commands/npm-init.md | 18 ++--- docs/lib/content/commands/npm-install.md | 12 ++-- docs/lib/content/commands/npm-link.md | 12 ++-- docs/lib/content/commands/npm-login.md | 3 +- docs/lib/content/commands/npm-org.md | 3 +- docs/lib/content/commands/npm-owner.md | 15 ++-- docs/lib/content/commands/npm-pkg.md | 4 +- docs/lib/content/commands/npm-prefix.md | 3 +- docs/lib/content/commands/npm-profile.md | 31 +++------ docs/lib/content/commands/npm-publish.md | 40 ++++------- docs/lib/content/commands/npm-repo.md | 3 +- docs/lib/content/commands/npm-run.md | 25 +++---- docs/lib/content/commands/npm-sbom.md | 3 +- docs/lib/content/commands/npm-shrinkwrap.md | 3 +- docs/lib/content/commands/npm-star.md | 3 +- docs/lib/content/commands/npm-start.md | 3 +- docs/lib/content/commands/npm-test.md | 3 +- docs/lib/content/commands/npm-uninstall.md | 3 +- docs/lib/content/commands/npm-unpublish.md | 12 ++-- docs/lib/content/commands/npm-unstar.md | 3 +- docs/lib/content/commands/npm-update.md | 9 +-- docs/lib/content/commands/npm-view.md | 3 +- docs/lib/content/commands/npm.md | 3 +- docs/lib/content/commands/npx.md | 43 ++++-------- docs/lib/content/configuring-npm/install.md | 24 +++---- .../configuring-npm/npm-shrinkwrap-json.md | 4 +- docs/lib/content/configuring-npm/npmrc.md | 15 ++-- .../content/configuring-npm/package-json.md | 15 ++-- docs/lib/content/using-npm/config.md | 21 ++---- docs/lib/content/using-npm/logging.md | 3 +- docs/lib/content/using-npm/package-spec.md | 6 +- docs/lib/content/using-npm/registry.md | 32 +++------ docs/lib/content/using-npm/removal.md | 6 +- docs/lib/content/using-npm/scope.md | 60 +++++----------- docs/lib/content/using-npm/scripts.md | 68 ++++++------------- docs/lib/content/using-npm/workspaces.md | 21 ++---- 45 files changed, 185 insertions(+), 395 deletions(-) diff --git a/docs/lib/content/commands/npm-access.md b/docs/lib/content/commands/npm-access.md index 5ad8ccca246cd..6b846e9158f6f 100644 --- a/docs/lib/content/commands/npm-access.md +++ b/docs/lib/content/commands/npm-access.md @@ -15,8 +15,7 @@ Used to set access controls on private packages. For all of the subcommands, `npm access` will perform actions on the packages in the current working directory if no package name is passed to the subcommand. * grant / revoke: - Add or remove the ability of users and teams to have read-only or read-write - access to a package. + Add or remove the ability of users and teams to have read-only or read-write access to a package. ### Details @@ -30,8 +29,7 @@ You must have privileges to set the access of a package: * You are an owner of an unscoped or scoped package. * You are a member of the team that owns a scope. -* You have been given read-write privileges for a package, either as a member - of a team or directly as an owner. +* You have been given read-write privileges for a package, either as a member of a team or directly as an owner. If you have two-factor authentication enabled then you'll be prompted to provide a second factor, or may use the `--otp=...` option to specify it on the command line. diff --git a/docs/lib/content/commands/npm-audit.md b/docs/lib/content/commands/npm-audit.md index c51c722ef86f7..6cd26b1406b4a 100644 --- a/docs/lib/content/commands/npm-audit.md +++ b/docs/lib/content/commands/npm-audit.md @@ -145,8 +145,7 @@ If remediations do not require changes to the dependency ranges, then all vulner The `npm audit` command will exit with a 0 exit code if no vulnerabilities were found. The `npm audit fix` command will exit with 0 exit code if no vulnerabilities are found _or_ if the remediation is able to successfully fix all vulnerabilities. -If vulnerabilities were found the exit code will depend on the -[`audit-level` config](/using-npm/config#audit-level). +If vulnerabilities were found the exit code will depend on the [`audit-level` config](/using-npm/config#audit-level). ### Examples diff --git a/docs/lib/content/commands/npm-ci.md b/docs/lib/content/commands/npm-ci.md index 4bddcb402862b..7c59b39c86a1c 100644 --- a/docs/lib/content/commands/npm-ci.md +++ b/docs/lib/content/commands/npm-ci.md @@ -10,8 +10,7 @@ description: Clean install a project ### Description -This command is similar to [`npm install`](/commands/npm-install), except it's meant to be used in automated environments such as test platforms, -continuous integration, and deployment -- or any situation where you want to make sure you're doing a clean install of your dependencies. +This command is similar to [`npm install`](/commands/npm-install), except it's meant to be used in automated environments such as test platforms, continuous integration, and deployment -- or any situation where you want to make sure you're doing a clean install of your dependencies. The main differences between using `npm install` and `npm ci` are: @@ -19,15 +18,12 @@ The main differences between using `npm install` and `npm ci` are: `npm-shrinkwrap.json`. * If dependencies in the package lock do not match those in `package.json`, `npm ci` will exit with an error, instead of updating the package lock. -* `npm ci` can only install entire projects at a time: individual - dependencies cannot be added with this command. -* If a `node_modules` is already present, it will be automatically removed - before `npm ci` begins its install. +* `npm ci` can only install entire projects at a time: individual dependencies cannot be added with this command. +* If a `node_modules` is already present, it will be automatically removed before `npm ci` begins its install. * It will never write to `package.json` or any of the package-locks: installs are essentially frozen. -NOTE: If you create your `package-lock.json` file by running `npm install` -with flags that can affect the shape of your dependency tree, such as +NOTE: If you create your `package-lock.json` file by running `npm install` with flags that can affect the shape of your dependency tree, such as `--legacy-peer-deps` or `--install-links`, you _must_ provide the same flags to `npm ci` or you are likely to encounter errors. An easy way to do this is to run, for example, `npm config set legacy-peer-deps=true --location=project` and commit the diff --git a/docs/lib/content/commands/npm-config.md b/docs/lib/content/commands/npm-config.md index 965eeeb01e628..831876bac290d 100644 --- a/docs/lib/content/commands/npm-config.md +++ b/docs/lib/content/commands/npm-config.md @@ -57,8 +57,7 @@ npm config list Show all the config settings. Use `-l` to also show defaults. -Use `--json` -to show the settings in json format. +Use `--json` to show the settings in json format. #### delete diff --git a/docs/lib/content/commands/npm-dedupe.md b/docs/lib/content/commands/npm-dedupe.md index 21ea4b64bcd03..754f84f6c5317 100644 --- a/docs/lib/content/commands/npm-dedupe.md +++ b/docs/lib/content/commands/npm-dedupe.md @@ -44,8 +44,7 @@ a ``` 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. +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. diff --git a/docs/lib/content/commands/npm-deprecate.md b/docs/lib/content/commands/npm-deprecate.md index 143b892637cee..183c65113a160 100644 --- a/docs/lib/content/commands/npm-deprecate.md +++ b/docs/lib/content/commands/npm-deprecate.md @@ -18,8 +18,7 @@ It works on [version ranges](https://semver.npmjs.com/) as well as specific vers npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" ``` -SemVer ranges passed to this command are interpreted such that they *do* -include prerelease versions. +SemVer ranges passed to this command are interpreted such that they *do* include prerelease versions. For example: ```bash @@ -31,8 +30,7 @@ In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated. You must be the package owner to deprecate something. See the `owner` and `adduser` help topics. -To un-deprecate a package, specify an empty string (`""`) for the `message` -argument. +To un-deprecate a package, specify an empty string (`""`) for the `message` argument. Note that you must use double quotes with no space between them to format an empty string. ### Configuration diff --git a/docs/lib/content/commands/npm-docs.md b/docs/lib/content/commands/npm-docs.md index af42437093e22..816f228e6d527 100644 --- a/docs/lib/content/commands/npm-docs.md +++ b/docs/lib/content/commands/npm-docs.md @@ -10,8 +10,7 @@ description: Open documentation for a package in a web browser ### Description -This command tries to guess at the likely location of a package's documentation URL, and then tries to open it using the -[`--browser` config](/using-npm/config#browser) param. +This command tries to guess at the likely location of a package's documentation URL, and then tries to open it using the [`--browser` config](/using-npm/config#browser) param. You can pass multiple package names at once. If no package name is provided, it will search for a `package.json` in the current folder and use the `name` property. diff --git a/docs/lib/content/commands/npm-edit.md b/docs/lib/content/commands/npm-edit.md index 8072bd99b2c06..84186792aaf89 100644 --- a/docs/lib/content/commands/npm-edit.md +++ b/docs/lib/content/commands/npm-edit.md @@ -10,8 +10,7 @@ description: Edit an installed package ### Description -Selects a dependency in the current project and opens the package folder in the default editor (or whatever you've configured as the npm `editor` -config -- see [`npm-config`](npm-config).) +Selects a dependency in the current project and opens the package folder in the default editor (or whatever you've configured as the npm `editor` config -- see [`npm-config`](npm-config).) After it has been edited, the package is rebuilt so as to pick up any changes in compiled packages. diff --git a/docs/lib/content/commands/npm-fund.md b/docs/lib/content/commands/npm-fund.md index 779b1441e62d4..1e9cc2255c1ec 100644 --- a/docs/lib/content/commands/npm-fund.md +++ b/docs/lib/content/commands/npm-fund.md @@ -12,8 +12,7 @@ description: Retrieve funding information This command retrieves information on how to fund the dependencies of a given project. If no package name is provided, it will list all dependencies that are looking for funding in a tree structure, listing the type of funding and the url to visit. -If a package name is provided then it tries to open its funding url using the -[`--browser` config](/using-npm/config#browser) param; if there are multiple funding sources for the package, the user will be instructed to pass the +If a package name is provided then it tries to open its funding url using the [`--browser` config](/using-npm/config#browser) param; if there are multiple funding sources for the package, the user will be instructed to pass the `--which` option to disambiguate. The list will avoid duplicated entries and will stack all packages that share the same url as a single entry. @@ -23,8 +22,7 @@ Thus, the list does not have the same shape of the output from `npm ls`. ### Workspaces support -It's possible to filter the results to only include a single workspace and its dependencies using the -[`workspace` config](/using-npm/config#workspace) option. +It's possible to filter the results to only include a single workspace and its dependencies using the [`workspace` config](/using-npm/config#workspace) option. #### Example: diff --git a/docs/lib/content/commands/npm-init.md b/docs/lib/content/commands/npm-init.md index 20c6700557c53..92092cff79f9f 100644 --- a/docs/lib/content/commands/npm-init.md +++ b/docs/lib/content/commands/npm-init.md @@ -33,31 +33,27 @@ If you pass `--scope`, it will create a scoped package. *Note:* if a user already has the `create-` package globally installed, that will be what `npm init` uses. If you want npm to use the latest version, or another specific version you must specify it: -* `npm init foo@latest` # fetches and runs the latest `create-foo` from - the registry +* `npm init foo@latest` # fetches and runs the latest `create-foo` from the registry * `npm init foo@1.2.3` # runs `create-foo@1.2.3` specifically #### Forwarding additional options Any additional options will be passed directly to the command, so `npm init foo -- --hello` will map to `npm exec -- create-foo --hello`. -To better illustrate how options are forwarded, here's a more evolved example showing options passed to both the **npm cli** and a create package, -both following commands are equivalent: +To better illustrate how options are forwarded, here's a more evolved example showing options passed to both the **npm cli** and a create package, both following commands are equivalent: - `npm init foo -y --registry= -- --hello -a` - `npm exec -y --registry= -- create-foo --hello -a` ### Examples -Create a new React-based project using -[`create-react-app`](https://npm.im/create-react-app): +Create a new React-based project using [`create-react-app`](https://npm.im/create-react-app): ```bash $ npm init react-app ./my-react-app ``` -Create a new `esm`-compatible package using -[`create-esm`](https://npm.im/create-esm): +Create a new `esm`-compatible package using [`create-esm`](https://npm.im/create-esm): ```bash $ mkdir my-esm-lib && cd my-esm-lib @@ -111,11 +107,9 @@ That will generate a new folder and `package.json` file, while also updating you `-- package.json ``` -The workspaces init also supports the `npm init -w ` -syntax, following the same set of rules explained earlier in the initial +The workspaces init also supports the `npm init -w ` syntax, following the same set of rules explained earlier in the initial **Description** section of this page. -Similar to the previous example of creating a new React-based project using -[`create-react-app`](https://npm.im/create-react-app), the following syntax will make sure to create the new react app as a nested **workspace** within your project and configure your `package.json` to recognize it as such: +Similar to the previous example of creating a new React-based project using [`create-react-app`](https://npm.im/create-react-app), the following syntax will make sure to create the new react app as a nested **workspace** within your project and configure your `package.json` to recognize it as such: ```bash npm init -w packages/my-react-app react-app . diff --git a/docs/lib/content/commands/npm-install.md b/docs/lib/content/commands/npm-install.md index 9e4996d51373c..e1e17e6d70466 100644 --- a/docs/lib/content/commands/npm-install.md +++ b/docs/lib/content/commands/npm-install.md @@ -17,19 +17,15 @@ If the package has a package-lock, or an npm shrinkwrap file, or a yarn lock fil * `package-lock.json` * `yarn.lock` -See [package-lock.json](/configuring-npm/package-lock-json) and -[`npm shrinkwrap`](/commands/npm-shrinkwrap). +See [package-lock.json](/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/commands/npm-shrinkwrap). A `package` is: -* a) a folder containing a program described by a - [`package.json`](/configuring-npm/package-json) file +* a) a folder containing a program described by a [`package.json`](/configuring-npm/package-json) file * b) a gzipped tarball containing (a) * c) a url that resolves to (b) -* d) a `@` that is published on the registry (see - [`registry`](/using-npm/registry)) with (c) -* e) a `@` (see [`npm dist-tag`](/commands/npm-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`](/commands/npm-dist-tag)) that points to (d) * f) a `` that has a "latest" tag satisfying (e) * g) a `` that resolves to (a) diff --git a/docs/lib/content/commands/npm-link.md b/docs/lib/content/commands/npm-link.md index 05aff5314e65a..347da3540b4a2 100644 --- a/docs/lib/content/commands/npm-link.md +++ b/docs/lib/content/commands/npm-link.md @@ -23,12 +23,10 @@ Next, in some other location, `npm link package-name` will create a symbolic lin 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). +See [`scope`](/using-npm/scope). The scope must be preceded by an @-symbol and followed by a slash. -When creating tarballs for `npm publish`, the linked packages are -"snapshotted" to their current state by resolving the symbolic links, if they are included in `bundleDependencies`. +When creating tarballs for `npm publish`, the linked packages are "snapshotted" to their current state by resolving the symbolic links, if they are included in `bundleDependencies`. For example: @@ -71,10 +69,8 @@ npm link @myorg/privatepackage ### Caveat -Note that package dependencies linked in this way are _not_ saved to `package.json` by default, on the assumption that the intention is to have -a link stand in for a regular non-link dependency. -Otherwise, for example, -if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace the `^3.0.1` dependency with `file:../path/to/node-redis`, which you probably don't want! Additionally, other users or developers on your project would run into issues if they do not have their folders set up exactly the same as yours. +Note that package dependencies linked in this way are _not_ saved to `package.json` by default, on the assumption that the intention is to have a link stand in for a regular non-link dependency. +Otherwise, for example, if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace the `^3.0.1` dependency with `file:../path/to/node-redis`, which you probably don't want! Additionally, other users or developers on your project would run into issues if they do not have their folders set up exactly the same as yours. If you are adding a _new_ dependency as a link, you should add it to the relevant metadata by running `npm install --package-lock-only`. diff --git a/docs/lib/content/commands/npm-login.md b/docs/lib/content/commands/npm-login.md index 1c8e744e0b8da..18d776e39a19b 100644 --- a/docs/lib/content/commands/npm-login.md +++ b/docs/lib/content/commands/npm-login.md @@ -24,8 +24,7 @@ To reset your password, go to To change your email address, go to You may use this command multiple times with the same user account to authorize on a new machine. -When authenticating on a new machine, -the username, password and email address must all match with your existing record. +When authenticating on a new machine, the username, password and email address must all match with your existing record. ### Configuration diff --git a/docs/lib/content/commands/npm-org.md b/docs/lib/content/commands/npm-org.md index d866c75aead61..3cf6f01dde7a3 100644 --- a/docs/lib/content/commands/npm-org.md +++ b/docs/lib/content/commands/npm-org.md @@ -49,8 +49,7 @@ $ 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. +It supports adding and removing users, changing their roles, listing them, and finding specific ones and their roles. ### Configuration diff --git a/docs/lib/content/commands/npm-owner.md b/docs/lib/content/commands/npm-owner.md index a803111802eb4..4bea77a0f9aac 100644 --- a/docs/lib/content/commands/npm-owner.md +++ b/docs/lib/content/commands/npm-owner.md @@ -12,23 +12,18 @@ description: Manage package owners Manage ownership of published packages. -* ls: List all the users who have access to modify a package and push new - versions. +* 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. +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. +This immediately revokes their privileges. Note that there is only one level of access. -Either you can modify a package, -or you can't. +Either you can modify a package, or you can't. Future versions may contain more fine-grained access levels, but that is not implemented at this time. -If you have two-factor authentication enabled with `auth-and-writes` (see -[`npm-profile`](/commands/npm-profile)) then you'll need to go through a second factor flow when changing ownership or include an otp on the command line with `--otp`. +If you have two-factor authentication enabled with `auth-and-writes` (see [`npm-profile`](/commands/npm-profile)) then you'll need to go through a second factor flow when changing ownership or include an otp on the command line with `--otp`. ### Configuration diff --git a/docs/lib/content/commands/npm-pkg.md b/docs/lib/content/commands/npm-pkg.md index 6379c6575b1c4..403b8f93cacc7 100644 --- a/docs/lib/content/commands/npm-pkg.md +++ b/docs/lib/content/commands/npm-pkg.md @@ -122,9 +122,7 @@ Returned values are always in **json** format. ### Workspaces support -You can set/get/delete items across your configured workspaces by using the -[`workspace`](/using-npm/config#workspace) or -[`workspaces`](/using-npm/config#workspaces) config options. +You can set/get/delete items across your configured workspaces by using the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) config options. For example, setting a `funding` value across all configured workspaces of a project: diff --git a/docs/lib/content/commands/npm-prefix.md b/docs/lib/content/commands/npm-prefix.md index c0615aa743e8b..b038cc20e2f51 100644 --- a/docs/lib/content/commands/npm-prefix.md +++ b/docs/lib/content/commands/npm-prefix.md @@ -14,8 +14,7 @@ Print the local prefix to standard output. This is the closest parent directory to contain a `package.json` file or `node_modules` directory, unless `-g` is also specified. If `-g` is specified, this will be the value of the global prefix. -See -[`npm config`](/commands/npm-config) for more detail. +See [`npm config`](/commands/npm-config) for more detail. ### Example diff --git a/docs/lib/content/commands/npm-profile.md b/docs/lib/content/commands/npm-profile.md index 79dd965c705d0..fc69cef28918e 100644 --- a/docs/lib/content/commands/npm-profile.md +++ b/docs/lib/content/commands/npm-profile.md @@ -13,8 +13,7 @@ description: Change settings on your registry profile 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 []`: Display all of the properties of your - profile, or one or more specific properties. +* `npm profile get []`: Display all of the properties of your profile, or one or more specific properties. It looks like: ``` @@ -30,29 +29,19 @@ created: 2015-02-26T01:38:35.892Z updated: 2017-10-02T21:29:45.922Z ``` -* `npm profile set `: Set the value of a profile - property. -You can set the following properties this way: email, fullname, - homepage, freenode, twitter, github +* `npm profile set `: 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 enable-2fa [auth-and-writes|auth-only]`: Enables two-factor - authentication. +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-only`: Require an OTP when logging in or making changes to your account's authentication. +The OTP will be required on both the website and the command line. + * `auth-and-writes`: Requires an OTP at all the times `auth-only` does, and also requires one when publishing a module, setting the `latest` dist-tag, or changing access via `npm access` and `npm owner`. * `npm profile disable-2fa`: Disables two-factor authentication. diff --git a/docs/lib/content/commands/npm-publish.md b/docs/lib/content/commands/npm-publish.md index 35e7a88349ed9..d787e0020008a 100644 --- a/docs/lib/content/commands/npm-publish.md +++ b/docs/lib/content/commands/npm-publish.md @@ -13,21 +13,16 @@ description: Publish a package Publishes a package to the registry so that it can be installed by name. By default npm will publish to the public registry. -This can be overridden by specifying a different default registry or using a -[`scope`](/using-npm/scope) in the name, combined with a scope-configured registry (see -[`package.json`](/configuring-npm/package-json)). +This can be overridden by specifying a different default registry or using a [`scope`](/using-npm/scope) in the name, combined with a scope-configured registry (see [`package.json`](/configuring-npm/package-json)). A `package` is interpreted the same way as other commands (like `npm install`) and can be: -* a) 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`](/commands/npm-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`](/commands/npm-dist-tag)) that points to (d) * f) a `` that has a "latest" tag satisfying (e) * g) a `` that resolves to (a) @@ -45,31 +40,20 @@ Similar to `--dry-run` see [`npm pack`](/commands/npm-pack), which figures out t To see what will be included in your package, run `npm pack --dry-run`. All files are included by default, with the following exceptions: -- Certain files that are relevant to package installation and distribution - are always included. +- 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 +- 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 + `.npmignore` files follow the [same pattern rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) as `.gitignore` files -- If the file matches certain patterns, then it will _never_ be included, - unless explicitly added to the `"files"` list in `package.json`, or - un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file. +- If the file matches certain patterns, then it will _never_ be included, unless explicitly added to the `"files"` list in `package.json`, or un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file. - Symbolic links are never included in npm packages. diff --git a/docs/lib/content/commands/npm-repo.md b/docs/lib/content/commands/npm-repo.md index e63940b0e2b84..75d39df6cd5ba 100644 --- a/docs/lib/content/commands/npm-repo.md +++ b/docs/lib/content/commands/npm-repo.md @@ -10,8 +10,7 @@ description: Open package repository page in the browser ### Description -This command tries to guess at the likely location of a package's repository URL, and then tries to open it using the -[`--browser` config](/using-npm/config#browser) param. +This command tries to guess at the likely location of a package's repository URL, and then tries to open it using the [`--browser` config](/using-npm/config#browser) param. If no package name is provided, it will search for a `package.json` in the current folder and use the `repository` property. ### Configuration diff --git a/docs/lib/content/commands/npm-run.md b/docs/lib/content/commands/npm-run.md index cb73dd36c5e3d..ddabd699e6962 100644 --- a/docs/lib/content/commands/npm-run.md +++ b/docs/lib/content/commands/npm-run.md @@ -26,12 +26,10 @@ For example: npm run test -- --grep="pattern" ``` -The arguments will only be passed to the script specified after `npm run` -and not to any `pre` or `post` script. +The arguments will only be passed to the script specified after `npm run` and not to any `pre` or `post` script. The `env` script is a special built-in command that can be used to list environment variables that will be available to the script at runtime. -If an -"env" command is defined in your package, it will take precedence over the built-in. +If an "env" command is defined in your package, it will take precedence over the built-in. In addition to the shell's pre-existing `PATH`, `npm run` adds `node_modules/.bin` to the `PATH` provided to scripts. Any binaries provided by locally-installed dependencies can be used without the `node_modules/.bin` prefix. @@ -48,11 +46,9 @@ instead of ``` The actual shell your script is run within is platform dependent. -By default, -on Unix-like systems it is the `/bin/sh` command, on Windows it is `cmd.exe`. +By default, on Unix-like systems it is the `/bin/sh` command, on Windows it is `cmd.exe`. The actual shell referred to by `/bin/sh` also depends on the system. -You can customize the shell with the -[`script-shell` config](/using-npm/config#script-shell). +You can customize the shell with the [`script-shell` config](/using-npm/config#script-shell). Scripts are run from the root of the package folder, regardless of what the current working directory is when `npm run` is called. If you want your script to use different behavior based on what subdirectory you're in, you can use the `INIT_CWD` environment variable, which holds the full path you were in when you ran `npm run`. @@ -63,8 +59,7 @@ If you try to run a script without having a `node_modules` directory and it fail ### Workspaces support -You may use the [`workspace`](/using-npm/config#workspace) or -[`workspaces`](/using-npm/config#workspaces) configs in order to run an arbitrary command from a package's `"scripts"` object in the context of the specified workspaces. +You may use the [`workspace`](/using-npm/config#workspace) or [`workspaces`](/using-npm/config#workspaces) configs in order to run an arbitrary command from a package's `"scripts"` object in the context of the specified workspaces. If no `"command"` is provided, it will list the available scripts for each of these configured workspaces. Given a project with configured workspaces, e.g: @@ -90,9 +85,7 @@ e.g: } ``` -And that each of the configured workspaces has a configured `test` script, -we can run tests in all of them using the -[`workspaces` config](/using-npm/config#workspaces): +And that each of the configured workspaces has a configured `test` script, we can run tests in all of them using the [`workspaces` config](/using-npm/config#workspaces): ``` npm test --workspaces @@ -100,8 +93,7 @@ npm test --workspaces #### Filtering workspaces -It's also possible to run a script in a single workspace using the `workspace` -config along with a name or directory path: +It's also possible to run a script in a single workspace using the `workspace` config along with a name or directory path: ``` npm test --workspace=a @@ -114,8 +106,7 @@ When defining values for the `workspace` config in the command line, it also pos npm test -w a -w b ``` -This last command will run `test` in both `./packages/a` and `./packages/b` -packages. +This last command will run `test` in both `./packages/a` and `./packages/b` packages. ### Configuration diff --git a/docs/lib/content/commands/npm-sbom.md b/docs/lib/content/commands/npm-sbom.md index ff1eaaa832d17..2e2c53f1bf327 100644 --- a/docs/lib/content/commands/npm-sbom.md +++ b/docs/lib/content/commands/npm-sbom.md @@ -11,8 +11,7 @@ description: Generate a Software Bill of Materials (SBOM) ### Description The `npm sbom` command generates a Software Bill of Materials (SBOM) listing the dependencies for the current project. -SBOMs can be generated in either -[SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format. +SBOMs can be generated in either [SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format. ### Example CycloneDX SBOM diff --git a/docs/lib/content/commands/npm-shrinkwrap.md b/docs/lib/content/commands/npm-shrinkwrap.md index 689f815891d7f..6eb53e288201f 100644 --- a/docs/lib/content/commands/npm-shrinkwrap.md +++ b/docs/lib/content/commands/npm-shrinkwrap.md @@ -12,8 +12,7 @@ description: Lock down dependency versions for publication This command repurposes `package-lock.json` into a publishable `npm-shrinkwrap.json` or simply creates a new one. The file created and updated by this command will then take precedence over any other existing or future `package-lock.json` files. -For a detailed explanation of the design and purpose of package locks in npm, see -[package-lock-json](/configuring-npm/package-lock-json). +For a detailed explanation of the design and purpose of package locks in npm, see [package-lock-json](/configuring-npm/package-lock-json). ### See Also diff --git a/docs/lib/content/commands/npm-star.md b/docs/lib/content/commands/npm-star.md index 7db44d809a17a..431ee396761aa 100644 --- a/docs/lib/content/commands/npm-star.md +++ b/docs/lib/content/commands/npm-star.md @@ -11,8 +11,7 @@ description: Mark your favorite packages ### Description "Starring" a package means that you have some interest in it. -It's -a vaguely positive way to show that you care. +It's a vaguely positive way to show that you care. It's a boolean thing. Starring repeatedly has no additional effect. diff --git a/docs/lib/content/commands/npm-start.md b/docs/lib/content/commands/npm-start.md index 1cf690084bc12..3c28b43359fed 100644 --- a/docs/lib/content/commands/npm-start.md +++ b/docs/lib/content/commands/npm-start.md @@ -10,8 +10,7 @@ description: Start a package ### Description -This runs a predefined command specified in the `"start"` property of -a package's `"scripts"` object. +This runs a predefined command specified in the `"start"` property of a package's `"scripts"` object. If the `"scripts"` object does not define a `"start"` property, npm will run `node server.js`. diff --git a/docs/lib/content/commands/npm-test.md b/docs/lib/content/commands/npm-test.md index 58a35e5bba1d2..143c3b60dca6d 100644 --- a/docs/lib/content/commands/npm-test.md +++ b/docs/lib/content/commands/npm-test.md @@ -10,8 +10,7 @@ description: Test a package ### Description -This runs a predefined command specified in the `"test"` property of -a package's `"scripts"` object. +This runs a predefined command specified in the `"test"` property of a package's `"scripts"` object. ### Example diff --git a/docs/lib/content/commands/npm-uninstall.md b/docs/lib/content/commands/npm-uninstall.md index bf4b1694f22d6..ce0aa55966433 100644 --- a/docs/lib/content/commands/npm-uninstall.md +++ b/docs/lib/content/commands/npm-uninstall.md @@ -22,8 +22,7 @@ Further, if you have an `npm-shrinkwrap.json` or `package-lock.json`, npm will u `--save` or `-S` will tell npm to remove the package from your `package.json`, `npm-shrinkwrap.json`, and `package-lock.json` files. This is the default, but you may need to use this if you have for instance `save=false` in your `npmrc` file -In global mode (ie, with `-g` or `--global` appended to the command), -it uninstalls the current package context as a global package. +In global mode (ie, with `-g` or `--global` appended to the command), it uninstalls the current package context as a global package. `--no-save` is ignored in this case. Scope is optional and follows the usual rules for [`scope`](/using-npm/scope). diff --git a/docs/lib/content/commands/npm-unpublish.md b/docs/lib/content/commands/npm-unpublish.md index ce03ef15e408a..152af8b55212d 100644 --- a/docs/lib/content/commands/npm-unpublish.md +++ b/docs/lib/content/commands/npm-unpublish.md @@ -8,13 +8,11 @@ description: Remove a package from the registry -To learn more about how the npm registry treats unpublish, see our -[unpublish policies](https://docs.npmjs.com/policies/unpublish). +To learn more about how the npm registry treats unpublish, see our [unpublish policies](https://docs.npmjs.com/policies/unpublish). ### Warning -Consider using the [`deprecate`](/commands/npm-deprecate) command instead, -if your intent is to encourage users to upgrade, or if you no longer want to maintain a package. +Consider using the [`deprecate`](/commands/npm-deprecate) command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package. ### Description @@ -27,10 +25,8 @@ If you do not specify a package name at all, the name and version to be unpublis If you specify a package name but do not specify a version or if you remove all of a package's versions then the registry will remove the root package entry entirely. Even if you unpublish a package version, that specific name and version combination can never be reused. -In order to publish the package again, -you must use a new version number. -If you unpublish the entire package, -you may not publish any new versions of that package until 24 hours have passed. +In order to publish the package again, you must use a new version number. +If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed. ### Configuration diff --git a/docs/lib/content/commands/npm-unstar.md b/docs/lib/content/commands/npm-unstar.md index aedeb92a6d71e..51124d8b1e65a 100644 --- a/docs/lib/content/commands/npm-unstar.md +++ b/docs/lib/content/commands/npm-unstar.md @@ -10,8 +10,7 @@ description: Remove an item from your favorite packages ### Description -"Unstarring" a package is the opposite of [`npm star`](/commands/npm-star), -it removes an item from your list of favorite packages. +"Unstarring" a package is the opposite of [`npm star`](/commands/npm-star), it removes an item from your list of favorite packages. ### More diff --git a/docs/lib/content/commands/npm-update.md b/docs/lib/content/commands/npm-update.md index 0f453c1f72a8d..b4d8516329faf 100644 --- a/docs/lib/content/commands/npm-update.md +++ b/docs/lib/content/commands/npm-update.md @@ -10,8 +10,7 @@ description: Update packages ### Description -This command will update all the packages listed to the latest version -(specified by the [`tag` config](/using-npm/config#tag)), respecting the semver constraints of both your package and its dependencies (if they also require the same package). +This command will update all the packages listed to the latest version (specified by the [`tag` config](/using-npm/config#tag)), respecting the semver constraints of both your package and its dependencies (if they also require the same package). It will also install missing packages. @@ -20,14 +19,12 @@ If the `-g` flag is specified, this command will update globally installed packa If no package name is specified, all packages in the specified location (global or local) will be updated. Note that by default `npm update` will not update the semver values of direct dependencies in your project `package.json`. -If you want to also update values in `package.json` you can run: `npm update --save` (or add the `save=true` option to a [configuration file](/configuring-npm/npmrc) -to make that the default behavior). +If you want to also update values in `package.json` you can run: `npm update --save` (or add the `save=true` option to a [configuration file](/configuring-npm/npmrc) to make that the default behavior). ### Example For the examples below, assume that the current package is `app` and it depends on dependencies, `dep1` (`dep2`, .. etc.). -The published versions of `dep1` -are: +The published versions of `dep1` are: ```json { diff --git a/docs/lib/content/commands/npm-view.md b/docs/lib/content/commands/npm-view.md index 5f82d55e3bdde..a882cb757e53a 100644 --- a/docs/lib/content/commands/npm-view.md +++ b/docs/lib/content/commands/npm-view.md @@ -86,8 +86,7 @@ npm view npm contributors ``` If a version range is provided, then data will be printed for every matching version of the package. -This will show which version of `jsdom` -was required by each matching version of `yui3`: +This will show which version of `jsdom` was required by each matching version of `yui3`: ```bash npm view yui3@'>0.5.4' dependencies.jsdom diff --git a/docs/lib/content/commands/npm.md b/docs/lib/content/commands/npm.md index 9f5373e99da7d..97ebb5abd3557 100644 --- a/docs/lib/content/commands/npm.md +++ b/docs/lib/content/commands/npm.md @@ -47,8 +47,7 @@ Use `npm ls` to show everything you've installed. If a package lists a dependency using a git URL, npm will install that dependency using the [`git`](https://github.com/git-guides/install-git) command and will generate an error if it is not installed. If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use [node-gyp](https://github.com/nodejs/node-gyp) for that task. -For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp) needs Python, make and a buildchain like GCC. On Windows, -Python and Microsoft Visual Studio C++ are needed. +For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp) needs Python, make and a buildchain like GCC. On Windows, Python and Microsoft Visual Studio C++ are needed. For more information visit [the node-gyp repository](https://github.com/nodejs/node-gyp) and the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki). ### Directories diff --git a/docs/lib/content/commands/npx.md b/docs/lib/content/commands/npx.md index eb0bbbb0de04a..91e03f4138f43 100644 --- a/docs/lib/content/commands/npx.md +++ b/docs/lib/content/commands/npx.md @@ -10,8 +10,7 @@ description: Run a command from a local or remote npm package ### Description -This command allows you to run an arbitrary command from an npm package -(either one installed locally, or fetched remotely), in a similar context as running it via `npm run`. +This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via `npm run`. Whatever packages are specified by the `--package` option will be provided in the `PATH` of the executed command, along with any locally installed package executables. The `--package` option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available. @@ -25,13 +24,9 @@ Package names with a specifier will only be considered a match if they have the If no `-c` or `--call` option is provided, then the positional arguments are used to generate the command string. If no `--package` options are provided, then npm will attempt to determine the executable name from the package specifier provided as the first positional argument according to the following heuristic: -- If the package has a single entry in its `bin` field in `package.json`, - or if all entries are aliases of the same command, then that command - will be used. -- If the package has multiple `bin` entries, and one of them matches the - unscoped portion of the `name` field, then that command will be used. -- If this does not result in exactly one option (either because there are - no bin entries, or none of them match the `name` of the package), then +- If the package has a single entry in its `bin` field in `package.json`, or if all entries are aliases of the same command, then that command will be used. +- If the package has multiple `bin` entries, and one of them matches the unscoped portion of the `name` field, then that command will be used. +- If this does not result in exactly one option (either because there are no bin entries, or none of them match the `name` of the package), then `npm exec` exits with an error. To run a binary _other than_ the named binary, specify one or more @@ -40,8 +35,7 @@ To run a binary _other than_ the named binary, specify one or more ### `npx` vs `npm exec` When run via the `npx` binary, all flags and options *must* be set prior to any positional arguments. -When run via `npm exec`, a double-hyphen `--` -flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command. +When run via `npm exec`, a double-hyphen `--` flag can be used to suppress npm's parsing of switches and options that should be sent to the executed command. For example: @@ -104,36 +98,27 @@ $ npx -c 'eslint && say "hooray, lint passed"' ### Compatibility with Older npx Versions -The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` -package deprecated at that time. - `npx` uses the `npm exec` -command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions. +The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` package deprecated at that time. + `npx` uses the `npm exec` command instead of a separate argument parser and install process, with some affordances to maintain backwards compatibility with the arguments it accepted in previous versions. This resulted in some shifts in its functionality: - Any `npm` config value may be provided. -- To prevent security and user-experience problems from mistyping package - names, `npx` prompts before installing anything. -Suppress this - prompt with the `-y` or `--yes` option. +- To prevent security and user-experience problems from mistyping package names, `npx` prompts before installing anything. +Suppress this prompt with the `-y` or `--yes` option. - The `--no-install` option is deprecated, and will be converted to `--no`. - Shell fallback functionality is removed, as it is not advisable. -- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand - for `--package` in npx. -This is maintained, but only for the `npx` - executable. +- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand for `--package` in npx. +This is maintained, but only for the `npx` executable. - The `--ignore-existing` option is removed. -Locally installed bins are - always present in the executed process `PATH`. +Locally installed bins are always present in the executed process `PATH`. - The `--npm` option is removed. - `npx` will always use the `npm` it ships - with. + `npx` will always use the `npm` it ships with. - The `--node-arg` and `-n` options have been removed. Use [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) instead: e.g., `NODE_OPTIONS="--trace-warnings --trace-exit" npx foo --random=true` - The `--always-spawn` option is redundant, and thus removed. -- The `--shell` option is replaced with `--script-shell`, but maintained - in the `npx` executable for backwards compatibility. +- The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility. ### See Also diff --git a/docs/lib/content/configuring-npm/install.md b/docs/lib/content/configuring-npm/install.md index f24a2915c7a54..1d7e7b80e6c22 100644 --- a/docs/lib/content/configuring-npm/install.md +++ b/docs/lib/content/configuring-npm/install.md @@ -12,12 +12,9 @@ Node installer, since the Node installation process installs npm in a directory ### Overview -- [Checking your version of npm and - Node.js](#checking-your-version-of-npm-and-nodejs) -- [Using a Node version manager to install Node.js and - npm](#using-a-node-version-manager-to-install-nodejs-and-npm) -- [Using a Node installer to install Node.js and - npm](#using-a-node-installer-to-install-nodejs-and-npm) +- [Checking your version of npm and Node.js](#checking-your-version-of-npm-and-nodejs) +- [Using a Node version manager to install Node.js and npm](#using-a-node-version-manager-to-install-nodejs-and-npm) +- [Using a Node installer to install Node.js and npm](#using-a-node-installer-to-install-nodejs-and-npm) ### Checking your version of npm and Node.js @@ -31,8 +28,7 @@ npm -v ### Using a Node version manager to install Node.js and npm Node version managers allow you to install and switch between multiple versions of Node.js and npm on your system so you can test your applications on multiple versions of npm to ensure they work for users on different versions. -You can -[search for them on GitHub](https://github.com/search?q=node+version+manager+archived%3Afalse&type=repositories&ref=advsearch). +You can [search for them on GitHub](https://github.com/search?q=node+version+manager+archived%3Afalse&type=repositories&ref=advsearch). ### Using a Node installer to install Node.js and npm @@ -40,22 +36,18 @@ If you are unable to use a Node version manager, you can use a Node installer to * [Node.js installer](https://nodejs.org/en/download/) * [NodeSource installer](https://github.com/nodesource/distributions). -If - you use Linux, we recommend that you use a NodeSource installer. +If you use Linux, we recommend that you use a NodeSource installer. #### macOS or Windows Node installers -If you're using macOS or Windows, use one of the installers from the -[Node.js download page](https://nodejs.org/en/download/). +If you're using macOS or Windows, use one of the installers from the [Node.js download page](https://nodejs.org/en/download/). Be sure to install the version labeled **LTS**. Other versions have not yet been tested with npm. #### Linux or other operating systems Node installers If you're using Linux or another operating system, use one of the following installers: -- [NodeSource installer](https://github.com/nodesource/distributions) - (recommended) -- One of the installers on the [Node.js download - page](https://nodejs.org/en/download/) +- [NodeSource installer](https://github.com/nodesource/distributions) (recommended) +- One of the installers on the [Node.js download page](https://nodejs.org/en/download/) Or see [this page](https://nodejs.org/en/download/package-manager/) to install npm for Linux in the way many Linux developers prefer. diff --git a/docs/lib/content/configuring-npm/npm-shrinkwrap-json.md b/docs/lib/content/configuring-npm/npm-shrinkwrap-json.md index f03998d641997..4ea5e4dc20b1d 100644 --- a/docs/lib/content/configuring-npm/npm-shrinkwrap-json.md +++ b/docs/lib/content/configuring-npm/npm-shrinkwrap-json.md @@ -15,9 +15,7 @@ It's strongly discouraged for library authors to publish this file, since that w If both `package-lock.json` and `npm-shrinkwrap.json` are present in a package root, `npm-shrinkwrap.json` will be preferred over the `package-lock.json` file. -For full details and description of the `npm-shrinkwrap.json` file format, -refer to the manual page for -[package-lock.json](/configuring-npm/package-lock-json). +For full details and description of the `npm-shrinkwrap.json` file format, refer to the manual page for [package-lock.json](/configuring-npm/package-lock-json). ### See also diff --git a/docs/lib/content/configuring-npm/npmrc.md b/docs/lib/content/configuring-npm/npmrc.md index 77f094b6bb08d..41d7c5e462c51 100644 --- a/docs/lib/content/configuring-npm/npmrc.md +++ b/docs/lib/content/configuring-npm/npmrc.md @@ -6,13 +6,11 @@ description: The npm config files ### Description -npm gets its config settings from the command line, environment variables, -and `npmrc` files. +npm gets its config settings from the command line, environment variables, and `npmrc` files. The `npm config` command can be used to update and edit the contents of the user and global npmrc files. -For a list of available configuration options, see -[config](/using-npm/config). +For a list of available configuration options, see [config](/using-npm/config). ### Files @@ -84,14 +82,12 @@ Environment variables can be replaced as above. `path/to/npm/itself/npmrc` This is an unchangeable "builtin" configuration file that npm keeps consistent across updates. -Set fields in here using the `./configure` -script that comes with npm. +Set fields in here using the `./configure` script that comes with npm. This is primarily for distribution maintainers to override default configs in a standard and consistent manner. ### Auth related configuration -The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`, -and `keyfile` must all be scoped to a specific registry. +The settings `_auth`, `_authToken`, `username`, `_password`, `certfile`, and `keyfile` must all be scoped to a specific registry. This ensures that `npm` will never send credentials to the wrong host. The full list is: @@ -105,8 +101,7 @@ The full list is: - `keyfile` (path to key file) In order to scope these values, they must be prefixed by a URI fragment. -If the credential is meant for any request to a registry on a single host, -the scope may look like `//registry.npmjs.org/:`. +If the credential is meant for any request to a registry on a single host, the scope may look like `//registry.npmjs.org/:`. If it must be scoped to a specific path on the host that path may also be provided, such as `//my-custom-registry.org/unique/path:`. diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 018f28bf0474b..a68ccf6f6d2cc 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -92,8 +92,7 @@ It should look like this: ``` You can specify either one or both values. -If you want to provide only a -URL, you can specify the value for "bugs" as a simple string instead of an object. +If you want to provide only a URL, you can specify the value for "bugs" as a simple string instead of an object. If a URL is provided, it will be used by the `npm bugs` command. @@ -101,8 +100,7 @@ If a URL is provided, it will be used by the `npm bugs` command. You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it. -If you're using a common license such as BSD-2-Clause or MIT, add a current -SPDX license identifier for the license you're using, like this: +If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this: ```json { @@ -338,8 +336,7 @@ This is helpful to hint users that it might rely on primitives that aren't avail A lot of packages have one or more executable files that they'd like to install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.) To use this, supply a `bin` field in your package.json which is a map of command name to local file name. -When this package is installed globally, that file will be either linked inside the global bins directory or a cmd (Windows Command File) will be created which executes the specified file in the `bin` field, so it is available to run by `name` or `name.cmd` (on -Windows PowerShell). +When this package is installed globally, that file will be either linked inside the global bins directory or a cmd (Windows Command File) will be created which executes the specified file in the `bin` field, so it is available to run by `name` or `name.cmd` (on Windows PowerShell). When this package is installed as a dependency in another package, the file will be linked where it will be available to that package either directly by `npm exec` or by name in other scripts when invoking them via `npm run`. @@ -681,8 +678,7 @@ In this case, it's best to map these additional items in a `devDependencies` obj These things will be installed when doing `npm link` or `npm install` from the root of a package, and can be managed like any other npm configuration param. See [`config`](/using-npm/config) for more on the topic. -For build steps that are not platform-specific, such as compiling -CoffeeScript or other languages to JavaScript, use the `prepare` script to do this, and make the required package a devDependency. +For build steps that are not platform-specific, such as compiling CoffeeScript or other languages to JavaScript, use the `prepare` script to do this, and make the required package a devDependency. For example: @@ -797,8 +793,7 @@ A value of `true` will bundle all dependencies, a value of `false` will bundle n ### optionalDependencies If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the `optionalDependencies` object. -This is a map of package name to version or -URL, just like the `dependencies` object. +This is a map of package name to version or URL, just like the `dependencies` object. The difference is that build failures do not cause installation to fail. Running `npm install --omit=optional` will prevent these dependencies from being installed. diff --git a/docs/lib/content/using-npm/config.md b/docs/lib/content/using-npm/config.md index 15d53ddf3d7e1..865ca05b92914 100644 --- a/docs/lib/content/using-npm/config.md +++ b/docs/lib/content/using-npm/config.md @@ -7,8 +7,7 @@ description: More than you probably want to know about npm configuration ### Description This article details npm configuration in general. -To learn about the `config` command, -see [`npm config`](/commands/npm-config). +To learn about the `config` command, see [`npm config`](/commands/npm-config). npm gets its configuration values from the following sources, sorted by priority: @@ -18,33 +17,27 @@ Putting `--foo bar` on the command line sets the `foo` configuration parameter t A `--` argument tells the cli parser to stop reading flags. Using `--flag` without specifying any value will set the value to `true`. -Example: `--flag1 --flag2` will set both configuration parameters to `true`, while `--flag1 --flag2 bar` will set `flag1` to `true`, -and `flag2` to `bar`. +Example: `--flag1 --flag2` will set both configuration parameters to `true`, while `--flag1 --flag2 bar` will set `flag1` to `true`, and `flag2` to `bar`. Finally, `--flag1 --flag2 -- bar` will set both configuration parameters to `true`, and the `bar` is taken as a command argument. #### Environment Variables Any environment variables that start with `npm_config_` will be interpreted as a configuration parameter. -For example, putting `npm_config_foo=bar` in your environment will set the `foo` -configuration parameter to `bar`. +For example, putting `npm_config_foo=bar` in your environment will set the `foo` configuration parameter to `bar`. Any environment configurations that are not given a value will be given the value of `true`. Config values are case-insensitive, so `NPM_CONFIG_FOO=bar` will work the same. -However, please note that inside [`scripts`](/using-npm/scripts) -npm will set its own environment variables and Node will prefer those lowercase versions over any uppercase ones that you might set. +However, please note that inside [`scripts`](/using-npm/scripts) npm will set its own environment variables and Node will prefer those lowercase versions over any uppercase ones that you might set. For details see [this issue](https://github.com/npm/npm/issues/14528). -Notice that you need to use underscores instead of dashes, so `--allow-same-version` -would become `npm_config_allow_same_version=true`. +Notice that you need to use underscores instead of dashes, so `--allow-same-version` would become `npm_config_allow_same_version=true`. #### npmrc Files The four relevant files are: * per-project configuration file (`/path/to/my/project/.npmrc`) -* per-user configuration file (defaults to `$HOME/.npmrc`; configurable via CLI - option `--userconfig` or environment variable `$NPM_CONFIG_USERCONFIG`) -* global configuration file (defaults to `$PREFIX/etc/npmrc`; configurable via - CLI option `--globalconfig` or environment variable `$NPM_CONFIG_GLOBALCONFIG`) +* per-user configuration file (defaults to `$HOME/.npmrc`; configurable via CLI option `--userconfig` or environment variable `$NPM_CONFIG_USERCONFIG`) +* global configuration file (defaults to `$PREFIX/etc/npmrc`; configurable via CLI option `--globalconfig` or environment variable `$NPM_CONFIG_GLOBALCONFIG`) * npm's built-in configuration file (`/path/to/npm/npmrc`) See [npmrc](/configuring-npm/npmrc) for more details. diff --git a/docs/lib/content/using-npm/logging.md b/docs/lib/content/using-npm/logging.md index ee27ad62c62df..d5fca42f595c2 100644 --- a/docs/lib/content/using-npm/logging.md +++ b/docs/lib/content/using-npm/logging.md @@ -16,8 +16,7 @@ The default location of the logs directory is a directory named `_logs` inside t This can be changed with the `logs-dir` config option. For example, if you wanted to write all your logs to the current working directory, you could run: `npm install --logs-dir=.`. -This is especially helpful in debugging a specific `npm` issue as you can run -a command multiple times with different config values and then diff all the log files. +This is especially helpful in debugging a specific `npm` issue as you can run a command multiple times with different config values and then diff all the log files. Log files will be removed from the `logs-dir` when the number of log files exceeds `logs-max`, with the oldest logs being deleted first. diff --git a/docs/lib/content/using-npm/package-spec.md b/docs/lib/content/using-npm/package-spec.md index 71e8cb1706d01..93de80d579963 100644 --- a/docs/lib/content/using-npm/package-spec.md +++ b/docs/lib/content/using-npm/package-spec.md @@ -8,8 +8,7 @@ description: Package name specifier ### Description Commands like `npm install` and the dependency sections in the `package.json` use a package name specifier. -This can be many different things that all refer to a "package". Examples include a package name, -git url, tarball, or local directory. +This can be many different things that all refer to a "package". Examples include a package name, git url, tarball, or local directory. These will generally be referred to as `` in the help output for the npm commands that use this package name specifier. ### Package name @@ -48,8 +47,7 @@ Examples: * `` This refers to a package on the local filesystem. -Specifically this is -a folder with a `package.json` file in it. +Specifically this is a folder with a `package.json` file in it. This *should* always be prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion. npm currently will parse a string with more than one `/` in it as a folder, but this is legacy behavior that may be removed in a future version. diff --git a/docs/lib/content/using-npm/registry.md b/docs/lib/content/using-npm/registry.md index 1dbd41e3090bc..a707b97ac5a9b 100644 --- a/docs/lib/content/using-npm/registry.md +++ b/docs/lib/content/using-npm/registry.md @@ -17,15 +17,11 @@ Use of someone else's registry may be governed by their terms of use. npm's package registry implementation supports several write APIs as well, to allow for publishing packages and managing user account information. -The registry URL used is determined by the scope of the package (see -[`scope`](/using-npm/scope). -If no scope is specified, the default registry is used, which is supplied by the [`registry` config](/using-npm/config#registry) -parameter. -See [`npm config`](/commands/npm-config), -[`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on managing npm's configuration. +The registry URL used is determined by the scope of the package (see [`scope`](/using-npm/scope). +If no scope is specified, the default registry is used, which is supplied by the [`registry` config](/using-npm/config#registry) parameter. +See [`npm config`](/commands/npm-config), [`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on managing npm's configuration. Authentication configuration such as auth tokens and certificates are configured specifically scoped to an individual registry. -See -[Auth Related Configuration](/configuring-npm/npmrc#auth-related-configuration) +See [Auth Related Configuration](/configuring-npm/npmrc#auth-related-configuration) When the default registry is used in a package-lock or shrinkwrap it has the special meaning of "the currently configured registry". If you create a lock file while using the default registry you can switch to another registry and npm will install packages from the new registry, but if you create a lock file while using a custom registry packages will be installed from that registry even after you change to another registry. @@ -35,21 +31,13 @@ Yes. When making requests of the registry npm adds two headers with information about your environment: -* `Npm-Scope` – If your project is scoped, this header will contain its - scope. -In the future npm hopes to build registry features that use this - information to allow you to customize your experience for your - organization. -* `Npm-In-CI` – Set to "true" if npm believes this install is running in a - continuous integration environment, "false" otherwise. -This is detected by - looking for the following environment variables: `CI`, `TDDIUM`, +* `Npm-Scope` – If your project is scoped, this header will contain its scope. +In the future npm hopes to build registry features that use this information to allow you to customize your experience for your organization. +* `Npm-In-CI` – Set to "true" if npm believes this install is running in a continuous integration environment, "false" otherwise. +This is detected by looking for the following environment variables: `CI`, `TDDIUM`, `JENKINS_URL`, `bamboo.buildKey`. -If you'd like to learn more you may find - the [original PR](https://github.com/npm/npm-registry-client/pull/129) - interesting. - This is used to gather better metrics on how npm is used by humans, versus - build farms. +If you'd like to learn more you may find the [original PR](https://github.com/npm/npm-registry-client/pull/129) interesting. + This is used to gather better metrics on how npm is used by humans, versus build farms. The npm registry does not try to correlate the information in these headers with any authenticated accounts that may be used in the same requests. diff --git a/docs/lib/content/using-npm/removal.md b/docs/lib/content/using-npm/removal.md index 43be8e95dda26..9b431aaf7f38a 100644 --- a/docs/lib/content/using-npm/removal.md +++ b/docs/lib/content/using-npm/removal.md @@ -19,12 +19,10 @@ Or, if that fails, please proceed to more severe uninstalling methods. Usually, the above instructions are sufficient. That will remove npm, but leave behind anything you've installed. -If that doesn't work, or if you require more drastic measures, -continue reading. +If that doesn't work, or if you require more drastic measures, continue reading. Note that this is only necessary for globally-installed packages. -Local installs are completely contained within a project's `node_modules` -folder. +Local installs are completely contained within a project's `node_modules` folder. Delete that folder, and everything is gone unless a package's install script is particularly ill-behaved. This assumes that you installed node and npm in the default place. diff --git a/docs/lib/content/using-npm/scope.md b/docs/lib/content/using-npm/scope.md index 3e5ba7d1141d0..ed069752b63ad 100644 --- a/docs/lib/content/using-npm/scope.md +++ b/docs/lib/content/using-npm/scope.md @@ -8,18 +8,14 @@ description: Scoped packages All npm packages have a name. Some package names also have a scope. -A scope -follows the usual rules for package names (URL-safe characters, no leading dots -or underscores). -When used in package names, scopes are preceded by an `@` symbol -and followed by a slash, e.g. +A scope follows the usual rules for package names (URL-safe characters, no leading dots or underscores). +When used in package names, scopes are preceded by an `@` symbol and followed by a slash, e.g. ```bash @somescope/somepackagename ``` -Scopes are a way of grouping related packages together, and also affect a few -things about the way npm treats the package. +Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package. Each npm user/organization has their own scope, and only you can add packages in your scope. This means you don't have to worry about someone taking your package name ahead of you. @@ -49,27 +45,22 @@ Or in `package.json`: } ``` -Note that if the `@` symbol is omitted, in either case, npm will instead attempt to -install from GitHub; see [`npm install`](/commands/npm-install). +Note that if the `@` symbol is omitted, in either case, npm will instead attempt to install from GitHub; see [`npm install`](/commands/npm-install). ### Requiring scoped packages -Because scoped packages are installed into a scope folder, you have to -include the name of the scope when requiring them in your code, e.g. +Because scoped packages are installed into a scope folder, you have to include the name of the scope when requiring them in your code, e.g. ```javascript require('@myorg/mypackage') ``` There is nothing special about the way Node treats scope folders. -This -simply requires the `mypackage` module in the folder named `@myorg`. +This simply requires the `mypackage` module in the folder named `@myorg`. ### Publishing scoped packages -Scoped packages can be published from the CLI as of `npm@2` and can be -published to any registry that supports them, including the primary npm -registry. +Scoped packages can be published from the CLI as of `npm@2` and can be published to any registry that supports them, including the primary npm registry. (As of 2015-04-19, and with npm 2.0 or better, the primary npm registry **does** support scoped packages.) @@ -83,42 +74,27 @@ Publishing to a scope, you have two options: - Publishing to your user scope (example: `@username/module`) - Publishing to an organization scope (example: `@org/module`) -If publishing a public module to an organization scope, you must -first either create an organization with the name of the scope -that you'd like to publish to or be added to an existing organization -with the appropriate permissions. -For example, if you'd like to -publish to `@org`, you would need to create the `org` organization -on npmjs.com prior to trying to publish. +If publishing a public module to an organization scope, you must first either create an organization with the name of the scope that you'd like to publish to or be added to an existing organization with the appropriate permissions. +For example, if you'd like to publish to `@org`, you would need to create the `org` organization on npmjs.com prior to trying to publish. Scoped packages are not public by default. You will need to specify `--access public` with the initial `npm publish` command. -This will publish -the package and set access to `public` as if you had run `npm access public` -after publishing. -You do not need to do this when publishing new versions of -an existing scoped package. +This will publish the package and set access to `public` as if you had run `npm access public` after publishing. +You do not need to do this when publishing new versions of an existing scoped package. #### Publishing private scoped packages to the npm registry -To publish a private scoped package to the npm registry, you must have -an [npm Private Modules](https://docs.npmjs.com/private-modules/intro) -account. +To publish a private scoped package to the npm registry, you must have an [npm Private Modules](https://docs.npmjs.com/private-modules/intro) account. You can then publish the module with `npm publish` or `npm publish ---access restricted`, and it will be present in the npm registry, with -restricted access. -You can then change the access permissions, if -desired, with `npm access` or on the npmjs.com website. +--access restricted`, and it will be present in the npm registry, with restricted access. +You can then change the access permissions, if desired, with `npm access` or on the npmjs.com website. ### Associating a scope with a registry Scopes can be associated with a separate registry. -This allows you to -seamlessly use a mix of packages from the primary npm registry and one or more -private registries, such as [GitHub Packages](https://github.com/features/packages) or the open source [Verdaccio](https://verdaccio.org) -project. +This allows you to seamlessly use a mix of packages from the primary npm registry and one or more private registries, such as [GitHub Packages](https://github.com/features/packages) or the open source [Verdaccio](https://verdaccio.org) project. You can associate a scope with a registry at login, e.g. @@ -126,8 +102,7 @@ You can associate a scope with a registry at login, e.g. npm login --registry=http://reg.example.com --scope=@myco ``` -Scopes have a many-to-one relationship with registries: one registry can -host multiple scopes, but a scope only ever points to one registry. +Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry. You can also associate a scope with a registry using `npm config`: @@ -135,8 +110,7 @@ You can also associate a scope with a registry using `npm config`: npm config set @myco:registry=http://reg.example.com ``` -Once a scope is associated with a registry, any `npm install` for a package -with that scope will request packages from that registry instead. +Once a scope is associated with a registry, any `npm install` for a package with that scope will request packages from that registry instead. Any `npm publish` for a package name that contains the scope will be published to that registry instead. diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md index 65bb8d230e540..d4a69f46feab7 100644 --- a/docs/lib/content/using-npm/scripts.md +++ b/docs/lib/content/using-npm/scripts.md @@ -8,8 +8,7 @@ description: How npm handles the "scripts" field The `"scripts"` property of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts. These all can be executed by running `npm run `. -*Pre* and *post* -commands with matching names will be run for those as well (e.g. +*Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). Scripts from dependencies can be run with `npm explore -- npm run `. @@ -42,23 +41,18 @@ These scripts happen in addition to the `pre`, `post`, and **prepare** (since `npm@4.0.0`) * Runs BEFORE the package is packed, i.e. -during `npm publish` - and `npm pack` +during `npm publish` and `npm pack` * Runs on local `npm install` without any arguments * Runs AFTER `prepublish`, but BEFORE `prepublishOnly` * Runs for a package if it's being installed as a link through `npm install ` -* NOTE: If a package being installed through git contains a `prepare` - script, its `dependencies` and `devDependencies` will be installed, and - the prepare script will be run, before the package is packaged and - installed. +* NOTE: If a package being installed through git contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed. * As of `npm@7` these scripts run in the background. To see the output, run with: `--foreground-scripts`. **prepublish** (DEPRECATED) -* Does not run during `npm publish`, but does run during `npm ci` - and `npm install`. +* Does not run during `npm publish`, but does run during `npm ci` and `npm install`. See below for more info. **prepublishOnly** @@ -98,12 +92,9 @@ This includes tasks such as: The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that: -* You can depend on `coffee-script` as a `devDependency`, and thus - your users don't need to have it installed. -* You don't need to include minifiers in your package, reducing - the size for your users. -* You don't need to rely on your users having `curl` or `wget` or - other system tools on the target machines. +* You can depend on `coffee-script` as a `devDependency`, and thus your users don't need to have it installed. +* You don't need to include minifiers in your package, reducing the size for your users. +* You don't need to rely on your users having `curl` or `wget` or other system tools on the target machines. #### Dependencies @@ -278,8 +269,7 @@ then you could run `npm start` to execute the `bar` script, which is exported in #### package.json vars The package.json fields are tacked onto the `npm_package_` prefix. -So, -for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then your package scripts would have the `npm_package_name` environment variable set to "foo", and the `npm_package_version` set to "1.2.5". You can access these variables in your code with `process.env.npm_package_name` and `process.env.npm_package_version`, and so on for other fields. +So, for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then your package scripts would have the `npm_package_name` environment variable set to "foo", and the `npm_package_version` set to "1.2.5". You can access these variables in your code with `process.env.npm_package_name` and `process.env.npm_package_version`, and so on for other fields. See [`package.json`](/configuring-npm/package-json) for more on package configs. @@ -308,10 +298,8 @@ For example, if your package.json contains this: } ``` -then `scripts/install.js` will be called for the install and post-install -stages of the lifecycle. -Since `scripts/install.js` is running for two -different phases, it would be wise in this case to look at the +then `scripts/install.js` will be called for the install and post-install stages of the lifecycle. +Since `scripts/install.js` is running for two different phases, it would be wise in this case to look at the `npm_lifecycle_event` environment variable. If you want to run a make command, you can do so. @@ -334,39 +322,25 @@ You can control which shell is used by setting the [`script-shell`](/using-npm/c If the script exits with a code other than 0, then this will abort the process. -Note that these script files don't have to be Node.js or even -JavaScript programs. +Note that these script files don't have to be Node.js or even JavaScript programs. They just have to be some kind of executable file. ### Best Practices * Don't exit with a non-zero error code unless you *really* mean it. - If the failure is minor or only will prevent some optional features, then - it's better to just print a warning and exit successfully. + If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully. * Try not to use scripts to do what npm can do for you. -Read through - [`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable - by simply describing your package appropriately. -In general, this - will lead to a more robust and consistent state. +Read through [`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable by simply describing your package appropriately. +In general, this will lead to a more robust and consistent state. * Inspect the env to determine where to put things. -For instance, if - the `npm_config_binroot` environment variable is set to `/home/user/bin`, then - don't try to install executables into `/usr/local/bin`. -The user - probably set it up that way for a reason. -* Don't prefix your script commands with "sudo". If root permissions - are required for some reason, then it'll fail with that error, and - the user will sudo the npm command in question. +For instance, if the `npm_config_binroot` environment variable is set to `/home/user/bin`, then don't try to install executables into `/usr/local/bin`. +The user probably set it up that way for a reason. +* Don't prefix your script commands with "sudo". If root permissions are required for some reason, then it'll fail with that error, and the user will sudo the npm command in question. * Don't use `install`. -Use a `.gyp` file for compilation, and `prepare` - for anything else. -You should almost never have to explicitly set a - preinstall or install script. -If you are doing this, please consider if - there is another option. -The only valid use of `install` or `preinstall` - scripts is for compilation which must be done on the target architecture. +Use a `.gyp` file for compilation, and `prepare` for anything else. +You should almost never have to explicitly set a preinstall or install script. +If you are doing this, please consider if there is another option. +The only valid use of `install` or `preinstall` scripts is for compilation which must be done on the target architecture. ### See Also diff --git a/docs/lib/content/using-npm/workspaces.md b/docs/lib/content/using-npm/workspaces.md index 86dac0b94bb83..e7f87ed2609cc 100644 --- a/docs/lib/content/using-npm/workspaces.md +++ b/docs/lib/content/using-npm/workspaces.md @@ -16,8 +16,7 @@ We also refer to these packages being auto-symlinked during `npm install` as a s ### Defining workspaces -Workspaces are usually defined via the `workspaces` property of the -[`package.json`](/configuring-npm/package-json#workspaces) file, e.g: +Workspaces are usually defined via the `workspaces` property of the [`package.json`](/configuring-npm/package-json#workspaces) file, e.g: ```json { @@ -55,16 +54,14 @@ Below is a post `npm install` example, given that same previous example structur ### Getting started with workspaces -You may automate the required steps to define a new workspace using -[npm init](/commands/npm-init). +You may automate the required steps to define a new workspace using [npm init](/commands/npm-init). For example in a project that already has a `package.json` defined you can run: ``` npm init -w ./packages/a ``` -This command will create the missing folders and a new `package.json` -file (if needed) while also making sure to properly configure the +This command will create the missing folders and a new `package.json` file (if needed) while also making sure to properly configure the `"workspaces"` property of your root project `package.json`. ### Adding dependencies to a workspace @@ -94,8 +91,7 @@ Note: other installing commands such as `uninstall`, `ci`, etc will also respect ### Using workspaces Given the [specifics of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace by its declared `package.json` `name`. -Continuing from the example defined above, let's also create a Node.js script that will require the workspace `a` -example module, e.g: +Continuing from the example defined above, let's also create a Node.js script that will require the workspace `a` example module, e.g: ``` // ./packages/a/index.js @@ -111,14 +107,12 @@ When running it with: `node lib/index.js` This demonstrates how the nature of `node_modules` resolution allows for -**workspaces** to enable a portable workflow for requiring each **workspace** -in such a way that is also easy to [publish](/commands/npm-publish) these nested workspaces to be consumed elsewhere. +**workspaces** to enable a portable workflow for requiring each **workspace** in such a way that is also easy to [publish](/commands/npm-publish) these nested workspaces to be consumed elsewhere. ### Running commands in the context of workspaces You can use the `workspace` configuration option to run commands in the context of a configured workspace. -Additionally, if your current directory is in a workspace, the `workspace` -configuration is implicitly set, and `prefix` is set to the root workspace. +Additionally, if your current directory is in a workspace, the `workspace` configuration is implicitly set, and `prefix` is set to the root workspace. Following is a quick example on how to use the `npm run` command in the context of nested workspaces. For a project containing multiple workspaces, e.g: @@ -160,8 +154,7 @@ Or run the command for each workspace within the 'packages' folder: npm run test --workspace=packages ``` -It's also possible to use the `workspaces` (plural) configuration option to enable the same behavior but running that command in the context of **all** -configured workspaces. +It's also possible to use the `workspaces` (plural) configuration option to enable the same behavior but running that command in the context of **all** configured workspaces. e.g: ```