npm workspaces let one root package manage several local packages in the same repository. A single install links them together and writes one lockfile at the root, so dependency decisions are made once for the whole repo instead of separately in each folder.
How they are declared
The root package.json lists the workspace folders.
{
"name": "my-monorepo",
"workspaces": ["packages/a", "packages/b"]
}
Each folder has its own package.json. You can scaffold one with npm init -w ./packages/a, which creates the folder and updates the root config.
What an install does
On install, npm symlinks each workspace into the root node_modules. For example, node_modules/a points to ../packages/a. That replaces the manual npm link step, and other code can require a workspace by the name in its package.json.
The post install layout in the npm documentation shows a single package-lock.json at the root. One lockfile means one place to review dependency changes, which is a real advantage for security review.
Running commands
npm install abbrev -w aadds a dependency to one workspace.- The workspace option, short form
-w, can be repeated to target several. - The workspaces option runs a command in all workspaces.
- The if-present option skips workspaces that lack the script.
Commands run in the order the workspaces appear in the root package.json, and reordering the array changes the run order. Other install related commands, such as uninstall and ci, also respect the workspace option.
Hygiene practices for a workspace repo
Keep versions aligned. If five packages use five different ranges of the same library, you get duplicates and uneven security fixes. Choose one range and use it everywhere.
Review the root lockfile in every pull request. A change in one workspace can move versions used by another.
Use the lockfile in CI. npm ci installs from the lockfile and fails if it disagrees with package.json, so drift is caught early.
Remember overrides live at the root. npm only considers overrides in the root package.json, not in workspaces.
Do not treat internal packages as trusted by default. A workspace package can still pull in vulnerable third party code.
Where scanning fits
A monorepo can hide a lot of dependencies behind a few manifests. An SBOM generated from the whole repository shows what each workspace actually pulls in. The demo below shows an inventory view of that kind.
Click through it at your own pace, or open it full screen.
Safeguard's SBOM and dependency scanning covers repositories like this, and you can try a free scan at gold.safeguard.sh/scan. For wider monorepo guidance, see monorepo security and dependency management.
Quick check
How many lockfiles does an npm workspaces repo have?
The documentation's example shows a single package-lock.json at the root.
Can I put overrides in a workspace package.json?
No. npm only considers overrides in the root package.json.
Sources
Last reviewed: 19 October 2026.
