In an npm project, what does the root package.json `workspaces` field declare, and what does one `npm install` at the root then produce?
answer
- globs in the root manifest
- folder needs its own package.json
- symlink, not a copy
- one root lockfile
- npm init -w packages/<name>
basics
~20 sThe 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 sThe `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
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.
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.
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.
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.