npm workspaces: run the owning package’s script

Identify where the build script is defined

Inspect the root manifest and the child package manifests. A root-level missing-script error can be correct even when both child packages define build.

Our fixture root declared packages/* as workspaces and had no root build script. Running npm run build there failed. The packages @fixture/api and @fixture/web each had a small independent build script.

Verify the declared workspace structure

This root fragment describes the local test layout. Each matched child directory must contain its own package manifest. The names used for explicit selection belong to those child manifests.

If the real root already has a build script, inspect what it does before adding more command layers. An existing task runner can have different dependency-order and caching semantics from a direct npm workspace invocation.

json · EXAMPLE

{
  "name": "workspace-root",
  "private": true,
  "workspaces": ["packages/*"]
}

Run only the package that owns the operation

From the workspace root, select the intended package name. In the fixture, the following command produced api built and created the API’s marker file without creating the web package’s marker.

These are synthetic package names. Use the corresponding name or supported workspace path from the actual repository, and confirm the package defines the required script.

sh · EXAMPLE

npm run build --workspace=@fixture/api

Choose all-workspace execution deliberately

The plural option executes the script in the configured workspaces. In our test, both small packages ran. That is a different operation from repairing a single API build invocation.

Do not use --if-present to conceal a missing required build. It can be appropriate when scripts are intentionally optional, but that policy needs to match the repository. npm workspace selection does not infer a full framework build graph.

sh · EXAMPLE

# Use only when building all configured workspaces is intended:
npm run build --workspaces

Verify scope and output in automation

Check both the target output and packages that should remain untouched. A successful run in the wrong workspace can still be a failed deployment step if the required artifact is absent.

Record the working directory, workspace selector, script, and expected artifact. Fix the CI invocation that owns the mistake rather than adding a root placeholder script that succeeds without building the needed package.

Know the limits

Reproduced with npm 12.2.1 and Node.js 24.22.1 in a disposable Linux container using local fixtures, with external networking disabled during tests. The root declared two workspaces but no build script. A targeted run built only the API workspace; --workspaces then reached both configured packages. Dependency linking, hoisting, build dependency graphs, and framework task scheduling were not tested.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles