skip to content

Workspaces & Monorepos

Globs in the root package.json, packages symlinked into node_modules, one root lockfile, and the --workspace and --workspaces flags. Asked when sibling packages must build together unpublished.

on this pageshow

questions

5

In an npm project, what does the root package.json `workspaces` field declare, and what does one `npm install` at the root then produce?

level: juniorimportance: must knowfreq 32%

answer

  1. globs in the root manifest
  2. folder needs its own package.json
  3. symlink, not a copy
  4. one root lockfile
  5. npm init -w packages/<name>

basics

~20 s

The root workspaces field lists the folders or globs, such as packages/*, that hold sibling packages. One root npm install symlinks each into the root node_modules by name, hoists shared dependencies there and writes a single root package-lock.json.

solid answer

~40 s

The `workspaces` field in the root `package.json` is an array of paths or globs, for example `"workspaces": ["packages/*"]`; every matched folder that contains a valid `package.json` becomes a workspace. One `npm install` at the root then symlinks each workspace into the root `node_modules` under its package name (`node_modules/@rota/ui` points at `packages/ui`), so siblings can import each other without publishing. It installs all the workspaces' dependencies as one tree, hoisting the ones they share to the root `node_modules`, and records everything in a single root `package-lock.json`, where each workspace shows up as a link. `npm init -w packages/config` scaffolds a new workspace and adds it to the field, and no manual `npm link` step is needed.

go deeper

for a junior

Recall the shape: a root workspaces array of paths or globs, one install at the root, symlinks into the root node_modules, and one root lockfile.

for a middle

Explain why the symlink matters: workspaces are found by package name through node_modules, edits show up without reinstalling, and shared dependencies are hoisted to the root.

for a senior

Show you know what the single root lockfile implies for review and CI: one file records every workspace, and links appear as link entries pointing at the folders.

for a principal

Frame workspaces as npm's linking and install layer only, and keep it distinct from questions of repository strategy and build orchestration when you advise a team.

## What a workspace is in npm In npm, **workspaces** is the name for the set of features that let one **root package** manage several packages that live in the same repository, on the local file system, and build together before any of them is published. Each of those nested packages is a **workspace**: an ordinary folder with its own `package.json`, its own `name`, its own `dependencies` and its own `scripts`. The root package is the folder that holds the top-level `package.json` and the one place where you run `npm install`. Picture a hospital shift-rota repository: a staff web app, an admin portal and three shared packages, `@rota/ui`, `@rota/date-rules` and `@rota/config`, all under `packages/`. Without workspaces, the apps could only use the shared packages by publishing them first or by wiring them together by hand with `npm link`. Workspaces automate that linking as part of the normal install. ## Declaring workspaces: the root `workspaces` field The root `package.json` declares where the workspaces are with the `workspaces` field, an **array of file patterns**. Each entry can be a direct path to one folder or a **glob** that matches many: ```json { "name": "rota-root", "private": true, "workspaces": ["packages/*", "apps/*"] } ``` With `"packages/*"`, every folder directly under `packages/` becomes a workspace **as long as it contains a valid `package.json`**. A folder without one is not a workspace, so a stray `packages/notes/` folder is simply ignored. ## What one root `npm install` produces Running `npm install` once, at the root, does all of the following in a single pass: 1. **Reads the globs** in `workspaces` and turns them into the list of workspace folders. 2. **Symlinks each workspace into the root `node_modules`** under its package `name`, so `node_modules/@rota/ui` is a link to `../packages/ui`, not a copy. Any code in the repository can now `require('@rota/ui')` or `import` it by name. 3. **Installs every workspace's dependencies into one tree.** A dependency that several workspaces share, at compatible versions, is installed once and **hoisted** to the root `node_modules`; a workspace that needs an incompatible version gets its own nested copy. 4. **Writes one root `package-lock.json`** that records the whole tree, including every workspace. A linked workspace appears in it as an entry flagged `"link": true` whose `resolved` value is the workspace folder. Afterwards the layout looks roughly like this: ``` . +-- node_modules | +-- @rota/ui -> ../packages/ui | `-- @rota/date-rules -> ../packages/date-rules +-- package-lock.json +-- package.json `-- packages +-- ui/package.json `-- date-rules/package.json ``` The root install writes no lockfile inside the workspace folders: the root lockfile is the record for all of them. ## Adding a new workspace with `npm init -w` You do not have to create the folder and edit the root manifest by hand. `npm init -w packages/config` creates the folder (if it is missing), writes a new `package.json` in it if there is none, and adds the workspace to the root `workspaces` field. The `-w` value names a folder that does not exist yet; npm sets it up as a brand-new workspace. Run `npm install` afterwards so the new package is linked. ## The pieces at a glance | Piece | Where it lives | Written by | |---|---|---| | `workspaces` globs | root `package.json` | you, or `npm init -w` | | each workspace's `dependencies` | the workspace's own `package.json` | you, or `npm install <pkg> -w <name>` | | the workspace links | root `node_modules` | `npm install` at the root | | hoisted shared dependencies | root `node_modules` | `npm install` at the root | | the lockfile | one root `package-lock.json` | `npm install` at the root | ## Common misreadings - **"Every workspace gets its own lockfile."** It does not; there is one root `package-lock.json` for the whole repository. - **"npm copies the workspace into `node_modules`."** It creates a **symlink**, so an edit in `packages/ui` is visible to its consumers at once, with no reinstall. - **"You still need `npm link`."** Workspaces exist to remove that manual step; linking happens during `npm install`. - **"Globs are not allowed."** The field accepts both direct paths and globs. - **"A sibling must be published first."** A workspace is consumed straight from the local folder by its declared `name`. Monorepo strategy, whether one repository is the right shape at all, and build orchestration are separate subjects; this is only how npm itself lays the packages out.

  • A folder matched by the packages/* glob has no package.json. What does npm do with it?
    It is not a workspace. npm treats a matched folder as a workspace only when it contains a valid `package.json`, so the folder is skipped: nothing is linked into `node_modules` for it and it never appears among the workspaces a `--workspaces` command runs in.
  • What does `npm init -w packages/config` do that creating the folder by hand does not?
    It creates the folder if it is missing, writes a new `package.json` inside it if needed, and adds the workspace to the root `package.json` `workspaces` field in one step. Created by hand, the folder still needs its own `package.json` and a matching entry or glob in the root field before `npm install` will link it.
  • Do you still need `npm link` to let the staff web app import `@rota/ui`?
    No. Workspaces automate that linking as part of `npm install`: the root install symlinks `@rota/ui` into the root `node_modules`, and Node.js finds it by name from anywhere in the repository. Because it is a symlink, edits in `packages/ui` are visible at once.

  • Each workspace gets its own package-lock.json next to its package.json.
  • npm copies each workspace's files into node_modules during install.
  • You must run npm link in every package before siblings can import it.
  • The workspaces field only accepts exact paths, never globs.
  • A sibling package must be published before another workspace can use it.
open as a page

With npm workspaces, how do you run `test` in every workspace when some lack it, and include the root's own `test`?

level: middleimportance: should knowfreq 17%

basics

~20 s

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

open as a page

In an npm workspaces repo, `@rota/ui` imports `zone-kit` without declaring it; tests pass locally but consumers get Cannot find module, so why, and what catches it earlier?

level: seniorimportance: should knowfreq 13%

basics

~20 s

Hoisting put zone-kit in the root node_modules because a sibling or the root declares it, and Node.js finds it by walking up from packages/ui. Consumers get only declared dependencies. Declare it with npm install zone-kit -w @rota/ui; test under install-strategy=linked.

open as a page

In an npm workspaces repo, `@rota/date-rules` was bumped to 2.0.0 while `@rota/ui` still declares `^1.0.0`; why does `npm install` now fail with E404?

level: seniorimportance: nice to knowfreq 7%

basics

~20 s

npm links a sibling workspace only when its local version satisfies the dependent's range. 2.0.0 is outside ^1.0.0, so npm asks the registry for @rota/date-rules, which was never published. Re-save the range with npm install @rota/date-rules -w @rota/ui.

open as a page