pnpm

pnpm is a package manager built with an emphasis on monorepos. This makes it our preferred choice in a monorepo for a few specific reasons:

• Speed: pnpm can be up to two times faster than the other package managers.
• Correctness: Other package managers are more willing to sacrifice strictness when it comes to workspace dependency boundaries. In a pnpm repository, package hoisting is less forgiving.
• Disk space efficiency: Caching and deduplication in pnpm mean smaller project size on your hard drive.

Setting up workspaces

To create your workspaces, make a file in the root of your repository called pnpm-workspace.yaml and add the globs where your workspaces will be located:

packages:
  - apps/*
  - packages/*
  - tooling/*

packages:
  - apps/*
  - packages/*
  - tooling/*

packages:
  - apps/*
  - packages/*
  - tooling/*

packages:
  - apps/*
  - packages/*
  - tooling/*

Note that you pnpm will let you add nested workspaces using a /** double star syntax but Turborepo does not currently support this feature.

If you're using Turborepo, you'll also need to add a line to your root package.json:

{
  "name": "my-repo",
  "private": true,
  "scripts": { ... },
  "devDependencies": { ... },
  "packageManager": "pnpm@8.5.0"
}

{
  "name": "my-repo",
  "private": true,
  "scripts": { ... },
  "devDependencies": { ... },
  "packageManager": "pnpm@8.5.0"
}

{
  "name": "my-repo",
  "private": true,
  "scripts": { ... },
  "devDependencies": { ... },
  "packageManager": "pnpm@8.5.0"
}

{
  "name": "my-repo",
  "private": true,
  "scripts": { ... },
  "devDependencies": { ... },
  "packageManager": "pnpm@8.5.0"
}

Migrating to pnpm

If you're migrating to pnpm from a different package manager, you may find that your repository starts to throw errors about not being able to find dependencies in certain workspaces.

It is very unlikely that you've found a bug in pnpm. Rather, pnpm may be finding a bug in your code.

Because pnpm resolves dependencies more strictly, you might have to do some debugging to learn why your dependencies are not being resolved. Common reasons include:

• npm and yarn use an * to refer to workspace dependencies but pnpm uses workspace:*. Make sure your dependency follows the format "@repo/my-dep": "workspace:*.
• You're using a package in a workspace where it hasn't been installed. Because npm and yarn are more relaxed about module resolution, you can often use a package in a workspace where it is not explicitly installed into the workspace's package.json. Audit your dependency list to see if you need to install the package in the erroring workspace.

Tips and tricks

Bump an external package version in all workspaces

You'll often want to keep the same version of an external package consistent across your repository. For instance, you only have one version of React being used in your ui and web packages. Use this command to bump to the latest React version in all your workspaces:

pnpm -r up react@latest

pnpm -r up react@latest

pnpm -r up react@latest

pnpm -r up react@latest

You can change the package and version tag that you're targeting to your liking!

Figure out where a package is being installed

Package dependencies trees can be hard to debug. Sometimes, you just want to figure out what a package is in your repository in the first place.

pnpm why react

pnpm why react

pnpm why react

pnpm why react

This command will show you everywhere in your dependency tree where react is being brought in and why.