Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add run-script workspaces #2864

Merged
merged 1 commit into from
Mar 18, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/content/commands/npm-adduser.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ npm adduser [--registry=url] [--scope=@orgname] [--always-auth] [--auth-type=leg
aliases: login, add-user
```

Note: This command is unaware of workspaces.

### Description

Create or verify a user named `<username>` in the specified registry, and
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-bin.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Display npm bin folder
npm bin [-g|--global]
```

Note: This command is unaware of workspaces.

### Description

Print the folder where npm will install executables.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ aliases: npm cache clear, npm cache rm
npm cache verify
```

Note: This command is unaware of workspaces.

### Description

Used to add, list, or clean the npm cache folder.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-completion.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Tab Completion for npm
source <(npm completion)
```

Note: This command is unaware of workspaces.

### Description

Enables tab-completion in all npm commands.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ npm get [<key> [<key> ...]]
alias: c
```

Note: This command is unaware of workspaces.

### Description

npm gets its config settings from the command line, environment
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-deprecate.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Deprecate a version of a package
npm deprecate <pkg>[@<version range>] <message>
```

Note: This command is unaware of workspaces.

### Description

This command will update the npm registry entry for a package, providing a
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-doctor.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Check your npm environment
npm doctor
```

Note: This command is unaware of workspaces.

### Description

`npm doctor` runs a set of checks to ensure that your npm installation has
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-edit.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Edit an installed package
npm edit <pkg>
```

Note: This command is unaware of workspaces.

### Description

Selects a dependency in the current project and opens the package folder in
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-explore.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Browse an installed package
npm explore <pkg> [ -- <command>]
```

Note: This command is unaware of workspaces.

### Description

Spawn a subshell in the directory of the installed package specified.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-help-search.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Search npm help documentation
npm help-search <text>
```

Note: This command is unaware of workspaces.

### Description

This command will search the npm markdown documentation files for the terms
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Get help on npm
npm help <term> [<terms..>]
```

Note: This command is unaware of workspaces.

### Description

If supplied a topic, then show the appropriate documentation page.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-hook.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ npm hook update <id> <url> [secret]
npm hook rm <id>
```

Note: This command is unaware of workspaces.

### Description

Allows you to manage [npm
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-logout.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Log out of the registry
npm logout [--registry=<url>] [--scope=<@scope>]
```

Note: This command is unaware of workspaces.

### Description

When logged into a registry that supports token-based authentication, tell
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-org.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ npm org rm <orgname> <username>
npm org ls <orgname> [<username>]
```

Note: This command is unaware of workspaces.

### Example

Add a new developer to an org:
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-owner.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ npm owner ls [<@scope>/]<pkg>
aliases: author
```

Note: This command is unaware of workspaces.

### Description

Manage ownership of published packages.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-ping.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Ping npm registry
npm ping [--registry <registry>]
```

Note: This command is unaware of workspaces.

### Description

Ping the configured or given npm registry and verify authentication.
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-prefix.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Display prefix
npm prefix [-g]
```

Note: This command is unaware of workspaces.

### Description

Print the local prefix to standard output. This is the closest parent directory
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-profile.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ npm profile enable-2fa [auth-and-writes|auth-only]
npm profile disable-2fa
```

Note: This command is unaware of workspaces.

### Description

Change your profile information on the registry. Note that this command
Expand Down
85 changes: 85 additions & 0 deletions docs/content/commands/npm-run-script.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ description: Run arbitrary package scripts

```bash
npm run-script <command> [--if-present] [--silent] [-- <args>]
npm run-script <command> [--workspace=<workspace-name>]
npm run-script <command> [--workspaces]

aliases: run, rum, urn
```
Expand Down Expand Up @@ -78,6 +80,65 @@ If you try to run a script without having a `node_modules` directory and it
fails, you will be given a warning to run `npm install`, just in case you've
forgotten.

### Workspaces support

You may use the `workspace` or `workspaces` configs in order to run an
arbitrary command from a package's `"scripts"` object in the context of the
specified workspaces. If no `"command"` is provided, it will list the available
scripts for each of these configured workspaces.

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/*" ]
}
```

And that each of the configured workspaces has a configured `test` script,
we can run tests in all of them using the `workspaces` config:

```
npm test --workspaces
```

#### Filtering workspaces

It's also possible to run a script in a single workspace using the `workspace`
config along with a name or directory path:

```
npm test --workspace=a
```

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 test -w a -w b
```

This last command will run `test` in both `./packages/a` and `./packages/b`
packages.


### Configuration

#### if-present
Expand Down Expand Up @@ -111,6 +172,30 @@ to `/bin/sh` on Unix, defaults to `env.comspec` or `cmd.exe` on Windows.

You can use the `--silent` flag to prevent showing `npm ERR!` output on 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 scripts](/using-npm/scripts)
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-search.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms .
aliases: s, se, find
```

Note: This command is unaware of workspaces.

### Description

Search the registry for packages matching the search terms. `npm search`
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-shrinkwrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Lock down dependency versions for publication
npm shrinkwrap
```

Note: This command is unaware of workspaces.

### Description

This command repurposes `package-lock.json` into a publishable
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-star.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Mark your favorite packages
npm star [<pkg>...]
```

Note: This command is unaware of workspaces.

### Description

"Starring" a package means that you have some interest in it. It's
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-stars.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ description: View packages marked as favorites
npm stars [<user>]
```

Note: This command is unaware of workspaces.

### Description

If you have starred a lot of neat things and want to find them again
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-team.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ npm team rm <scope:team> <user>
npm team ls <scope>|<scope:team>
```

Note: This command is unaware of workspaces.

### Description

Used to manage teams in organizations, and change team memberships. Does not
Expand Down
4 changes: 3 additions & 1 deletion docs/content/commands/npm-token.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ description: Manage your authentication tokens
npm token list [--json|--parseable]
npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16]
npm token revoke <id|token>
```
```

Note: This command is unaware of workspaces.

### Description

Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-unstar.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Remove an item from your favorite packages
npm unstar [<pkg>...]
```

Note: This command is unaware of workspaces.

### Description

"Unstarring" a package is the opposite of [`npm star`](/commands/npm-star),
Expand Down
2 changes: 2 additions & 0 deletions docs/content/commands/npm-whoami.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description: Display npm username
npm whoami [--registry <registry>]
```

Note: This command is unaware of workspaces.

### Description

Print the `username` config to standard output.
Expand Down
46 changes: 46 additions & 0 deletions docs/content/using-npm/workspaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,54 @@ This demonstrates how the nature of `node_modules` resolution allows for
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 man use the `workspace` configuration option to run commands in the context
of a configured 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
```

This 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
```

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`.

### See also

* [npm install](/commands/npm-install)
* [npm publish](/commands/npm-publish)
* [npm run-script](/commands/npm-run-script)

Loading