diff options
author | Ruy Adorno <ruyadorno@hotmail.com> | 2021-03-07 20:13:58 +0300 |
---|---|---|
committer | Gar <gar+gh@danger.computer> | 2021-03-22 20:22:38 +0300 |
commit | e1b3b318f095a7e1a7cc4b131907de4955275d9d (patch) | |
tree | cb2cf7f6fa70a6eb546431f10bbe8124febe1db5 /docs | |
parent | b876442241b9d366a0541714bbee1ae50d6746fd (diff) |
feat: add exec workspaces
Add workspaces support to `npm exec`
- Refactored logic to read and filter workspaces into
`lib/workspaces/get-workspaces.js`
- Added location context message when entering interactive
shell using `npm exec` (with no args)
- Add ability to execute a package in the context of each
configured workspace
Fixes: https://github.com/npm/statusboard/issues/288
PR-URL: https://github.com/npm/cli/pull/2886
Credit: @ruyadorno
Close: #2886
Reviewed-by: @wraithgar
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/commands/npm-exec.md | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md index cb3e51c82..88b98e3bc 100644 --- a/docs/content/commands/npm-exec.md +++ b/docs/content/commands/npm-exec.md @@ -11,6 +11,7 @@ npm exec -- <pkg>[@<version>] [args...] npm exec --package=<pkg>[@<version>] -- <cmd> [args...] npm exec -c '<cmd> [args...]' npm exec --package=foo -c '<cmd> [args...]' +npm exec [-ws] [-w <workspace-name] [args...] npx <pkg>[@<specifier>] [args...] npx -p <pkg>[@<specifier>] <cmd> [args...] @@ -145,6 +146,68 @@ $ npm x -c 'eslint && say "hooray, lint passed"' $ npx -c 'eslint && say "hooray, lint passed"' ``` +### Workspaces support + +You may use the `workspace` or `workspaces` configs in order to run an +arbitrary command from an npm package (either one installed locally, or fetched +remotely) in the context of the specified workspaces. +If no positional argument or `--call` option is provided, it will open an +interactive subshell in the context of each of these configured workspaces one +at a time. + +Given a project with configured workspaces, e.g: + +``` +. ++-- package.json +`-- packages + +-- a + | `-- package.json + +-- b + | `-- package.json + `-- c + `-- package.json +``` + +Assuming the workspace configuration is properly set up at the root level +`package.json` file. e.g: + +``` +{ + "workspaces": [ "./packages/*" ] +} +``` + +You can execute an arbitrary command from a package in the context of each of +the configured workspaces when using the `workspaces` configuration options, +in this example we're using **eslint** to lint any js file found within each +workspace folder: + +``` +npm exec -ws -- eslint ./*.js +``` + +#### Filtering workspaces + +It's also possible to execute a command in a single workspace using the +`workspace` config along with a name or directory path: + +``` +npm exec --workspace=a -- eslint ./*.js +``` + +The `workspace` config can also be specified multiple times in order to run a +specific script in the context of multiple workspaces. When defining values for +the `workspace` config in the command line, it also possible to use `-w` as a +shorthand, e.g: + +``` +npm exec -w a -w b -- eslint ./*.js +``` + +This last command will run the `eslint` command in both `./packages/a` and +`./packages/b` folders. + ### Compatibility with Older npx Versions The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx` @@ -195,6 +258,30 @@ requested from the server. To force full offline mode, use `offline`. Forces full offline mode. Any packages not locally cached will result in an error. +#### workspace + +* Alias: `-w` +* Type: Array +* Default: `[]` + +Enable running scripts in the context of workspaces while also filtering by +the provided names or paths provided. + +Valid values for the `workspace` config are either: +- Workspace names +- Path to a workspace directory +- Path to a parent workspace directory (will result to selecting all of the +children workspaces) + +#### workspaces + +* Alias: `-ws` +* Type: Boolean +* Default: `false` + +Run scripts in the context of all configured workspaces for the current +project. + ### See Also * [npm run-script](/commands/npm-run-script) |