Using pnpm Workspaces to Share Dependencies in a Monorepo

Why use pnpm workspaces

If you maintain multiple packages in a single repository and want them to share a common set of dependencies without duplicating them, enable pnpm workspaces. This creates a single logical project where each package’s node_modules is a symlink to a shared store under .pnpm, and compatible dependencies are hoisted to the root.

Configuration example

# pnpm-workspace.yaml (place at repository root)
packages:
  - 'packages/*'
  - 'services/*'

# packages/ui/package.json
name: ui
version: 1.0.0
dependencies:
  react: ^18.2.0

# services/api/package.json
name: api
version: 1.0.0
dependencies:
  express: ^4.18.2

Running the install

From the repository root, run:

pnpm install

You need read and write access to the repository directory; no special privileges are required. The command resolves dependencies, creates a .pnpm store, and symlinks each workspace’s node_modules to the appropriate folders.

What pnpm creates

Limits

• Requires pnpm version 6 or newer.
• Cannot coexist with npm or Yarn workspaces in the same repository.
• Hoisting only moves dependencies whose versions are compatible across all workspace packages; incompatible versions remain nested, which can lead to phantom dependencies if you rely on them without declaring them.

Common mistakes

• Omitting the packages array or using glob patterns that do not match your workspace folders.
• Committing the generated node_modules folder to version control.
• Assuming every dependency is hoisted; check the lockfile or run pnpm ls -r to see which packages remain nested.
• Setting shamefully-hoist=true in .npmrc unless you intentionally want all dependencies hoisted, as this can hide missing declarations.

Verification steps

1. Run pnpm install from the repository root.
2. List the workspace packages: pnpm ls -r. Verify each appears with its version and that dependencies are shown as linked.
3. Inspect the symlinks: ls -la node_modules. You should see entries like ui -> ../../.pnpm/ui@1.0.0/node_modules/ui.
4. Try to import a dependency that is declared only in one workspace from another workspace’s code. If the build fails, the dependency was not hoisted and must be added explicitly to the depending package’s package.json.

Rollback considerations

Since the operation creates symlinks and modifies node_modules and .pnpm, you can revert by deleting those folders and reinstalling, or by checking out a previous commit that does not contain the workspace configuration. No database or state outside the repository is changed.