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