11cb0ef41Sopenharmony_ci---
21cb0ef41Sopenharmony_cititle: npm-audit
31cb0ef41Sopenharmony_cisection: 1
41cb0ef41Sopenharmony_cidescription: Run a security audit
51cb0ef41Sopenharmony_ci---
61cb0ef41Sopenharmony_ci
71cb0ef41Sopenharmony_ci### Synopsis
81cb0ef41Sopenharmony_ci
91cb0ef41Sopenharmony_ci```bash
101cb0ef41Sopenharmony_cinpm audit [fix|signatures]
111cb0ef41Sopenharmony_ci```
121cb0ef41Sopenharmony_ci
131cb0ef41Sopenharmony_ci### Description
141cb0ef41Sopenharmony_ci
151cb0ef41Sopenharmony_ciThe audit command submits a description of the dependencies configured in
161cb0ef41Sopenharmony_ciyour project to your default registry and asks for a report of known
171cb0ef41Sopenharmony_civulnerabilities.  If any vulnerabilities are found, then the impact and
181cb0ef41Sopenharmony_ciappropriate remediation will be calculated.  If the `fix` argument is
191cb0ef41Sopenharmony_ciprovided, then remediations will be applied to the package tree.
201cb0ef41Sopenharmony_ci
211cb0ef41Sopenharmony_ciThe command will exit with a 0 exit code if no vulnerabilities were found.
221cb0ef41Sopenharmony_ci
231cb0ef41Sopenharmony_ciNote that some vulnerabilities cannot be fixed automatically and will
241cb0ef41Sopenharmony_cirequire manual intervention or review.  Also note that since `npm audit
251cb0ef41Sopenharmony_cifix` runs a full-fledged `npm install` under the hood, all configs that
261cb0ef41Sopenharmony_ciapply to the installer will also apply to `npm install` -- so things like
271cb0ef41Sopenharmony_ci`npm audit fix --package-lock-only` will work as expected.
281cb0ef41Sopenharmony_ci
291cb0ef41Sopenharmony_ciBy default, the audit command will exit with a non-zero code if any
301cb0ef41Sopenharmony_civulnerability is found. It may be useful in CI environments to include the
311cb0ef41Sopenharmony_ci`--audit-level` parameter to specify the minimum vulnerability level that
321cb0ef41Sopenharmony_ciwill cause the command to fail. This option does not filter the report
331cb0ef41Sopenharmony_cioutput, it simply changes the command's failure threshold.
341cb0ef41Sopenharmony_ci
351cb0ef41Sopenharmony_ci### Package lock
361cb0ef41Sopenharmony_ci
371cb0ef41Sopenharmony_ciBy default npm requires a package-lock or shrinkwrap in order to run the
381cb0ef41Sopenharmony_ciaudit.  You can bypass the package lock with `--no-package-lock` but be
391cb0ef41Sopenharmony_ciaware the results may be different with every run, since npm will
401cb0ef41Sopenharmony_cire-build the dependency tree each time.
411cb0ef41Sopenharmony_ci
421cb0ef41Sopenharmony_ci### Audit Signatures
431cb0ef41Sopenharmony_ci
441cb0ef41Sopenharmony_ciTo ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.
451cb0ef41Sopenharmony_ci
461cb0ef41Sopenharmony_ciRegistry signatures can be verified using the following `audit` command:
471cb0ef41Sopenharmony_ci
481cb0ef41Sopenharmony_ci```bash
491cb0ef41Sopenharmony_ci$ npm audit signatures
501cb0ef41Sopenharmony_ci```
511cb0ef41Sopenharmony_ci
521cb0ef41Sopenharmony_ciThe npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
531cb0ef41Sopenharmony_ci
541cb0ef41Sopenharmony_ci1. Signatures are provided in the package's `packument` in each published version within the `dist` object:
551cb0ef41Sopenharmony_ci
561cb0ef41Sopenharmony_ci```json
571cb0ef41Sopenharmony_ci"dist":{
581cb0ef41Sopenharmony_ci  "..omitted..": "..omitted..",
591cb0ef41Sopenharmony_ci  "signatures": [{
601cb0ef41Sopenharmony_ci    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
611cb0ef41Sopenharmony_ci    "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
621cb0ef41Sopenharmony_ci  }]
631cb0ef41Sopenharmony_ci}
641cb0ef41Sopenharmony_ci```
651cb0ef41Sopenharmony_ci
661cb0ef41Sopenharmony_ciSee this [example](https://registry.npmjs.org/light-cycle/1.4.3) of a signed package from the public npm registry.
671cb0ef41Sopenharmony_ci
681cb0ef41Sopenharmony_ciThe `sig` is generated using the following template: `${package.name}@${package.version}:${package.dist.integrity}` and the `keyid` has to match one of the public signing keys below.
691cb0ef41Sopenharmony_ci
701cb0ef41Sopenharmony_ci2. Public signing keys are provided at `registry-host.tld/-/npm/v1/keys` in the following format:
711cb0ef41Sopenharmony_ci
721cb0ef41Sopenharmony_ci```
731cb0ef41Sopenharmony_ci{
741cb0ef41Sopenharmony_ci  "keys": [{
751cb0ef41Sopenharmony_ci    "expires": null,
761cb0ef41Sopenharmony_ci    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
771cb0ef41Sopenharmony_ci    "keytype": "ecdsa-sha2-nistp256",
781cb0ef41Sopenharmony_ci    "scheme": "ecdsa-sha2-nistp256",
791cb0ef41Sopenharmony_ci    "key": "{{B64_PUBLIC_KEY}}"
801cb0ef41Sopenharmony_ci  }]
811cb0ef41Sopenharmony_ci}
821cb0ef41Sopenharmony_ci```
831cb0ef41Sopenharmony_ci
841cb0ef41Sopenharmony_ciKeys response:
851cb0ef41Sopenharmony_ci
861cb0ef41Sopenharmony_ci- `expires`: null or a simplified extended [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601"): `YYYY-MM-DDTHH:mm:ss.sssZ`
871cb0ef41Sopenharmony_ci- `keydid`: sha256 fingerprint of the public key
881cb0ef41Sopenharmony_ci- `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
891cb0ef41Sopenharmony_ci- `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
901cb0ef41Sopenharmony_ci- `key`: base64 encoded public key
911cb0ef41Sopenharmony_ci
921cb0ef41Sopenharmony_ciSee this [example key's response from the public npm registry](https://registry.npmjs.org/-/npm/v1/keys").
931cb0ef41Sopenharmony_ci
941cb0ef41Sopenharmony_ci### Audit Endpoints
951cb0ef41Sopenharmony_ci
961cb0ef41Sopenharmony_ciThere are two audit endpoints that npm may use to fetch vulnerability
971cb0ef41Sopenharmony_ciinformation: the `Bulk Advisory` endpoint and the `Quick Audit` endpoint.
981cb0ef41Sopenharmony_ci
991cb0ef41Sopenharmony_ci#### Bulk Advisory Endpoint
1001cb0ef41Sopenharmony_ci
1011cb0ef41Sopenharmony_ciAs of version 7, npm uses the much faster `Bulk Advisory` endpoint to
1021cb0ef41Sopenharmony_cioptimize the speed of calculating audit results.
1031cb0ef41Sopenharmony_ci
1041cb0ef41Sopenharmony_cinpm will generate a JSON payload with the name and list of versions of each
1051cb0ef41Sopenharmony_cipackage in the tree, and POST it to the default configured registry at
1061cb0ef41Sopenharmony_cithe path `/-/npm/v1/security/advisories/bulk`.
1071cb0ef41Sopenharmony_ci
1081cb0ef41Sopenharmony_ciAny packages in the tree that do not have a `version` field in their
1091cb0ef41Sopenharmony_cipackage.json file will be ignored.  If any `--omit` options are specified
1101cb0ef41Sopenharmony_ci(either via the [`--omit` config](/using-npm/config#omit), or one of the
1111cb0ef41Sopenharmony_cishorthands such as `--production`, `--only=dev`, and so on), then packages will
1121cb0ef41Sopenharmony_cibe omitted from the submitted payload as appropriate.
1131cb0ef41Sopenharmony_ci
1141cb0ef41Sopenharmony_ciIf the registry responds with an error, or with an invalid response, then
1151cb0ef41Sopenharmony_cinpm will attempt to load advisory data from the `Quick Audit` endpoint.
1161cb0ef41Sopenharmony_ci
1171cb0ef41Sopenharmony_ciThe expected result will contain a set of advisory objects for each
1181cb0ef41Sopenharmony_cidependency that matches the advisory range.  Each advisory object contains
1191cb0ef41Sopenharmony_cia `name`, `url`, `id`, `severity`, `vulnerable_versions`, and `title`.
1201cb0ef41Sopenharmony_ci
1211cb0ef41Sopenharmony_cinpm then uses these advisory objects to calculate vulnerabilities and
1221cb0ef41Sopenharmony_cimeta-vulnerabilities of the dependencies within the tree.
1231cb0ef41Sopenharmony_ci
1241cb0ef41Sopenharmony_ci#### Quick Audit Endpoint
1251cb0ef41Sopenharmony_ci
1261cb0ef41Sopenharmony_ciIf the `Bulk Advisory` endpoint returns an error, or invalid data, npm will
1271cb0ef41Sopenharmony_ciattempt to load advisory data from the `Quick Audit` endpoint, which is
1281cb0ef41Sopenharmony_ciconsiderably slower in most cases.
1291cb0ef41Sopenharmony_ci
1301cb0ef41Sopenharmony_ciThe full package tree as found in `package-lock.json` is submitted, along
1311cb0ef41Sopenharmony_ciwith the following pieces of additional metadata:
1321cb0ef41Sopenharmony_ci
1331cb0ef41Sopenharmony_ci* `npm_version`
1341cb0ef41Sopenharmony_ci* `node_version`
1351cb0ef41Sopenharmony_ci* `platform`
1361cb0ef41Sopenharmony_ci* `arch`
1371cb0ef41Sopenharmony_ci* `node_env`
1381cb0ef41Sopenharmony_ci
1391cb0ef41Sopenharmony_ciAll packages in the tree are submitted to the Quick Audit endpoint.
1401cb0ef41Sopenharmony_ciOmitted dependency types are skipped when generating the report.
1411cb0ef41Sopenharmony_ci
1421cb0ef41Sopenharmony_ci#### Scrubbing
1431cb0ef41Sopenharmony_ci
1441cb0ef41Sopenharmony_ciOut of an abundance of caution, npm versions 5 and 6 would "scrub" any
1451cb0ef41Sopenharmony_cipackages from the submitted report if their name contained a `/` character,
1461cb0ef41Sopenharmony_ciso as to avoid leaking the names of potentially private packages or git
1471cb0ef41Sopenharmony_ciURLs.
1481cb0ef41Sopenharmony_ci
1491cb0ef41Sopenharmony_ciHowever, in practice, this resulted in audits often failing to properly
1501cb0ef41Sopenharmony_cidetect meta-vulnerabilities, because the tree would appear to be invalid
1511cb0ef41Sopenharmony_cidue to missing dependencies, and prevented the detection of vulnerabilities
1521cb0ef41Sopenharmony_ciin package trees that used git dependencies or private modules.
1531cb0ef41Sopenharmony_ci
1541cb0ef41Sopenharmony_ciThis scrubbing has been removed from npm as of version 7.
1551cb0ef41Sopenharmony_ci
1561cb0ef41Sopenharmony_ci#### Calculating Meta-Vulnerabilities and Remediations
1571cb0ef41Sopenharmony_ci
1581cb0ef41Sopenharmony_cinpm uses the
1591cb0ef41Sopenharmony_ci[`@npmcli/metavuln-calculator`](http://npm.im/@npmcli/metavuln-calculator)
1601cb0ef41Sopenharmony_cimodule to turn a set of security advisories into a set of "vulnerability"
1611cb0ef41Sopenharmony_ciobjects.  A "meta-vulnerability" is a dependency that is vulnerable by
1621cb0ef41Sopenharmony_civirtue of dependence on vulnerable versions of a vulnerable package.
1631cb0ef41Sopenharmony_ci
1641cb0ef41Sopenharmony_ciFor example, if the package `foo` is vulnerable in the range `>=1.0.2
1651cb0ef41Sopenharmony_ci<2.0.0`, and the package `bar` depends on `foo@^1.1.0`, then that version
1661cb0ef41Sopenharmony_ciof `bar` can only be installed by installing a vulnerable version of `foo`.
1671cb0ef41Sopenharmony_ciIn this case, `bar` is a "metavulnerability".
1681cb0ef41Sopenharmony_ci
1691cb0ef41Sopenharmony_ciOnce metavulnerabilities for a given package are calculated, they are
1701cb0ef41Sopenharmony_cicached in the `~/.npm` folder and only re-evaluated if the advisory range
1711cb0ef41Sopenharmony_cichanges, or a new version of the package is published (in which case, the
1721cb0ef41Sopenharmony_cinew version is checked for metavulnerable status as well).
1731cb0ef41Sopenharmony_ci
1741cb0ef41Sopenharmony_ciIf the chain of metavulnerabilities extends all the way to the root
1751cb0ef41Sopenharmony_ciproject, and it cannot be updated without changing its dependency ranges,
1761cb0ef41Sopenharmony_cithen `npm audit fix` will require the `--force` option to apply the
1771cb0ef41Sopenharmony_ciremediation.  If remediations do not require changes to the dependency
1781cb0ef41Sopenharmony_ciranges, then all vulnerable packages will be updated to a version that does
1791cb0ef41Sopenharmony_cinot have an advisory or metavulnerability posted against it.
1801cb0ef41Sopenharmony_ci
1811cb0ef41Sopenharmony_ci### Exit Code
1821cb0ef41Sopenharmony_ci
1831cb0ef41Sopenharmony_ciThe `npm audit` command will exit with a 0 exit code if no vulnerabilities
1841cb0ef41Sopenharmony_ciwere found.  The `npm audit fix` command will exit with 0 exit code if no
1851cb0ef41Sopenharmony_civulnerabilities are found _or_ if the remediation is able to successfully
1861cb0ef41Sopenharmony_cifix all vulnerabilities.
1871cb0ef41Sopenharmony_ci
1881cb0ef41Sopenharmony_ciIf vulnerabilities were found the exit code will depend on the
1891cb0ef41Sopenharmony_ci[`audit-level` config](/using-npm/config#audit-level).
1901cb0ef41Sopenharmony_ci
1911cb0ef41Sopenharmony_ci### Examples
1921cb0ef41Sopenharmony_ci
1931cb0ef41Sopenharmony_ciScan your project for vulnerabilities and automatically install any compatible
1941cb0ef41Sopenharmony_ciupdates to vulnerable dependencies:
1951cb0ef41Sopenharmony_ci
1961cb0ef41Sopenharmony_ci```bash
1971cb0ef41Sopenharmony_ci$ npm audit fix
1981cb0ef41Sopenharmony_ci```
1991cb0ef41Sopenharmony_ci
2001cb0ef41Sopenharmony_ciRun `audit fix` without modifying `node_modules`, but still updating the
2011cb0ef41Sopenharmony_cipkglock:
2021cb0ef41Sopenharmony_ci
2031cb0ef41Sopenharmony_ci```bash
2041cb0ef41Sopenharmony_ci$ npm audit fix --package-lock-only
2051cb0ef41Sopenharmony_ci```
2061cb0ef41Sopenharmony_ci
2071cb0ef41Sopenharmony_ciSkip updating `devDependencies`:
2081cb0ef41Sopenharmony_ci
2091cb0ef41Sopenharmony_ci```bash
2101cb0ef41Sopenharmony_ci$ npm audit fix --only=prod
2111cb0ef41Sopenharmony_ci```
2121cb0ef41Sopenharmony_ci
2131cb0ef41Sopenharmony_ciHave `audit fix` install SemVer-major updates to toplevel dependencies, not
2141cb0ef41Sopenharmony_cijust SemVer-compatible ones:
2151cb0ef41Sopenharmony_ci
2161cb0ef41Sopenharmony_ci```bash
2171cb0ef41Sopenharmony_ci$ npm audit fix --force
2181cb0ef41Sopenharmony_ci```
2191cb0ef41Sopenharmony_ci
2201cb0ef41Sopenharmony_ciDo a dry run to get an idea of what `audit fix` will do, and _also_ output
2211cb0ef41Sopenharmony_ciinstall information in JSON format:
2221cb0ef41Sopenharmony_ci
2231cb0ef41Sopenharmony_ci```bash
2241cb0ef41Sopenharmony_ci$ npm audit fix --dry-run --json
2251cb0ef41Sopenharmony_ci```
2261cb0ef41Sopenharmony_ci
2271cb0ef41Sopenharmony_ciScan your project for vulnerabilities and just show the details, without
2281cb0ef41Sopenharmony_cifixing anything:
2291cb0ef41Sopenharmony_ci
2301cb0ef41Sopenharmony_ci```bash
2311cb0ef41Sopenharmony_ci$ npm audit
2321cb0ef41Sopenharmony_ci```
2331cb0ef41Sopenharmony_ci
2341cb0ef41Sopenharmony_ciGet the detailed audit report in JSON format:
2351cb0ef41Sopenharmony_ci
2361cb0ef41Sopenharmony_ci```bash
2371cb0ef41Sopenharmony_ci$ npm audit --json
2381cb0ef41Sopenharmony_ci```
2391cb0ef41Sopenharmony_ci
2401cb0ef41Sopenharmony_ciFail an audit only if the results include a vulnerability with a level of moderate or higher:
2411cb0ef41Sopenharmony_ci
2421cb0ef41Sopenharmony_ci```bash
2431cb0ef41Sopenharmony_ci$ npm audit --audit-level=moderate
2441cb0ef41Sopenharmony_ci```
2451cb0ef41Sopenharmony_ci
2461cb0ef41Sopenharmony_ci### Configuration
2471cb0ef41Sopenharmony_ci
2481cb0ef41Sopenharmony_ci#### `audit-level`
2491cb0ef41Sopenharmony_ci
2501cb0ef41Sopenharmony_ci* Default: null
2511cb0ef41Sopenharmony_ci* Type: null, "info", "low", "moderate", "high", "critical", or "none"
2521cb0ef41Sopenharmony_ci
2531cb0ef41Sopenharmony_ciThe minimum level of vulnerability for `npm audit` to exit with a non-zero
2541cb0ef41Sopenharmony_ciexit code.
2551cb0ef41Sopenharmony_ci
2561cb0ef41Sopenharmony_ci
2571cb0ef41Sopenharmony_ci
2581cb0ef41Sopenharmony_ci#### `dry-run`
2591cb0ef41Sopenharmony_ci
2601cb0ef41Sopenharmony_ci* Default: false
2611cb0ef41Sopenharmony_ci* Type: Boolean
2621cb0ef41Sopenharmony_ci
2631cb0ef41Sopenharmony_ciIndicates that you don't want npm to make any changes and that it should
2641cb0ef41Sopenharmony_cionly report what it would have done. This can be passed into any of the
2651cb0ef41Sopenharmony_cicommands that modify your local installation, eg, `install`, `update`,
2661cb0ef41Sopenharmony_ci`dedupe`, `uninstall`, as well as `pack` and `publish`.
2671cb0ef41Sopenharmony_ci
2681cb0ef41Sopenharmony_ciNote: This is NOT honored by other network related commands, eg `dist-tags`,
2691cb0ef41Sopenharmony_ci`owner`, etc.
2701cb0ef41Sopenharmony_ci
2711cb0ef41Sopenharmony_ci
2721cb0ef41Sopenharmony_ci
2731cb0ef41Sopenharmony_ci#### `force`
2741cb0ef41Sopenharmony_ci
2751cb0ef41Sopenharmony_ci* Default: false
2761cb0ef41Sopenharmony_ci* Type: Boolean
2771cb0ef41Sopenharmony_ci
2781cb0ef41Sopenharmony_ciRemoves various protections against unfortunate side effects, common
2791cb0ef41Sopenharmony_cimistakes, unnecessary performance degradation, and malicious input.
2801cb0ef41Sopenharmony_ci
2811cb0ef41Sopenharmony_ci* Allow clobbering non-npm files in global installs.
2821cb0ef41Sopenharmony_ci* Allow the `npm version` command to work on an unclean git repository.
2831cb0ef41Sopenharmony_ci* Allow deleting the cache folder with `npm cache clean`.
2841cb0ef41Sopenharmony_ci* Allow installing packages that have an `engines` declaration requiring a
2851cb0ef41Sopenharmony_ci  different version of npm.
2861cb0ef41Sopenharmony_ci* Allow installing packages that have an `engines` declaration requiring a
2871cb0ef41Sopenharmony_ci  different version of `node`, even if `--engine-strict` is enabled.
2881cb0ef41Sopenharmony_ci* Allow `npm audit fix` to install modules outside your stated dependency
2891cb0ef41Sopenharmony_ci  range (including SemVer-major changes).
2901cb0ef41Sopenharmony_ci* Allow unpublishing all versions of a published package.
2911cb0ef41Sopenharmony_ci* Allow conflicting peerDependencies to be installed in the root project.
2921cb0ef41Sopenharmony_ci* Implicitly set `--yes` during `npm init`.
2931cb0ef41Sopenharmony_ci* Allow clobbering existing values in `npm pkg`
2941cb0ef41Sopenharmony_ci* Allow unpublishing of entire packages (not just a single version).
2951cb0ef41Sopenharmony_ci
2961cb0ef41Sopenharmony_ciIf you don't have a clear idea of what you want to do, it is strongly
2971cb0ef41Sopenharmony_cirecommended that you do not use this option!
2981cb0ef41Sopenharmony_ci
2991cb0ef41Sopenharmony_ci
3001cb0ef41Sopenharmony_ci
3011cb0ef41Sopenharmony_ci#### `json`
3021cb0ef41Sopenharmony_ci
3031cb0ef41Sopenharmony_ci* Default: false
3041cb0ef41Sopenharmony_ci* Type: Boolean
3051cb0ef41Sopenharmony_ci
3061cb0ef41Sopenharmony_ciWhether or not to output JSON data, rather than the normal output.
3071cb0ef41Sopenharmony_ci
3081cb0ef41Sopenharmony_ci* In `npm pkg set` it enables parsing set values with JSON.parse() before
3091cb0ef41Sopenharmony_ci  saving them to your `package.json`.
3101cb0ef41Sopenharmony_ci
3111cb0ef41Sopenharmony_ciNot supported by all npm commands.
3121cb0ef41Sopenharmony_ci
3131cb0ef41Sopenharmony_ci
3141cb0ef41Sopenharmony_ci
3151cb0ef41Sopenharmony_ci#### `package-lock-only`
3161cb0ef41Sopenharmony_ci
3171cb0ef41Sopenharmony_ci* Default: false
3181cb0ef41Sopenharmony_ci* Type: Boolean
3191cb0ef41Sopenharmony_ci
3201cb0ef41Sopenharmony_ciIf set to true, the current operation will only use the `package-lock.json`,
3211cb0ef41Sopenharmony_ciignoring `node_modules`.
3221cb0ef41Sopenharmony_ci
3231cb0ef41Sopenharmony_ciFor `update` this means only the `package-lock.json` will be updated,
3241cb0ef41Sopenharmony_ciinstead of checking `node_modules` and downloading dependencies.
3251cb0ef41Sopenharmony_ci
3261cb0ef41Sopenharmony_ciFor `list` this means the output will be based on the tree described by the
3271cb0ef41Sopenharmony_ci`package-lock.json`, rather than the contents of `node_modules`.
3281cb0ef41Sopenharmony_ci
3291cb0ef41Sopenharmony_ci
3301cb0ef41Sopenharmony_ci
3311cb0ef41Sopenharmony_ci#### `package-lock`
3321cb0ef41Sopenharmony_ci
3331cb0ef41Sopenharmony_ci* Default: true
3341cb0ef41Sopenharmony_ci* Type: Boolean
3351cb0ef41Sopenharmony_ci
3361cb0ef41Sopenharmony_ciIf set to false, then ignore `package-lock.json` files when installing. This
3371cb0ef41Sopenharmony_ciwill also prevent _writing_ `package-lock.json` if `save` is true.
3381cb0ef41Sopenharmony_ci
3391cb0ef41Sopenharmony_ci
3401cb0ef41Sopenharmony_ci
3411cb0ef41Sopenharmony_ci#### `omit`
3421cb0ef41Sopenharmony_ci
3431cb0ef41Sopenharmony_ci* Default: 'dev' if the `NODE_ENV` environment variable is set to
3441cb0ef41Sopenharmony_ci  'production', otherwise empty.
3451cb0ef41Sopenharmony_ci* Type: "dev", "optional", or "peer" (can be set multiple times)
3461cb0ef41Sopenharmony_ci
3471cb0ef41Sopenharmony_ciDependency types to omit from the installation tree on disk.
3481cb0ef41Sopenharmony_ci
3491cb0ef41Sopenharmony_ciNote that these dependencies _are_ still resolved and added to the
3501cb0ef41Sopenharmony_ci`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
3511cb0ef41Sopenharmony_ciphysically installed on disk.
3521cb0ef41Sopenharmony_ci
3531cb0ef41Sopenharmony_ciIf a package type appears in both the `--include` and `--omit` lists, then
3541cb0ef41Sopenharmony_ciit will be included.
3551cb0ef41Sopenharmony_ci
3561cb0ef41Sopenharmony_ciIf the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
3571cb0ef41Sopenharmony_civariable will be set to `'production'` for all lifecycle scripts.
3581cb0ef41Sopenharmony_ci
3591cb0ef41Sopenharmony_ci
3601cb0ef41Sopenharmony_ci
3611cb0ef41Sopenharmony_ci#### `include`
3621cb0ef41Sopenharmony_ci
3631cb0ef41Sopenharmony_ci* Default:
3641cb0ef41Sopenharmony_ci* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
3651cb0ef41Sopenharmony_ci
3661cb0ef41Sopenharmony_ciOption that allows for defining which types of dependencies to install.
3671cb0ef41Sopenharmony_ci
3681cb0ef41Sopenharmony_ciThis is the inverse of `--omit=<type>`.
3691cb0ef41Sopenharmony_ci
3701cb0ef41Sopenharmony_ciDependency types specified in `--include` will not be omitted, regardless of
3711cb0ef41Sopenharmony_cithe order in which omit/include are specified on the command-line.
3721cb0ef41Sopenharmony_ci
3731cb0ef41Sopenharmony_ci
3741cb0ef41Sopenharmony_ci
3751cb0ef41Sopenharmony_ci#### `foreground-scripts`
3761cb0ef41Sopenharmony_ci
3771cb0ef41Sopenharmony_ci* Default: `false` unless when using `npm pack` or `npm publish` where it
3781cb0ef41Sopenharmony_ci  defaults to `true`
3791cb0ef41Sopenharmony_ci* Type: Boolean
3801cb0ef41Sopenharmony_ci
3811cb0ef41Sopenharmony_ciRun all build scripts (ie, `preinstall`, `install`, and `postinstall`)
3821cb0ef41Sopenharmony_ciscripts for installed packages in the foreground process, sharing standard
3831cb0ef41Sopenharmony_ciinput, output, and error with the main npm process.
3841cb0ef41Sopenharmony_ci
3851cb0ef41Sopenharmony_ciNote that this will generally make installs run slower, and be much noisier,
3861cb0ef41Sopenharmony_cibut can be useful for debugging.
3871cb0ef41Sopenharmony_ci
3881cb0ef41Sopenharmony_ci
3891cb0ef41Sopenharmony_ci
3901cb0ef41Sopenharmony_ci#### `ignore-scripts`
3911cb0ef41Sopenharmony_ci
3921cb0ef41Sopenharmony_ci* Default: false
3931cb0ef41Sopenharmony_ci* Type: Boolean
3941cb0ef41Sopenharmony_ci
3951cb0ef41Sopenharmony_ciIf true, npm does not run scripts specified in package.json files.
3961cb0ef41Sopenharmony_ci
3971cb0ef41Sopenharmony_ciNote that commands explicitly intended to run a particular script, such as
3981cb0ef41Sopenharmony_ci`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`
3991cb0ef41Sopenharmony_ciwill still run their intended script if `ignore-scripts` is set, but they
4001cb0ef41Sopenharmony_ciwill *not* run any pre- or post-scripts.
4011cb0ef41Sopenharmony_ci
4021cb0ef41Sopenharmony_ci
4031cb0ef41Sopenharmony_ci
4041cb0ef41Sopenharmony_ci#### `workspace`
4051cb0ef41Sopenharmony_ci
4061cb0ef41Sopenharmony_ci* Default:
4071cb0ef41Sopenharmony_ci* Type: String (can be set multiple times)
4081cb0ef41Sopenharmony_ci
4091cb0ef41Sopenharmony_ciEnable running a command in the context of the configured workspaces of the
4101cb0ef41Sopenharmony_cicurrent project while filtering by running only the workspaces defined by
4111cb0ef41Sopenharmony_cithis configuration option.
4121cb0ef41Sopenharmony_ci
4131cb0ef41Sopenharmony_ciValid values for the `workspace` config are either:
4141cb0ef41Sopenharmony_ci
4151cb0ef41Sopenharmony_ci* Workspace names
4161cb0ef41Sopenharmony_ci* Path to a workspace directory
4171cb0ef41Sopenharmony_ci* Path to a parent workspace directory (will result in selecting all
4181cb0ef41Sopenharmony_ci  workspaces within that folder)
4191cb0ef41Sopenharmony_ci
4201cb0ef41Sopenharmony_ciWhen set for the `npm init` command, this may be set to the folder of a
4211cb0ef41Sopenharmony_ciworkspace which does not yet exist, to create the folder and set it up as a
4221cb0ef41Sopenharmony_cibrand new workspace within the project.
4231cb0ef41Sopenharmony_ci
4241cb0ef41Sopenharmony_ciThis value is not exported to the environment for child processes.
4251cb0ef41Sopenharmony_ci
4261cb0ef41Sopenharmony_ci#### `workspaces`
4271cb0ef41Sopenharmony_ci
4281cb0ef41Sopenharmony_ci* Default: null
4291cb0ef41Sopenharmony_ci* Type: null or Boolean
4301cb0ef41Sopenharmony_ci
4311cb0ef41Sopenharmony_ciSet to true to run the command in the context of **all** configured
4321cb0ef41Sopenharmony_ciworkspaces.
4331cb0ef41Sopenharmony_ci
4341cb0ef41Sopenharmony_ciExplicitly setting this to false will cause commands like `install` to
4351cb0ef41Sopenharmony_ciignore workspaces altogether. When not set explicitly:
4361cb0ef41Sopenharmony_ci
4371cb0ef41Sopenharmony_ci- Commands that operate on the `node_modules` tree (install, update, etc.)
4381cb0ef41Sopenharmony_ciwill link workspaces into the `node_modules` folder. - Commands that do
4391cb0ef41Sopenharmony_ciother things (test, exec, publish, etc.) will operate on the root project,
4401cb0ef41Sopenharmony_ci_unless_ one or more workspaces are specified in the `workspace` config.
4411cb0ef41Sopenharmony_ci
4421cb0ef41Sopenharmony_ciThis value is not exported to the environment for child processes.
4431cb0ef41Sopenharmony_ci
4441cb0ef41Sopenharmony_ci#### `include-workspace-root`
4451cb0ef41Sopenharmony_ci
4461cb0ef41Sopenharmony_ci* Default: false
4471cb0ef41Sopenharmony_ci* Type: Boolean
4481cb0ef41Sopenharmony_ci
4491cb0ef41Sopenharmony_ciInclude the workspace root when workspaces are enabled for a command.
4501cb0ef41Sopenharmony_ci
4511cb0ef41Sopenharmony_ciWhen false, specifying individual workspaces via the `workspace` config, or
4521cb0ef41Sopenharmony_ciall workspaces via the `workspaces` flag, will cause npm to operate only on
4531cb0ef41Sopenharmony_cithe specified workspaces, and not on the root project.
4541cb0ef41Sopenharmony_ci
4551cb0ef41Sopenharmony_ciThis value is not exported to the environment for child processes.
4561cb0ef41Sopenharmony_ci
4571cb0ef41Sopenharmony_ci#### `install-links`
4581cb0ef41Sopenharmony_ci
4591cb0ef41Sopenharmony_ci* Default: false
4601cb0ef41Sopenharmony_ci* Type: Boolean
4611cb0ef41Sopenharmony_ci
4621cb0ef41Sopenharmony_ciWhen set file: protocol dependencies will be packed and installed as regular
4631cb0ef41Sopenharmony_cidependencies instead of creating a symlink. This option has no effect on
4641cb0ef41Sopenharmony_ciworkspaces.
4651cb0ef41Sopenharmony_ci
4661cb0ef41Sopenharmony_ci
4671cb0ef41Sopenharmony_ci
4681cb0ef41Sopenharmony_ci### See Also
4691cb0ef41Sopenharmony_ci
4701cb0ef41Sopenharmony_ci* [npm install](/commands/npm-install)
4711cb0ef41Sopenharmony_ci* [config](/using-npm/config)
472