Using pnpm overrides to lock dependency versions across a monorepo

When two packages ask for different versions of the same dependency

In a monorepo it’s common for one workspace to depend on lodash@4.17.15 while another workspace needs lodash@4.17.21. When you run pnpm install pnpm will try to satisfy both requests, which can lead to duplicate copies of lodash in the virtual store or warnings about unmet peer dependencies. The result is a less predictable bundle and extra disk usage.

Thesis

pnpm’s overrides field lets you declare a single version for a dependency (including transitive ones) that pnpm will enforce for the whole project, eliminating the conflict without forking upstream packages.

How overrides work in pnpm

Starting with lockfile version 6, pnpm reads the overrides object in the root package.json. During installation it treats the specified version as a hard requirement: any request for that package name (or a scoped path like foo@^2/bar) is replaced with the overridden version before the dependency graph is resolved. The overridden version is then hoisted to the virtual store and shared by all dependents.

Overrides do not alter the published package; they only affect pnpm’s node_modules layout. Other package managers that don’t understand the field may still resolve different versions unless they also implement overrides.

Worked example: forcing a lodash version

1. Create a fresh workspace (run in a terminal with write access to the directory):

   pnpm init
   mkdir -p packages/pkg-a packages/pkg-b
   cd packages/pkg-a
   pnpm init -y
   pnpm add lodash@4.17.15
   cd ../pkg-b
   pnpm init -y
   pnpm add lodash@4.17.21
   cd ../..
   

   At this point pnpm install will show a warning about conflicting lodash versions.

2. Add an overrides section to the root package.json to force lodash 4.17.21:

   {
     "name": "monorepo-demo",
     "private": true,
     "overrides": {
       "lodash": "4.17.21"
     }
   }
   

3. Re‑install dependencies:

   pnpm install
   

   Check that the overridden version is used:

   pnpm ls lodash
   

   You should see only lodash@4.17.21 listed for both pkg-a and pkg-b. Inspect pnpm-lock.yaml; the lodash entry will resolve to 4.17.21 and the lockfile will contain no duplicate lodash entries.

4. Verify that your code works with the forced version (e.g., run tests or import lodash in a small script). If any tests fail, the override may be incompatible with a package that relied on features removed or changed between 4.17.15 and 4.17.21.

Trade‑offs and limitations

• Tool‑specific: Overrides only affect pnpm. If collaborators use npm or Yarn, they may still resolve different versions unless they also define similar overrides.

• Risk of breakage: Forcing a version can introduce API mismatches. Always run your test suite after adding or changing an override.

• Transitive scoping: You can target a nested dependency with syntax like some-package@^2/other-dep, but overly specific paths can become fragile if the intermediate package changes its internal structure.

Practical verification steps

1. Run pnpm ls <package> to confirm a single version appears for all workspaces.
2. Check pnpm-lock.yaml for the overridden version and the absence of duplicate entries.
3. Execute your project’s test suite or a small integration script that uses the dependency.
4. If you need to ensure other tools behave the same, add equivalent resolutions (Yarn) or overrides (npm 8+) to their lockfiles and repeat the verification.

Closing

Using pnpm overrides is a straightforward way to enforce a single dependency version across a monorepo, reducing duplication and simplifying version conflicts. Start by identifying the problematic package, add an override to the root package.json, reinstall, and verify with pnpm ls and your test suite. Keep an eye on compatibility risks and remember that the effect is limited to pnpm unless you propagate similar constraints to other package managers.