diff --git a/Makefile b/Makefile index 6fb39c704ff1d..b28e9eebda681 100644 --- a/Makefile +++ b/Makefile @@ -78,7 +78,7 @@ man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js node scripts/config-doc.js -docs/content/commands/npm-%.md: lib/%.js scripts/config-doc-command.js lib/utils/config/*.js +docs/content/commands/npm-%.md: lib/commands/%.js scripts/config-doc-command.js lib/utils/config/*.js node scripts/config-doc-command.js $@ $< freshdocs: diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md index 323d38f64c14f..ae2afa84032fe 100644 --- a/docs/content/commands/npm-audit.md +++ b/docs/content/commands/npm-audit.md @@ -306,6 +306,36 @@ variable will be set to `'production'` for all lifecycle scripts. +#### `foreground-scripts` + +* Default: false +* Type: Boolean + +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. + +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. + + + + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + + + + #### `workspace` * Default: diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md index 4490fea9a0bb7..97d1aa5523dd7 100644 --- a/docs/content/commands/npm-ci.md +++ b/docs/content/commands/npm-ci.md @@ -94,6 +94,21 @@ submitted. +#### `foreground-scripts` + +* Default: false +* Type: Boolean + +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. + +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. + + + + #### `ignore-scripts` * Default: false diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md index 5ad67604541d1..0d9470acf58b3 100644 --- a/docs/content/commands/npm-install-ci-test.md +++ b/docs/content/commands/npm-install-ci-test.md @@ -43,6 +43,21 @@ submitted. +#### `foreground-scripts` + +* Default: false +* Type: Boolean + +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. + +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. + + + + #### `ignore-scripts` * Default: false diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md index ed39c6705a484..5ac31cbf08e25 100644 --- a/docs/content/commands/npm-install-test.md +++ b/docs/content/commands/npm-install-test.md @@ -112,6 +112,27 @@ will be preferred. +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + + #### `strict-peer-deps` * Default: false @@ -151,23 +172,17 @@ This configuration does not affect `npm ci`. -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. +#### `foreground-scripts` -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. +* Default: false +* Type: Boolean -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md index 66193e733133b..b4fc2f2c89b4b 100644 --- a/docs/content/commands/npm-install.md +++ b/docs/content/commands/npm-install.md @@ -502,6 +502,27 @@ will be preferred. +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + + #### `strict-peer-deps` * Default: false @@ -541,23 +562,17 @@ This configuration does not affect `npm ci`. -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. +#### `foreground-scripts` -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. +* Default: false +* Type: Boolean -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. diff --git a/docs/content/commands/npm-pkg.md b/docs/content/commands/npm-pkg.md index 8f6cbecf958fd..c41f2a76d059d 100644 --- a/docs/content/commands/npm-pkg.md +++ b/docs/content/commands/npm-pkg.md @@ -14,6 +14,8 @@ description: Manages your package.json npm pkg set = [= ...] npm pkg get [ [ ...]] npm pkg delete [ ...] +npm pkg set [[].= ...] +npm pkg set [[].= ...] ``` diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md index 49420e5b9d99c..a10a353801b7c 100644 --- a/docs/content/commands/npm-prune.md +++ b/docs/content/commands/npm-prune.md @@ -99,6 +99,36 @@ Not supported by all npm commands. +#### `foreground-scripts` + +* Default: false +* Type: Boolean + +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. + +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. + + + + +#### `ignore-scripts` + +* Default: false +* Type: Boolean + +If true, npm does not run scripts specified in package.json files. + +Note that commands explicitly intended to run a particular script, such as +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` +will still run their intended script if `ignore-scripts` is set, but they +will *not* run any pre- or post-scripts. + + + + #### `workspace` * Default: diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md index ecb4a7ce34c62..d63e00b79d386 100644 --- a/docs/content/commands/npm-rebuild.md +++ b/docs/content/commands/npm-rebuild.md @@ -70,6 +70,21 @@ systems. +#### `foreground-scripts` + +* Default: false +* Type: Boolean + +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. + +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. + + + + #### `ignore-scripts` * Default: false diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md index e1b48a8ed4320..aff46b1e5b557 100644 --- a/docs/content/commands/npm-update.md +++ b/docs/content/commands/npm-update.md @@ -169,6 +169,22 @@ be _downgraded_. +#### `save` + +* Default: `true` unless when using `npm update` or `npm dedupe` where it + defaults to `false` +* Type: Boolean + +Save installed packages to a `package.json` file as dependencies. + +When used with the `npm rm` command, removes the dependency from +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. + + + + #### `global` * Default: false @@ -214,6 +230,27 @@ will be preferred. +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + + #### `strict-peer-deps` * Default: false @@ -253,39 +290,17 @@ This configuration does not affect `npm ci`. -#### `save` +#### `foreground-scripts` -* Default: `true` unless when using `npm update` or `npm dedupe` where it - defaults to `false` +* Default: false * Type: Boolean -Save installed packages to a `package.json` file as dependencies. +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) +scripts for installed packages in the foreground process, sharing standard +input, output, and error with the main npm process. -When used with the `npm rm` command, removes the dependency from -`package.json`. - -Will also prevent writing to `package-lock.json` if set to `false`. - - - - -#### `omit` - -* Default: 'dev' if the `NODE_ENV` environment variable is set to - 'production', otherwise empty. -* Type: "dev", "optional", or "peer" (can be set multiple times) - -Dependency types to omit from the installation tree on disk. - -Note that these dependencies _are_ still resolved and added to the -`package-lock.json` or `npm-shrinkwrap.json` file. They are just not -physically installed on disk. - -If a package type appears in both the `--include` and `--omit` lists, then -it will be included. - -If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment -variable will be set to `'production'` for all lifecycle scripts. +Note that this will generally make installs run slower, and be much noisier, +but can be useful for debugging. diff --git a/lib/commands/audit.js b/lib/commands/audit.js index fad43fe902df9..08d011d831875 100644 --- a/lib/commands/audit.js +++ b/lib/commands/audit.js @@ -14,6 +14,8 @@ class Audit extends ArboristWorkspaceCmd { 'json', 'package-lock-only', 'omit', + 'foreground-scripts', + 'ignore-scripts', ...super.params, ] diff --git a/lib/commands/ci.js b/lib/commands/ci.js index e054bee51679c..eb1e02bcdc724 100644 --- a/lib/commands/ci.js +++ b/lib/commands/ci.js @@ -24,6 +24,7 @@ class CI extends ArboristWorkspaceCmd { static name = 'ci' static params = [ 'audit', + 'foreground-scripts', 'ignore-scripts', 'script-shell', ] diff --git a/lib/commands/install.js b/lib/commands/install.js index 61526abb7879b..ebba02a1bd47d 100644 --- a/lib/commands/install.js +++ b/lib/commands/install.js @@ -14,15 +14,18 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js') class Install extends ArboristWorkspaceCmd { static description = 'Install a package' static name = 'install' + + // These are in the order they will show up in when running "-h" static params = [ 'save', 'save-exact', 'global', 'global-style', 'legacy-bundling', + 'omit', 'strict-peer-deps', 'package-lock', - 'omit', + 'foreground-scripts', 'ignore-scripts', 'audit', 'bin-links', diff --git a/lib/commands/prune.js b/lib/commands/prune.js index 16c8b6d4329ac..ee2c30553f1c5 100644 --- a/lib/commands/prune.js +++ b/lib/commands/prune.js @@ -6,7 +6,15 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js') class Prune extends ArboristWorkspaceCmd { static description = 'Remove extraneous packages' static name = 'prune' - static params = ['omit', 'dry-run', 'json', ...super.params] + static params = [ + 'omit', + 'dry-run', + 'json', + 'foreground-scripts', + 'ignore-scripts', + ...super.params, + ] + static usage = ['[[<@scope>/]...]'] async exec () { diff --git a/lib/commands/rebuild.js b/lib/commands/rebuild.js index 471d60b740df1..0e8a1510bde2b 100644 --- a/lib/commands/rebuild.js +++ b/lib/commands/rebuild.js @@ -11,6 +11,7 @@ class Rebuild extends ArboristWorkspaceCmd { static params = [ 'global', 'bin-links', + 'foreground-scripts', 'ignore-scripts', ...super.params, ] diff --git a/lib/commands/update.js b/lib/commands/update.js index 025ebbaf815f0..c2c3502eedd3d 100644 --- a/lib/commands/update.js +++ b/lib/commands/update.js @@ -10,14 +10,16 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js') class Update extends ArboristWorkspaceCmd { static description = 'Update packages' static name = 'update' + static params = [ + 'save', 'global', 'global-style', 'legacy-bundling', + 'omit', 'strict-peer-deps', 'package-lock', - 'save', - 'omit', + 'foreground-scripts', 'ignore-scripts', 'audit', 'bin-links', diff --git a/tap-snapshots/test/lib/load-all-commands.js.test.cjs b/tap-snapshots/test/lib/load-all-commands.js.test.cjs index d84cdfb305e90..df1cd5ae56618 100644 --- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs +++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs @@ -55,6 +55,7 @@ Options: [--audit-level ] [--dry-run] [-f|--force] [--json] [--package-lock-only] [--omit [--omit ...]] +[--foreground-scripts] [--ignore-scripts] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -121,7 +122,8 @@ Usage: npm ci Options: -[--no-audit] [--ignore-scripts] [--script-shell ] +[--no-audit] [--foreground-scripts] [--ignore-scripts] +[--script-shell ] aliases: clean-install, ic, install-clean, isntall-clean @@ -449,9 +451,9 @@ npm install / Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] -[--strict-peer-deps] [--no-package-lock] -[--omit [--omit ...]] [--ignore-scripts] -[--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +[--omit [--omit ...]] +[--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -469,7 +471,8 @@ Usage: npm install-ci-test Options: -[--no-audit] [--ignore-scripts] [--script-shell ] +[--no-audit] [--foreground-scripts] [--ignore-scripts] +[--script-shell ] alias: cit @@ -496,9 +499,9 @@ npm install-test / Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] -[--strict-peer-deps] [--no-package-lock] -[--omit [--omit ...]] [--ignore-scripts] -[--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +[--omit [--omit ...]] +[--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -742,7 +745,8 @@ npm prune [[<@scope>/]...] Options: [--omit [--omit ...]] [--dry-run] -[--json] [-w|--workspace [-w|--workspace ...]] +[--json] [--foreground-scripts] [--ignore-scripts] +[-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] Run "npm help prune" for more info @@ -773,7 +777,7 @@ Usage: npm rebuild [[<@scope>/][@] ...] Options: -[-g|--global] [--no-bin-links] [--ignore-scripts] +[-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -1063,11 +1067,11 @@ Usage: npm update [...] Options: -[-g|--global] [--global-style] [--legacy-bundling] [--strict-peer-deps] -[--no-package-lock] [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] -[--omit [--omit ...]] [--ignore-scripts] -[--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +[-g|--global] [--global-style] [--legacy-bundling] +[--omit [--omit ...]] +[--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] diff --git a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs index 42c24fabdfd61..8fc71437ee85d 100644 --- a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs +++ b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs @@ -210,6 +210,7 @@ All commands: [--audit-level ] [--dry-run] [-f|--force] [--json] [--package-lock-only] [--omit [--omit ...]] + [--foreground-scripts] [--ignore-scripts] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -268,7 +269,8 @@ All commands: npm ci Options: - [--no-audit] [--ignore-scripts] [--script-shell ] + [--no-audit] [--foreground-scripts] [--ignore-scripts] + [--script-shell ] aliases: clean-install, ic, install-clean, isntall-clean @@ -558,9 +560,9 @@ All commands: Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] - [--strict-peer-deps] [--no-package-lock] - [--omit [--omit ...]] [--ignore-scripts] - [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] + [--omit [--omit ...]] + [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] + [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -576,7 +578,8 @@ All commands: npm install-ci-test Options: - [--no-audit] [--ignore-scripts] [--script-shell ] + [--no-audit] [--foreground-scripts] [--ignore-scripts] + [--script-shell ] alias: cit @@ -601,9 +604,9 @@ All commands: Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] - [--strict-peer-deps] [--no-package-lock] - [--omit [--omit ...]] [--ignore-scripts] - [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] + [--omit [--omit ...]] + [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] + [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -819,7 +822,8 @@ All commands: Options: [--omit [--omit ...]] [--dry-run] - [--json] [-w|--workspace [-w|--workspace ...]] + [--json] [--foreground-scripts] [--ignore-scripts] + [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] Run "npm help prune" for more info @@ -846,7 +850,7 @@ All commands: npm rebuild [[<@scope>/][@] ...] Options: - [-g|--global] [--no-bin-links] [--ignore-scripts] + [-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root] @@ -1098,11 +1102,11 @@ All commands: npm update [...] Options: - [-g|--global] [--global-style] [--legacy-bundling] [--strict-peer-deps] - [--no-package-lock] [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] - [--omit [--omit ...]] [--ignore-scripts] - [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] + [-g|--global] [--global-style] [--legacy-bundling] + [--omit [--omit ...]] + [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] + [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] [-w|--workspace [-w|--workspace ...]] [-ws|--workspaces] [--include-workspace-root]