bunny-lab/Borealis
2
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Removed the Requirement to Install Python and NodeJS (Now Bundled with Borealis)

Browse Source
This commit is contained in:
Nicole Rappe
2025-04-24 00:42:19 -06:00
parent 785265d3e7
commit 9c68cdea84
7786 changed files with 2386458 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2020
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/config.md generated vendored Normal file
View File

File diff suppressed because it is too large Load Diff

223
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/dependency-selectors.md generated vendored Normal file
View File

@ -0,0 +1,223 @@
---
title: Dependency Selector Syntax & Querying
section: 7
description: Dependency Selector Syntax & Querying
---
### Description
The [`npm query`](/commands/npm-query) command exposes a new dependency selector syntax (informed by & respecting many aspects of the [CSS Selectors 4 Spec](https://dev.w3.org/csswg/selectors4/#relational)) which:
- Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax
- Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible
- Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
- Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
### Dependency Selector Syntax
#### Overview:
- there is no "type" or "tag" selectors (ex. `div, h1, a`) as a dependency/target is the only type of `Node` that can be queried
- the term "dependencies" is in reference to any `Node` found in a `tree` returned by `Arborist`
#### Combinators
- `>` direct descendant/child
- ` ` any descendant/child
- `~` sibling
#### Selectors
- `*` universal selector
- `#<name>` dependency selector (equivalent to `[name="..."]`)
- `#<name>@<version>` (equivalent to `[name=<name>]:semver(<version>)`)
- `,` selector list delimiter
- `.` dependency type selector
- `:` pseudo selector
#### Dependency Type Selectors
- `.prod` dependency found in the `dependencies` section of `package.json`, or is a child of said dependency
- `.dev` dependency found in the `devDependencies` section of `package.json`, or is a child of said dependency
- `.optional` dependency found in the `optionalDependencies` section of `package.json`, or has `"optional": true` set in its entry in the `peerDependenciesMeta` section of `package.json`, or a child of said dependency
- `.peer` dependency found in the `peerDependencies` section of `package.json`
- `.workspace` dependency found in the [`workspaces`](https://docs.npmjs.com/cli/v8/using-npm/workspaces) section of `package.json`
- `.bundled` dependency found in the `bundleDependencies` section of `package.json`, or is a child of said dependency
#### Pseudo Selectors
- [`:not(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
- [`:has(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)
- [`:is(<selector list>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:is)
- [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) matches the root node/dependency
- [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) matches node/dependency it was queried against
- [`:empty`](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty) when a dependency has no dependencies
- [`:private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) when a dependency is private
- `:link` when a dependency is linked (for instance, workspaces or packages manually [`linked`](https://docs.npmjs.com/cli/v8/commands/npm-link)
- `:deduped` when a dependency has been deduped (note that this does *not* always mean the dependency has been hoisted to the root of node_modules)
- `:overridden` when a dependency has been overridden
- `:extraneous` when a dependency exists but is not defined as a dependency of any node
- `:invalid` when a dependency version is out of its ancestors specified range
- `:missing` when a dependency is not found on disk
- `:semver(<spec>, [selector], [function])` match a valid [`node-semver`](https://github.com/npm/node-semver) version or range to a selector
- `:path(<path>)` [glob](https://www.npmjs.com/package/glob) matching based on dependencies path relative to the project
- `:type(<type>)` [based on currently recognized types](https://github.com/npm/npm-package-arg#result-object)
- `:outdated(<type>)` when a dependency is outdated
- `:vuln(<selector>)` when a dependency has a known vulnerability
##### `:semver(<spec>, [selector], [function])`
The `:semver()` pseudo selector allows comparing fields from each node's `package.json` using [semver](https://github.com/npm/node-semver#readme) methods. It accepts up to 3 parameters, all but the first of which are optional.
- `spec` a semver version or range
- `selector` an attribute selector for each node (default `[version]`)
- `function` a semver method to apply, one of: `satisfies`, `intersects`, `subset`, `gt`, `gte`, `gtr`, `lt`, `lte`, `ltr`, `eq`, `neq` or the special function `infer` (default `infer`)
When the special `infer` function is used the `spec` and the actual value from the node are compared. If both are versions, according to `semver.valid()`, `eq` is used. If both values are ranges, according to `!semver.valid()`, `intersects` is used. If the values are mixed types `satisfies` is used.
Some examples:
- `:semver(^1.0.0)` returns every node that has a `version` satisfied by the provided range `^1.0.0`
- `:semver(16.0.0, :attr(engines, [node]))` returns every node which has an `engines.node` property satisfying the version `16.0.0`
- `:semver(1.0.0, [version], lt)` every node with a `version` less than `1.0.0`
##### `:outdated(<type>)`
The `:outdated` pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated. The type parameter may be one of the following:
- `any` (default) a version exists that is greater than the current one
- `in-range` a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies
- `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its parent's dependencies
- `major` a version exists that is a semver major greater than the current one
- `minor` a version exists that is a semver minor greater than the current one
- `patch` a version exists that is a semver patch greater than the current one
In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects. The following data can be found under the `queryContext` property of each node.
- `versions` an array of every available version of the given node
- `outdated.inRange` an array of objects, each with a `from` and `versions`, where `from` is the on-disk location of the node that depends on the current node and `versions` is an array of all available versions that satisfies that dependency. This is only populated if `:outdated(in-range)` is used.
- `outdated.outOfRange` an array of objects, identical in shape to `inRange`, but where the `versions` array is every available version that does not satisfy the dependency. This is only populated if `:outdated(out-of-range)` is used.
Some examples:
- `:root > :outdated(major)` returns every direct dependency that has a new semver major release
- `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its parent's dependencies
##### `:vuln`
The `:vuln` pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability. Only dependencies whose current version matches a vulnerability will be returned. For example if you have `semver@7.6.0` in your tree, a vulnerability for `semver` which affects versions `<=6.3.1` will not match.
You can also filter results by certain attributes in advisories. Currently that includes `severity` and `cwe`. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the `queryContext` attribute of each node under the `advisories` attribute.
Some examples:
- `:root > .prod:vuln` returns direct production dependencies with any known vulnerability
- `:vuln([severity=high])` returns only dependencies with a vulnerability with a `high` severity.
- `:vuln([severity=high],[severity=moderate])` returns only dependencies with a vulnerability with a `high` or `moderate` severity.
- `:vuln([cwe=1333])` returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)
#### [Attribute Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
- `[]` attribute selector (ie. existence of attribute)
- `[attribute=value]` attribute value is equivalent...
- `[attribute~=value]` attribute value contains word...
- `[attribute*=value]` attribute value contains string...
- `[attribute|=value]` attribute value is equal to or starts with...
- `[attribute^=value]` attribute value starts with...
- `[attribute$=value]` attribute value ends with...
#### `Array` & `Object` Attribute Selectors
The generic `:attr()` pseudo selector standardizes a pattern which can be used for attribute selection of `Object`s, `Array`s or `Arrays` of `Object`s accessible via `Arborist`'s `Node.package` metadata. This allows for iterative attribute selection beyond top-level `String` evaluation. The last argument passed to `:attr()` must be an `attribute` selector or a nested `:attr()`. See examples below:
#### `Objects`
```css
/* return dependencies that have a `scripts.test` containing `"tap"` */
*:attr(scripts, [test~=tap])
```
#### Nested `Objects`
Nested objects are expressed as sequential arguments to `:attr()`.
```css
/* return dependencies that have a testling config for opera browsers */
*:attr(testling, browsers, [~=opera])
```
#### `Arrays`
`Array`s specifically uses a special/reserved `.` character in place of a typical attribute name. `Arrays` also support exact `value` matching when a `String` is passed to the selector.
##### Example of an `Array` Attribute Selection:
```css
/* removes the distinction between properties & arrays */
/* ie. we'd have to check the property & iterate to match selection */
*:attr([keywords^=react])
*:attr(contributors, :attr([name~=Jordan]))
```
##### Example of an `Array` matching directly to a value:
```css
/* return dependencies that have the exact keyword "react" */
/* this is equivalent to `*:keywords([value="react"])` */
*:attr([keywords=react])
```
##### Example of an `Array` of `Object`s:
```css
/* returns */
*:attr(contributors, [email=ruyadorno@github.com])
```
### Groups
Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in `package.json`). This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost. Dependencies are allowed to be included in multiple groups (ex. a `prod` dependency may also be a `dev` dependency (in that it's also required by another `dev` dependency) & may also be `bundled` - a selector for that type of dependency would look like: `*.prod.dev.bundled`).
- `.prod`
- `.dev`
- `.optional`
- `.peer`
- `.bundled`
- `.workspace`
Please note that currently `workspace` deps are always `prod` dependencies. Additionally the `.root` dependency is also considered a `prod` dependency.
### Programmatic Usage
- `Arborist`'s `Node` Class has a `.querySelectorAll()` method
- this method will return a filtered, flattened dependency Arborist `Node` list based on a valid query selector
```js
const Arborist = require('@npmcli/arborist')
const arb = new Arborist({})
```
```js
// root-level
arb.loadActual().then(async (tree) => {
// query all production dependencies
const results = await tree.querySelectorAll('.prod')
console.log(results)
})
```
```js
// iterative
arb.loadActual().then(async (tree) => {
// query for the deduped version of react
const results = await tree.querySelectorAll('#react:not(:deduped)')
// query the deduped react for git deps
const deps = await results[0].querySelectorAll(':type(git)')
console.log(deps)
})
```
## See Also
* [npm query](/commands/npm-query)
* [@npmcli/arborist](https://npm.im/@npmcli/arborist)

245
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/developers.md generated vendored Normal file
View File

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

96
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/logging.md generated vendored Normal file
View File

@ -0,0 +1,96 @@
---
title: Logging
section: 7
description: Why, What & How We Log
---
### Description
The `npm` CLI has various mechanisms for showing different levels of information back to end-users for certain commands, configurations & environments.
### Setting Log File Location
All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
The default location of the logs directory is a directory named `_logs` inside the npm cache. This can be changed with the `logs-dir` config option.
For example, if you wanted to write all your logs to the current working directory, you could run: `npm install --logs-dir=.`. This is especially helpful in debugging a specific `npm` issue as you can run
a command multiple times with different config values and then diff all the log files.
Log files will be removed from the `logs-dir` when the number of log files exceeds `logs-max`, with the oldest logs being deleted first.
To turn off logs completely set `--logs-max=0`.
### Setting Log Levels
#### `loglevel`
`loglevel` is a global argument/config that can be set to determine the type of information to be displayed.
The default value of `loglevel` is `"notice"` but there are several levels/types of logs available, including:
- `"silent"`
- `"error"`
- `"warn"`
- `"notice"`
- `"http"`
- `"info"`
- `"verbose"`
- `"silly"`
All logs pertaining to a level proceeding the current setting will be shown.
##### Aliases
The log levels listed above have various corresponding aliases, including:
- `-d`: `--loglevel info`
- `--dd`: `--loglevel verbose`
- `--verbose`: `--loglevel verbose`
- `--ddd`: `--loglevel silly`
- `-q`: `--loglevel warn`
- `--quiet`: `--loglevel warn`
- `-s`: `--loglevel silent`
- `--silent`: `--loglevel silent`
#### `foreground-scripts`
The `npm` CLI began hiding the output of lifecycle scripts for `npm install` as of `v7`. Notably, this means you will not see logs/output from packages that may be using "install scripts" to display information back to you or from your own project's scripts defined in `package.json`. If you'd like to change this behavior & log this output you can set `foreground-scripts` to `true`.
### Timing Information
The [`--timing` config](/using-npm/config#timing) can be set which does a few
things:
1. Always shows the full path to the debug log regardless of command exit status
1. Write timing information to a process specific timing file in the cache or `logs-dir`
1. Output timing information to the terminal
This file contains a `timers` object where the keys are an identifier for the
portion of the process being timed and the value is the number of milliseconds it took to complete.
Sometimes it is helpful to get timing information without outputting anything to the terminal. For
example, the performance might be affected by writing to the terminal. In this case you can use
`--timing --silent` which will still write the timing file, but not output anything to the terminal
while running.
### Registry Response Headers
#### `npm-notice`
The `npm` CLI reads from & logs any `npm-notice` headers that are returned from the configured registry. This mechanism can be used by third-party registries to provide useful information when network-dependent requests occur.
This header is not cached, and will not be logged if the request is served from the cache.
### Logs and Sensitive Information
The `npm` CLI makes a best effort to redact the following from terminal output and log files:
- Passwords inside basic auth URLs
- npm tokens
However, this behavior should not be relied on to keep all possible sensitive information redacted. If you are concerned about secrets in your log file or terminal output, you can use `--loglevel=silent` and `--logs-max=0` to ensure no logs are written to your terminal or filesystem.
### See also
* [config](/using-npm/config)

93
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/orgs.md generated vendored Normal file
View File

@ -0,0 +1,93 @@
---
title: orgs
section: 7
description: Working with Teams & Orgs
---
### Description
There are three levels of org users:
1. Super admin, controls billing & adding people to the org.
2. Team admin, manages team membership & package access.
3. Developer, works on packages they are given access to.
The super admin is the only person who can add users to the org because it impacts the monthly bill. The super admin will use the website to manage membership. Every org has a `developers` team that all users are automatically added to.
The team admin is the person who manages team creation, team membership, and package access for teams. The team admin grants package access to teams, not individuals.
The developer will be able to access packages based on the teams they are on. Access is either read-write or read-only.
There are two main commands:
1. `npm team` see [npm team](/commands/npm-team) for more details
2. `npm access` see [npm access](/commands/npm-access) for more details
### Team Admins create teams
* Check who you’ve added to your org:
```bash
npm team ls <org>:developers
```
* Each org is automatically given a `developers` team, so you can see the whole list of team members in your org. This team automatically gets read-write access to all packages, but you can change that with the `access` command.
* Create a new team:
```bash
npm team create <org:team>
```
* Add members to that team:
```bash
npm team add <org:team> <user>
```
### Publish a package and adjust package access
* In package directory, run
```bash
npm init --scope=<org>
```
to scope it for your org & publish as usual
* Grant access:
```bash
npm access grant <read-only|read-write> <org:team> [<package>]
```
* Revoke access:
```bash
npm access revoke <org:team> [<package>]
```
### Monitor your package access
* See what org packages a team member can access:
```bash
npm access ls-packages <org> <user>
```
* See packages available to a specific team:
```bash
npm access ls-packages <org:team>
```
* Check which teams are collaborating on a package:
```bash
npm access ls-collaborators <pkg>
```
### See also
* [npm team](/commands/npm-team)
* [npm access](/commands/npm-access)
* [npm scope](/using-npm/scope)

105
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/package-spec.md generated vendored Normal file
View File

@ -0,0 +1,105 @@
---
title: package-spec
section: 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. These will generally be referred
to as `<package-spec>` in the help output for the npm commands that use
this package name specifier.
### Package name
* `[<@scope>/]<pkg>`
* `[<@scope>/]<pkg>@<tag>`
* `[<@scope>/]<pkg>@<version>`
* `[<@scope>/]<pkg>@<version range>`
Refers to a package by name, with or without a scope, and optionally
tag, version, or version range. This is typically used in combination
with the [registry](/using-npm/config#registry) config to refer to a
package in a registry.
Examples:
* `npm`
* `@npmcli/arborist`
* `@npmcli/arborist@latest`
* `npm@6.13.1`
* `npm@^4.0.0`
### Aliases
* `<alias>@npm:<name>`
Primarily used by commands like `npm install` and in the dependency
sections in the `package.json`, this refers to a package by an alias.
The `<alias>` is the name of the package as it is reified in the
`node_modules` folder, and the `<name>` refers to a package name as
found in the configured registry.
See `Package name` above for more info on referring to a package by
name, and [registry](/using-npm/config#registry) for configuring which
registry is used when referring to a package by name.
Examples:
* `semver:@npm:@npmcli/semver-with-patch`
* `semver:@npm:semver@7.2.2`
* `semver:@npm:semver@legacy`
### Folders
* `<folder>`
This refers to a package on the local filesystem. Specifically this is
a folder with a `package.json` file in it. This *should* always be
prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion.
npm currently will parse a string with more than one `/` in it as a
folder, but this is legacy behavior that may be removed in a future
version.
Examples:
* `./my-package`
* `/opt/npm/my-package`
### Tarballs
* `<tarball file>`
* `<tarball url>`
Examples:
* `./my-package.tgz`
* `https://registry.npmjs.org/semver/-/semver-1.0.0.tgz`
Refers to a package in a tarball format, either on the local filesystem
or remotely via url. This is the format that packages exist in when
uploaded to a registry.
### git urls
* `<git:// url>`
* `<github username>/<github project>`
Refers to a package in a git repo. This can be a full git url, git
shorthand, or a username/package on GitHub. You can specify a
git tag, branch, or other git ref by appending `#ref`.
Examples:
* `https://github.com/npm/cli.git`
* `git@github.com:npm/cli.git`
* `git+ssh://git@github.com/npm/cli#v6.0.0`
* `github:npm/cli#HEAD`
* `npm/cli#c12ea07`
### See also
* [npm-package-arg](https://npm.im/npm-package-arg)
* [scope](/using-npm/scope)
* [config](/using-npm/config)

86
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/registry.md generated vendored Normal file
View File

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

60
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/removal.md generated vendored Normal file
View File

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

143
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/scope.md generated vendored Normal file
View File

@ -0,0 +1,143 @@
---
title: scope
section: 7
description: Scoped packages
---
### Description
All npm packages have a name. Some package names also have a scope. A scope
follows the usual rules for package names (URL-safe characters, no leading dots
or underscores). When used in package names, scopes are preceded by an `@` symbol
and followed by a slash, e.g.
```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.
Each npm user/organization has their own scope, and only you can add packages
in your scope. This means you don't have to worry about someone taking your
package name ahead of you. Thus it is also a good way to signal official packages
for organizations.
Scoped packages can be published and installed as of `npm@2` and are supported
by the primary npm registry. Unscoped packages can depend on scoped packages and
vice versa. The npm client is backwards-compatible with unscoped registries,
so it can be used to work with scoped and unscoped registries at the same time.
### Installing scoped packages
Scoped packages are installed to a sub-folder of the regular installation
folder, e.g. if your other packages are installed in `node_modules/packagename`,
scoped modules will be installed in `node_modules/@myorg/packagename`. The scope
folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can
contain any number of scoped packages.
A scoped package is installed by referencing it by name, preceded by an
`@` symbol, in `npm install`:
```bash
npm install @myorg/mypackage
```
Or in `package.json`:
```json
"dependencies": {
"@myorg/mypackage": "^1.3.0"
}
```
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.
```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`.
### 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.
(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry
**does** support scoped packages.)
If you wish, you may associate a scope with a registry; see below.
#### Publishing public scoped packages to the primary npm registry
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.
Scoped packages are not public by default. You will need to specify
`--access public` with the initial `npm publish` command. This will publish
the package and set access to `public` as if you had run `npm access public`
after publishing. You do not need to do this when publishing new versions of
an existing scoped package.
#### Publishing private scoped packages to the npm registry
To publish a private scoped package to the npm registry, you must have
an [npm Private Modules](https://docs.npmjs.com/private-modules/intro)
account.
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.
### 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.
You can associate a scope with a registry at login, e.g.
```bash
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.
You can also associate a scope with a registry using `npm config`:
```bash
npm config set @myco:registry=http://reg.example.com
```
Once a scope is associated with a registry, any `npm install` for a package
with that scope will request packages from that registry instead. Any
`npm publish` for a package name that contains the scope will be published to
that registry instead.
### See also
* [npm install](/commands/npm-install)
* [npm publish](/commands/npm-publish)
* [npm access](/commands/npm-access)
* [npm registry](/using-npm/registry)

363
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/scripts.md generated vendored Normal file
View File

@ -0,0 +1,363 @@
---
title: scripts
section: 7
description: How npm handles the "scripts" field
---
### Description
The `"scripts"` property of your `package.json` file supports a number
of built-in scripts and their preset life cycle events as well as
arbitrary scripts. These all can be executed by running
`npm run-script <stage>` or `npm run <stage>` for short. *Pre* and *post*
commands with matching names will be run for those as well (e.g. `premyscript`,
`myscript`, `postmyscript`). Scripts from dependencies can be run with
`npm explore <pkg> -- npm run <stage>`.
### Pre & Post Scripts
To create "pre" or "post" scripts for any scripts defined in the
`"scripts"` section of the `package.json`, simply create another script
*with a matching name* and add "pre" or "post" to the beginning of them.
```json
{
"scripts": {
"precompress": "{{ executes BEFORE the `compress` script }}",
"compress": "{{ run command to compress files }}",
"postcompress": "{{ executes AFTER `compress` script }}"
}
}
```
In this example `npm run compress` would execute these scripts as
described.
### Life Cycle Scripts
There are some special life cycle scripts that happen only in certain
situations. These scripts happen in addition to the `pre<event>`, `post<event>`, and
`<event>` scripts.
* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`, `dependencies`
**prepare** (since `npm@4.0.0`)
* Runs BEFORE the package is packed, i.e. during `npm publish`
and `npm pack`
* Runs on local `npm install` without any arguments
* Runs AFTER `prepublish`, but BEFORE `prepublishOnly`
* NOTE: If a package being installed through git contains a `prepare`
script, its `dependencies` and `devDependencies` will be installed, and
the prepare script will be run, before the package is packaged and
installed.
* As of `npm@7` these scripts run in the background.
To see the output, run with: `--foreground-scripts`.
**prepublish** (DEPRECATED)
* Does not run during `npm publish`, but does run during `npm ci`
and `npm install`. See below for more info.
**prepublishOnly**
* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
**prepack**
* Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependency).
* NOTE: "`npm run pack`" is NOT the same as "`npm pack`". "`npm run pack`" is an arbitrary user defined script name, where as, "`npm pack`" is a CLI defined command.
**postpack**
* Runs AFTER the tarball has been generated but before it is moved to its final destination (if at all, publish does not save the tarball locally)
**dependencies**
* Runs AFTER any operations that modify the `node_modules` directory IF changes occurred.
* Does NOT run in global mode
#### Prepare and Prepublish
**Deprecation Note: prepublish**
Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape).
See <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change.
**Use Cases**
If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as:
* Compiling CoffeeScript source code into JavaScript.
* Creating minified versions of JavaScript source code.
* Fetching remote resources that your package will use.
The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:
* You can depend on `coffee-script` as a `devDependency`, and thus
your users don't need to have it installed.
* You don't need to include minifiers in your package, reducing
the size for your users.
* You don't need to rely on your users having `curl` or `wget` or
other system tools on the target machines.
#### Dependencies
The `dependencies` script is run any time an `npm` command causes changes to the `node_modules` directory. It is run AFTER the changes have been applied and the `package.json` and `package-lock.json` files have been updated.
### Life Cycle Operation Order
#### [`npm cache add`](/commands/npm-cache)
* `prepare`
#### [`npm ci`](/commands/npm-ci)
* `preinstall`
* `install`
* `postinstall`
* `prepublish`
* `preprepare`
* `prepare`
* `postprepare`
These all run after the actual installation of modules into
`node_modules`, in order, with no internal actions happening in between
#### [`npm diff`](/commands/npm-diff)
* `prepare`
#### [`npm install`](/commands/npm-install)
These also run when you run `npm install -g <pkg-name>`
* `preinstall`
* `install`
* `postinstall`
* `prepublish`
* `preprepare`
* `prepare`
* `postprepare`
If there is a `binding.gyp` file in the root of your package and you
haven't defined your own `install` or `preinstall` scripts, npm will
default the `install` command to compile using node-gyp via `node-gyp
rebuild`
These are run from the scripts of `<pkg-name>`
#### [`npm pack`](/commands/npm-pack)
* `prepack`
* `prepare`
* `postpack`
#### [`npm publish`](/commands/npm-publish)
* `prepublishOnly`
* `prepack`
* `prepare`
* `postpack`
* `publish`
* `postpublish`
#### [`npm rebuild`](/commands/npm-rebuild)
* `preinstall`
* `install`
* `postinstall`
* `prepare`
`prepare` is only run if the current directory is a symlink (e.g. with
linked packages)
#### [`npm restart`](/commands/npm-restart)
If there is a `restart` script defined, these events are run, otherwise
`stop` and `start` are both run if present, including their `pre` and
`post` iterations)
* `prerestart`
* `restart`
* `postrestart`
#### [`npm run <user defined>`](/commands/npm-run-script)
* `pre<user-defined>`
* `<user-defined>`
* `post<user-defined>`
#### [`npm start`](/commands/npm-start)
* `prestart`
* `start`
* `poststart`
If there is a `server.js` file in the root of your package, then npm
will default the `start` command to `node server.js`. `prestart` and
`poststart` will still run in this case.
#### [`npm stop`](/commands/npm-stop)
* `prestop`
* `stop`
* `poststop`
#### [`npm test`](/commands/npm-test)
* `pretest`
* `test`
* `posttest`
#### [`npm version`](/commands/npm-version)
* `preversion`
* `version`
* `postversion`
#### A Note on a lack of [`npm uninstall`](/commands/npm-uninstall) scripts
While npm v6 had `uninstall` lifecycle scripts, npm v7 does not. Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful.
Reasons for a package removal include:
* a user directly uninstalled this package
* a user uninstalled a dependant package and so this dependency is being uninstalled
* a user uninstalled a dependant package but another package also depends on this version
* this version has been merged as a duplicate with another version
* etc.
Due to the lack of necessary context, `uninstall` lifecycle scripts are not implemented and will not function.
### User
When npm is run as root, scripts are always run with the effective uid
and gid of the working directory owner.
### Environment
Package scripts run in an environment where many pieces of information
are made available regarding the setup of npm and the current state of
the process.
#### path
If you depend on modules that define executable scripts, like test
suites, then those executables will be added to the `PATH` for
executing the scripts. So, if your package.json has this:
```json
{
"name" : "foo",
"dependencies" : {
"bar" : "0.1.x"
},
"scripts": {
"start" : "bar ./test"
}
}
```
then you could run `npm start` to execute the `bar` script, which is
exported into the `node_modules/.bin` directory on `npm install`.
#### package.json vars
The package.json fields are tacked onto the `npm_package_` prefix. So,
for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your
package.json file, then your package scripts would have the
`npm_package_name` environment variable set to "foo", and the
`npm_package_version` set to "1.2.5". You can access these variables
in your code with `process.env.npm_package_name` and
`process.env.npm_package_version`, and so on for other fields.
See [`package.json`](/configuring-npm/package-json) for more on package configs.
#### current lifecycle event
Lastly, the `npm_lifecycle_event` environment variable is set to
whichever stage of the cycle is being executed. So, you could have a
single script used for different parts of the process which switches
based on what's currently happening.
Objects are flattened following this format, so if you had
`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd
see this in the script:
```bash
process.env.npm_package_scripts_install === "foo.js"
```
### Examples
For example, if your package.json contains this:
```json
{
"scripts" : {
"install" : "scripts/install.js",
"postinstall" : "scripts/install.js"
}
}
```
then `scripts/install.js` will be called for the install and post-install
stages of the lifecycle. Since `scripts/install.js` is running for two
different phases, it would be wise in this case to look at the
`npm_lifecycle_event` environment variable.
If you want to run a make command, you can do so. This works just
fine:
```json
{
"scripts" : {
"preinstall" : "./configure",
"install" : "make && make install",
"test" : "make test"
}
}
```
### Exiting
Scripts are run by passing the line as a script argument to `sh`.
If the script exits with a code other than 0, then this will abort the
process.
Note that these script files don't have to be Node.js or even
JavaScript programs. They just have to be some kind of executable
file.
### Best Practices
* Don't exit with a non-zero error code unless you *really* mean it.
If the failure is minor or only will prevent some optional features, then
it's better to just print a warning and exit successfully.
* Try not to use scripts to do what npm can do for you. Read through
[`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable
by simply describing your package appropriately. In general, this
will lead to a more robust and consistent state.
* Inspect the env to determine where to put things. For instance, if
the `npm_config_binroot` environment variable is set to `/home/user/bin`, then
don't try to install executables into `/usr/local/bin`. The user
probably set it up that way for a reason.
* Don't prefix your script commands with "sudo". If root permissions
are required for some reason, then it'll fail with that error, and
the user will sudo the npm command in question.
* Don't use `install`. Use a `.gyp` file for compilation, and `prepare`
for anything else. You should almost never have to explicitly set a
preinstall or install script. If you are doing this, please consider if
there is another option. The only valid use of `install` or `preinstall`
scripts is for compilation which must be done on the target architecture.
* Scripts are run from the root of the package folder, regardless of what the
current working directory is when `npm` is invoked. 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`.
### See Also
* [npm run-script](/commands/npm-run-script)
* [package.json](/configuring-npm/package-json)
* [npm developers](/using-npm/developers)
* [npm install](/commands/npm-install)

226
Dependencies/NodeJS/node_modules/npm/docs/content/using-npm/workspaces.md generated vendored Normal file
View File

@ -0,0 +1,226 @@
---
title: workspaces
section: 7
description: Working with workspaces
---
### Description
**Workspaces** is a generic term that refers to the set of features in the
npm cli that provides support for managing multiple packages from your local
file system from within a singular top-level, root package.
This set of features makes up for a much more streamlined workflow handling
linked packages from the local file system. It automates the linking process
as part of `npm install` and removes the need to manually use `npm link` in
order to add references to packages that should be symlinked into the current
`node_modules` folder.
We also refer to these packages being auto-symlinked during `npm install` as a
single **workspace**, meaning it's a nested package within the current local
file system that is explicitly defined in the [`package.json`](/configuring-npm/package-json#workspaces)
`workspaces` configuration.
### Defining workspaces
Workspaces are usually defined via the `workspaces` property of the
[`package.json`](/configuring-npm/package-json#workspaces) file, e.g:
```json
{
"name": "my-workspaces-powered-project",
"workspaces": [
"packages/a"
]
}
```
Given the above `package.json` example living at a current working
directory `.` that contains a folder named `packages/a` that itself contains
a `package.json` inside it, defining a Node.js package, e.g:
```
.
+-- package.json
`-- packages
+-- a
| `-- package.json
```
The expected result once running `npm install` in this current working
directory `.` is that the folder `packages/a` will get symlinked to the
`node_modules` folder of the current working dir.
Below is a post `npm install` example, given that same previous example
structure of files and folders:
```
.
+-- node_modules
| `-- a -> ../packages/a
+-- package-lock.json
+-- package.json
`-- packages
+-- a
| `-- package.json
```
### Getting started with workspaces
You may automate the required steps to define a new workspace using
[npm init](/commands/npm-init). For example in a project that already has a
`package.json` defined you can run:
```
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
`"workspaces"` property of your root project `package.json`.
### Adding dependencies to a workspace
It's possible to directly add/remove/update dependencies of your workspaces
using the [`workspace` config](/using-npm/config#workspace).
For example, assuming the following structure:
```
.
+-- package.json
`-- packages
+-- a
| `-- package.json
`-- b
`-- package.json
```
If you want to add a dependency named `abbrev` from the registry as a
dependency of your workspace **a**, you may use the workspace config to tell
the npm installer that package should be added as a dependency of the provided
workspace:
```
npm install abbrev -w a
```
Note: other installing commands such as `uninstall`, `ci`, etc will also
respect the provided `workspace` configuration.
### Using workspaces
Given the [specifics of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace
by its declared `package.json` `name`. Continuing from the example defined
above, let's also create a Node.js script that will require the workspace `a`
example module, e.g:
```
// ./packages/a/index.js
module.exports = 'a'
// ./lib/index.js
const moduleA = require('a')
console.log(moduleA) // -> a
```
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.
### 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.
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:
```
.
+-- package.json
`-- packages
+-- a
| `-- package.json
`-- b
`-- package.json
```
By running a command using the `workspace` option, it's possible to run the
given command in the context of that specific workspace. e.g:
```
npm run test --workspace=a
```
You could also run the command within the workspace.
```
cd packages/a && npm run test
```
Either will run the `test` script defined within the
`./packages/a/package.json` file.
Please note that you can also specify this argument multiple times in the
command-line in order to target multiple workspaces, e.g:
```
npm run test --workspace=a --workspace=b
```
Or run the command for each workspace within the 'packages' folder:
```
npm run test --workspace=packages
```
It's also possible to use the `workspaces` (plural) configuration option to
enable the same behavior but running that command in the context of **all**
configured workspaces. e.g:
```
npm run test --workspaces
```
Will run the `test` script in both `./packages/a` and `./packages/b`.
Commands will be run in each workspace in the order they appear in your `package.json`
```
{
"workspaces": [ "packages/a", "packages/b" ]
}
```
Order of run is different with:
```
{
"workspaces": [ "packages/b", "packages/a" ]
}
```
### Ignoring missing scripts
It is not required for all of the workspaces to implement scripts run with the `npm run` command.
By running the command with the `--if-present` flag, npm will ignore workspaces missing target script.
```
npm run test --workspaces --if-present
```
### See also
* [npm install](/commands/npm-install)
* [npm publish](/commands/npm-publish)
* [npm run-script](/commands/npm-run-script)
* [config](/using-npm/config)