When should I choose pnpm over npm for a monorepo with shared internal packages?

[Suzukijs]

🏷️ Discussion Type

Question

Body

Hi, I'm setting up a monorepo with 4–5 packages that share internal dependencies (a shared utils package used by multiple apps). I've read that pnpm uses a content-addressable store and symlinked node_modules, which saves disk space and improves install speed.

My specific concerns are:

1. Hoisting behavior: npm hoists all dependencies to the root node_modules, which can cause phantom dependency issues. Does pnpm's strict linking fully prevent this, or are there edge cases?
2. Workspace protocol: How does workspace:* in pnpm compare to npm's workspaces field for resolving internal packages during development vs. publishing?
3. Compatibility: Are there known tool incompatibilities with pnpm's non-flat node_modules structure (certain Webpack or Jest configs that assume hoisted paths)?

I'm not concerned about lockfile portability since the whole team would migrate together.

Is pnpm's stricter dependency isolation worth the migration cost for this use case, or does npm's workspace support cover the same ground adequately now?

[RAAJK20Pro]

For a monorepo with shared internal packages, pnpm is usually the stronger choice once dependency isolation and workspace correctness start mattering more than maximum ecosystem compatibility.

Regarding your specific concerns:

1. Phantom dependencies
   pnpm’s strict symlinked structure does prevent many phantom dependency cases that npm’s hoisting can accidentally hide. In practice, this catches undeclared dependencies much earlier during development/CI.

It is not mathematically impossible to still create edge cases (especially with custom tooling or incorrect peer dependency setups), but pnpm is significantly stricter and more deterministic than classic npm hoisting.

2. Workspace protocol (workspace:)
   This is one of pnpm’s biggest advantages in monorepos.

Using:

"my-shared-lib": "workspace:*"

[blaze0089]

---

Great question and you've clearly done your research already so let me get straight to the specific things you asked about since the previous answer got cut off.

Phantom dependencies — pnpm's strict linking prevents this in the vast majority of real world cases. Each package can only access what it explicitly declares in its own package.json, full stop. The edge cases that do slip through are usually packages using dynamic require() with constructed paths, or native Node addons with unusual resolution logic. For a standard monorepo with a shared utils package those edge cases basically don't apply to you.

workspace: protocol — this is honestly where pnpm pulls the furthest ahead and it's the most underrated difference. When you use workspace:* during development it symlinks the actual local package so you get live changes instantly without rebuilding. When you run pnpm publish it automatically replaces workspace:* with the real semver version so your published packages are completely clean. npm workspaces don't do this automatic substitution at publish time which means you have to handle version replacement manually or bring in extra tooling. That alone saves a lot of headaches.

Compatibility — this is the one area worth actually thinking about before migrating. Tools that assume a flat node_modules can struggle. The most common ones you might hit:

Jest sometimes needs a small config tweak if it can't find packages:

// jest.config.js
moduleDirectories: ['node_modules', '<rootDir>/node_modules']

Webpack 4 and older can have issues but Webpack 5 handles pnpm's structure fine. Most modern tooling like Vite, Turbopack and tsup works without any changes at all.

For your specific setup — 4 to 5 packages with a shared utils is literally the textbook use case pnpm was designed for. The migration cost is low, the workspace:* publish behavior alone pays for it, and catching phantom dependency bugs during development rather than in production is genuinely valuable. npm workspaces have improved a lot but they still hoist everything and skip the publish time version substitution. For a team migrating together pnpm is the clear call here.

---

[Stewie-pixel]

You may consider pnpm because it is generally a better choice for a monorepo with several shared internal packages. Its dependency system is much stricter than npm’s traditional hoisting model. With npm, dependencies are often hoisted into the root node_modules, which means a package can accidentally use libraries it never declared in its own package.json.

Compatibility with pnpm has improved greatly in recent years, and most modern tooling such as TypeScript, Vite, Webpack 5, Jest, ESLint, Next.js, and Turborepo now works well with pnpm. However, some older tools and plugins still assume a flat node_modules structure and may require small configuration changes, especially certain Jest setups or React Native projects. For a standard web or TypeScript monorepo, these issues are relatively uncommon today.

For your use case, the migration is usually worth it because pnpm gives better dependency correctness, faster installs, lower disk usage, and cleaner separation between packages. npm workspaces are much more capable than they used to be and are perfectly usable for smaller monorepos, but pnpm still provides stronger guarantees and a better developer experience when managing multiple interconnected packages.

To start a pnpm monorepo, you would first install pnpm globally using:

npm install -g pnpm

Then create and initialize the repository:

mkdir my-monorepo
cd my-monorepo
pnpm init

Next, create a pnpm-workspace.yaml file:

packages:
  - "apps/*"
  - "packages/*"

You can then create your apps and shared packages:

mkdir -p apps/web
mkdir -p packages/utils

Initialize each package:

cd apps/web && pnpm init
cd ../../packages/utils && pnpm init

To connect an internal package, add this dependency inside apps/web/package.json:

{
  "dependencies": {
    "@repo/utils": "workspace:*"
  }
}

Finally, install everything from the repository root with:

pnpm install

After setup, you can run commands across the workspace or target specific packages using filters, which makes managing larger monorepos much easier.

[Suzukijs]

Thanks for your reply, @ALL. I think i have the right answer now

[saleenbefd-wq]

__

[rohitpatil9121]

For a monorepo with shared internal packages, pnpm is generally worth it in my experience.

• pnpm’s strict node_modules layout does prevent most phantom dependency issues that npm hoisting can hide. It’s one of the biggest advantages for long-term monorepo health.
• workspace:* is also cleaner and more explicit than npm’s workspace linking. It guarantees local resolution during development and prevents accidentally pulling registry versions.
• Compatibility is much better now than it used to be. Most modern tools (Vite, Next.js, Jest, Webpack, Turbo, etc.) work fine. The remaining issues are usually older tooling that assumes a flat hoisted structure or hardcodes node_modules traversal.

npm workspaces have improved a lot, but npm still behaves more permissively. If your repo is small and the team values simplicity over strictness, npm is adequate. But if you want stronger dependency boundaries and fewer “works on my machine” problems as the repo grows, pnpm is usually the better long-term choice.