With npm workspaces, how do you run `test` in every workspace when some lack it, and include the root's own `test`?
answer
- plural flag selects all
- skip missing, still fail failing
- root left out by default
- root runs first when included
- npm 12 rejects single-hyphen -ws
basics
~20 sRun npm run test --workspaces --if-present: npm runs test in each workspace in turn and skips those without the script. Add --include-workspace-root to run the root's test first; on npm 12 the single-hyphen -ws spelling throws.
solid answer
~40 s`--workspaces` (alias `--ws`) runs the script in every configured workspace, one after another, in the order the root `workspaces` field lists them; `-w <name>`, repeatable, or `-w packages` targets one, several, or every workspace under a folder. Without `--if-present`, a workspace that has no `test` reports `Missing script: "test"`, npm carries on with the others and the command exits non-zero; `--if-present` skips those workspaces, but a script that exists and fails still fails. The root package is left out whenever workspaces are selected; `--include-workspace-root` adds it, and it runs first. On npm 12, spell these flags in full or with their double-hyphen aliases: npm 12 throws on single-hyphen multi-character shorthands, so the `-ws` form older guides show now fails.
go deeper
Recall the three flags: --workspaces for all, --if-present to skip missing scripts, --include-workspace-root to add the root.
Explain the run loop: sequential, in workspaces-field order, failures labelled by workspace, the loop continuing, and a non-zero exit at the end.
Show you can debug a CI step after an npm 12 upgrade: single-hyphen -ws now throws, and --if-present never masks a failing script.
Be clear about what npm's loop does not give you, dependency order, parallelism and skipping unchanged packages, and when that gap justifies more tooling.
## Selecting workspaces for a command In an npm repository with workspaces, `npm run` (and its shortcuts such as `npm test`) runs in the **root package** unless you tell it otherwise. Two configs move it into the workspaces: | Flag | Selects | |---|---| | `-w <name>` / `--workspace=<name>` | one workspace by name, e.g. `-w @rota/ui` | | `-w <name> -w <other>` | several workspaces, one per repetition | | `-w <folder>` | the workspace in that folder, or every workspace under a parent folder such as `packages` | | `--workspaces` (alias `--ws`) | **every** configured workspace | | `--include-workspace-root` | adds the root package to whichever workspaces are selected | So, for the shift-rota repository, `npm run test --workspaces` runs `test` in `@rota/ui`, `@rota/date-rules`, `@rota/config` and both apps, and `npm test -w @rota/ui -w @rota/date-rules` runs it in just those two. Running `npm run -w @rota/ui` with no script name lists the scripts that workspace defines. ## Skipping workspaces without the script: `--if-present` Not every workspace defines every script; `@rota/config` might hold only JSON and have no `test`. Without help, npm reports `Missing script: "test"` for that workspace. The **`--if-present`** flag tells npm not to treat a missing script as an error: ```bash npm run test --workspaces --if-present ``` It skips only **missing** scripts. A `test` script that exists and fails still fails; `--if-present` is meant for running a script when it is present and failing if it fails. ## Including the root: `--include-workspace-root` When workspaces are selected, the root package is **left out** by default (`include-workspace-root` defaults to `false`). If the root has its own `test`, for example repository-wide checks, add the flag: ```bash npm run test --workspaces --if-present --include-workspace-root ``` The root runs **first**, then each workspace. ## What happens when one workspace fails npm walks the selected workspaces **one after another**: 1. It runs the script in the first selected package and waits for it to finish. 2. If the script exits non-zero (or is missing without `--if-present`), npm prints the error with the **workspace name and its location** and records a failing exit code. 3. It **carries on** with the remaining workspaces rather than stopping. 4. When the loop ends, the command exits **non-zero** if any workspace failed, so a CI step still fails. The practical consequence: the log shows every workspace's result, but you have to scroll for the failure, which is labelled with the workspace that produced it. ## Order, and what npm does not do Workspaces run in the **order the root `workspaces` field lists them**; swapping two entries in that array swaps their run order. npm does **not** work out an order from the dependencies between workspaces, does not run them in parallel and does not skip unchanged ones. If `@rota/ui`'s `build` needs `@rota/date-rules` built first, list the folders in that order or chain the scripts explicitly; dependency-aware ordering and result caching are what dedicated build orchestrators add on top. ## Recipes worth remembering - **Every workspace, tolerant of gaps:** `npm run test --workspaces --if-present`. - **Every workspace plus the root:** add `--include-workspace-root`; the root runs first. - **Two named workspaces:** `npm test -w @rota/ui -w @rota/date-rules`. - **Everything under one folder:** `npm run build -w packages`, which selects each workspace inside `packages/` but not the apps. - **A tool with no script:** `npm exec --ws -- eslint ./*.js` runs the command in the context of each workspace. - **Arguments for the script:** put them after `--`, as with any `npm run`, so npm does not read them as its own flags. A typical CI step therefore reads `npm run test --workspaces --if-present`, and its exit code is the signal: non-zero if any selected workspace failed or, without `--if-present`, lacked the script. ## npm 12: spell the flags in full npm 12.0.0 made **unknown CLI flags, abbreviated flags and single-hyphen multi-character shorthands throw** instead of only warning. Older guides and CI files often show `npm run test -ws`; on npm 12 that single-hyphen form fails before any script runs. Use the long names or their double-hyphen aliases: - `--workspaces` or `--ws` for all workspaces; - `--include-workspace-root` or `--iwr` for the root; - `-w <name>` stays valid, because `w` is a single-character short option. Unknown and abbreviated long flags throw on npm 12 as well. When a pipeline breaks right after an upgrade, check the spelling of these flags first.
- Does `--if-present` hide a workspace whose `test` script exists but fails?No. It only stops a missing script from being an error. A script that exists and exits non-zero is reported with its workspace name and location, npm continues with the remaining workspaces, and the command still exits non-zero, so CI fails as it should.
- How do you run a tool from `node_modules/.bin` in every workspace when no script wraps it?Use `npm exec` with the same selection flags, for example `npm exec --ws -- eslint ./*.js`, or `-w <name>` for one workspace. The command runs in the context of each selected workspace in turn, just as `npm run` does.
- What does `npm run -w @rota/ui` print when you give it no script name?It lists the scripts that `@rota/ui` defines. With `--workspaces` and no script name, npm prints the available scripts for every configured workspace, which is a quick way to see which ones are missing a `test` before relying on `--if-present`.
- --if-present also skips workspaces whose test script exists but fails.
- --workspaces runs the root package's own script as well.
- npm orders workspace scripts by the dependencies between workspaces.
- One failing workspace stops npm before it runs the rest.
- npm run test -ws is still a valid spelling on npm 12.
Assumes npm 12.2; the workspace flags behave the same since npm 7, but npm 12.0.0 made single-hyphen multi-character shorthands such as -ws, abbreviated flags and unknown flags throw instead of warn.