Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Scripts and Workspaces

Workspaces Basics

Learn what workspaces are, how to declare them in npm, Yarn and pnpm, how local packages link to each other, the workspace protocol, and how to run scripts across all packages.

Sometimes one repository holds several packages: a web app, an API, a shared library of utilities. Without help you would run npm install in each folder and link them together by hand. Workspaces let a single install at the repository root handle every package, and link your local packages to each other so edits are visible immediately. This lesson covers the basics; the Monorepos chapter goes deeper.

The layout

TEXT
my-repo/
  package.json            <- the root, lists the workspaces
  package-lock.json
  packages/
    shared/
      package.json        <- name: "@acme/shared"
      src/index.js
    web/
      package.json        <- depends on "@acme/shared"
      src/main.js
    api/
      package.json

The root package.json is usually private: true (it is not a publishable package) and says where the workspaces are.

Declaring workspaces

npm and Yarn use the workspaces field in the root package.json:

JSON
{
  "name": "my-repo",
  "private": true,
  "workspaces": ["packages/*"]
}

pnpm uses a separate file, pnpm-workspace.yaml, in the root:

YAML
packages:
  - "packages/*"

Globs select the folders; each folder containing a package.json becomes a workspace. After npm install (or yarn, pnpm install) at the root, there is one node_modules at the top, one lockfile, and the local packages are linked into it.

Linking local packages

If web imports @acme/shared, you write its dependency as usual, using the shared package's current version or a workspace specifier:

JSON
{
  "name": "@acme/web",
  "version": "1.0.0",
  "dependencies": { "@acme/shared": "*" }
}

Instead of downloading @acme/shared from the registry, the manager sees that a workspace with that name exists and creates a symlink: node_modules/@acme/shared points at packages/shared. Edit the shared code and web sees the change at once, with no publish step.

pnpm and Yarn Berry offer the explicit workspace protocol: "@acme/shared": "workspace:*" (always link, never fetch from the registry). When publishing, they replace workspace:* with the real version number. npm resolves the plain range against the local workspace when versions match, so "*" or a matching ^1.0.0 also links locally.

Node.js Resolving workspace dependencies (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Running commands in workspaces

Terminal
# npm
npm install lodash --workspace=packages/web       # add a dependency to one workspace (-w)
npm run build --workspaces                        # run "build" in every workspace (-ws)
npm run test -w @acme/shared                      # run in one workspace
npm run build --workspaces --if-present           # skip those without the script

# Yarn Berry
yarn workspace @acme/web add lodash
yarn workspaces foreach --all run build

# pnpm
pnpm --filter @acme/web add lodash
pnpm -r run build                                 # -r = recursive, in dependency order
pnpm --filter "...@acme/shared" run test          # shared plus everything depending on it

Order matters: if web imports shared's build output, shared must be built first. pnpm sorts recursive runs topologically for you; Yarn's foreach accepts --topological; with npm you control the order via the workspaces list or a task runner.

Node.js Build order from a dependency graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A cycle between workspaces (a needs b, b needs a) cannot be ordered and is a design problem to fix, not a tooling problem.

Hoisting in workspaces

In npm and Yarn Classic, packages shared by several workspaces are hoisted to the root node_modules, so each library is stored once. A workspace may still have its own nested node_modules for conflicting versions. In pnpm every workspace gets only its declared dependencies, linked from the store, which keeps strictness (and the phantom-dependency protection from npm, Yarn and pnpm Compared).

Shared dev tooling

Put tools used everywhere (TypeScript, ESLint, Prettier, a test runner) in the root devDependencies so every workspace uses the same version. Packages with specialized needs add their own. The root also usually holds scripts that fan out to the workspaces: "build": "npm run build --workspaces".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does pnpm declare its workspaces?

    pnpm reads the packages globs from pnpm-workspace.yaml.
  2. 2. What happens when a workspace depends on another local package?

    Workspace packages are linked locally rather than downloaded.
  3. 3. What does workspace:* mean?

    The workspace protocol forces linking and is rewritten on publish.
  4. 4. Why does build order matter in a workspace?

    Dependencies must be built before their dependents.

Summary

  • Workspaces let one repository hold several packages with one install and one lockfile.
  • npm and Yarn use the workspaces field; pnpm uses pnpm-workspace.yaml.
  • Local packages are symlinked; workspace:* makes it explicit in pnpm and Yarn.
  • Run scripts across workspaces with --workspaces, workspaces foreach or pnpm -r.
  • Put shared tooling in the root and watch the dependency order.

Next: Preparing a Package for Publishing