Using npm Workspaces to Hoist Dependencies in a Monorepo

The problem: duplicated installs in a growing monorepo

When a repository holds several related packages, each with its own package.json, running npm install in every folder creates separate node_modules trees. This wastes disk space, slows down CI, and makes it easy for different packages to drift onto different versions of the same dependency.

Thesis: npm workspaces hoist shared dependencies to a single root node_modules, giving a predictable, space‑efficient layout while still letting each workspace declare its own version ranges.

Enabling workspaces

1. At the repository root, add a "workspaces" array to package.json that lists the relative paths of each workspace. A common pattern is to use a glob:

{
  "private": true,
  "workspaces": ["packages/*"]
}

1. Run npm install from the root directory. npm creates a single node_modules folder at the root and symlinks each workspace into it.
2. Each workspace can still have its own package.json with dependencies, scripts, and version.

Worked example: two libraries sharing a utility

Assume the following layout:

my-monorepo/
├─ package.json          # root, with workspaces
├─ packages/
│   ├─ lib-a/
│   │   └─ package.json
│   └─ lib-b/
│       └─ package.json
└─ node_modules/         # created after install

Root package.json (as shown above).

packages/lib-a/package.json:

{
  "name": "lib-a",
  "version": "1.0.0",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

packages/lib-b/package.json:

{
  "name": "lib-b",
  "version": "1.0.0",
  "dependencies": {
    "lodash": "^4.17.21",
    "lib-a": "1.0.0"
  }
}

After running npm install at the root (requires npm ≥ 7):

• A single node_modules appears at the repository root.
• Inside it, lodash is installed once at node_modules/lodash.
• Both lib-a and lib-b are symlinked into node_modules and can require('lodash') or import lodash from 'lodash' without extra linking.

Verifying the hoist

You can confirm that both workspaces see the same copy:

# From the repository root
cd packages/lib-a
node -e "console.log(require.resolve('lodash'))"
cd ../lib-b
node -e "console.log(require.resolve('lodash'))"

Both commands should print the same absolute path, e.g., /path/to/my-monorepo/node_modules/lodash/package.json.

Alternatively, run:

npm ls lodash

which shows a single entry under the root node_modules.

Trade‑off and limitation: version hoisting can hide mismatches

npm hoists a dependency to the version that satisfies the most dependents. When workspace version ranges conflict, npm may nest a duplicate copy for the workspace that needs a different version. This means a workspace can receive a version outside its declared range, and the resulting error may only appear at runtime.

Practical check: after npm install, run npm ls <package> from each workspace directory. If you notice a workspace receiving a version outside its declared range, you can:

• Add an explicit "overrides" field in the root package.json to force the desired version, or
• Declare the dependency as a devDependency in the workspace that needs the specific version and avoid hoisting it.

Actionable closing

Start small: add a workspaces array to your root package.json, run npm install from the root, and verify a single node_modules tree with npm ls. Keep an eye on version ranges; use npm ls or require.resolve to confirm each workspace gets the expected copy. When a conflict appears, employ overrides or adjust the workspace’s dependencies rather than abandoning workspaces altogether.