We are migrating our repositories to use pnpm in place of yarn. This page aims to explain the reasoning behind the change and provide guidance on day-to-day work with the new package manager.

Why are we doing this?

Performance. pnpm tends to resolve and install packages faster than yarn. While the deduplicate command is much slower than yarn, we don’t run it unless packages are changed.

Checkout task with Yarn

Checkout task with pnpm

Explicit dependencies. Unlike yarn, pnpm requires all dependencies to be explicitly listed in package.json. This makes it easier to move projects between directories or repositories, and can help prevent errors in published packages.
Simpler releases. We no longer need to go through all the private packages during lerna version, but we can skip them. This is because workspace projects don’t use explicit version numbers in references between each other but a pnpm-specific protocol (for example "@mui/base": "workspace:*").
Many popular open-source projects use it: https://pnpm.io/users

What are the main differences to Yarn?

Yarn hoists all packages to the root node_modules (so dependencies of every workspace project are available to all workspace projects).
Terminology: in Yarn, a workspace is an individual package in a monorepo. In pnpm, the monorepo itself is a workspace.

Installation

Follow the guidelines at https://pnpm.io/installation. The Corepack method seems to be working well despite being experimental.

After installation, remove the node_modules directory and run pnpm i to create the pnpm package store.

Useful commands

Yarn	pnpm
`yarn`, `yarn install`	`pnpm i`, `pnpm install`	Installs dependencies. Note that (similarly to npm), you can’t run just `pnpm` to do this.
`yarn add`, `yarn add --dev`	`pnpm add`,
`pnpm add -D`	Adds a dependency to the current project’s package.json. Running this in the root will trigger a warning (as having dependencies in a root package.json is discouraged), that can be dismissed with a `-w` flag.
`yarn workspace X Y`	`pnpm --filter X Y`	Runs a command Y from a specific package X. In pnpm you can provide a filter matching multiple packages (https://pnpm.io/filtering).
`yarn X`, `yarn run X`	`pnpm X`, `pnpm run X`	Runs a script from the current package.json. It’s also possible to run a script from all the workspace projects that define it with the `-r` flag (for example `pnpm build -r` will run the `build` script from all workspace projects, not the root one).
`yarn test`	`pnpm test`, `pnpm t`	Runs the script named “test”.
Note: pnpm defines the `t` alias for this command that conflicts with our “t” script (the test CLI). Executing `pnpm t` won’t run the “t” script but the “test” one. To run the test CLI, execute `pnpm run t`.
	`pnpm patch`	Lets you patch broken dependencies (e.g., while waiting for the maintainers to merge a PR). See https://pnpm.io/cli/patch for more details.