The Case for pnpm Over npm or Yarn
Get to know this lesser-known JavaScript package manager
pnpm is a package manager for JavaScript, like npm and yarn. I personally feel that pnpm is less known than it should be. According to the README in the repository, pnpm is:
• Fast. As fast as npm and Yarn.
• Efficient. One version of a package is saved only ever once on a disk.
• Strict. A package can access only dependencies that are specified in its
package.json.• Deterministic. Has a lockfile called
pnpm-lock.yaml.• Works everywhere. Works on Windows, Linux and OS X.
This writing shares some of my learnings from migrating a monorepo (managed by a Yarn workspace + Lerna) that houses 60+ packages to pnpm. To understand more about why pnpm can be a good solution for your project, let’s start with a quiz.
Quiz
Imagine you’re starting a new JavaScript project. Like most people, you install your dependencies with npm or Yarn. Let’s use npm for this example. Your project needs Express, so you do:
npm install -g expressDependencies installed!
Let’s say Express has a dependency package called debug.
How does your node_modules look now?
Try thinking about it for a few seconds …
.
.
.
.
.
Done?
If you answered A, you probably think that’s just how dependencies are supposed to work.
But if you try this with npm or Yarn, you’d find the actual answer is B, and this is a problem.
Why’s This a Problem?
With the structure shown in B, our code now can require('debug'), even though we don’t depend on it explicitly in our package.json.
Think about what will happen if:
- Express updates their
debugdependency with breaking changes. - Express decided to not depend on
debuganymore.
In both cases, our code will now fail because it has an implicit dependency to debug.
In the correct structure, our code will never have access to debug. This is because of the way Node.js find stuffs inside node_modules.
Why Did npm Decide to Do This Then?
npm actually implemented structure A above before npm3, but there were some issues with it.
Duplications
If we add debug as our project dependency, we could have two different copies of debug.
Issues with this:
- Duplicates in our disk
- Possible duplicates in our bundles
- Some packages break when there are duplicates (e.g., React)
Long-nested directories
Some operating systems can’t handle long directories well.
Since version 3, npm has started to use flattened node_modules. You can read more about this here.
Why’s This a Problem? (Continued)
We already established that having implicit dependencies isn’t ideal. If you work with a sizable monorepo, then the problem is even worse. It’ll be harder to trace where the actual dependencies a project uses came from.
Duplications are also an issue. Although Yarn does hoistings to optimise disk-space usage, it unexpectedly fails in some cases.
How pnpm Solves These
pnpm uses hard links and symlinks to achieve a semistrict node_modules structure and also to make sure only one version of a module is ever saved on a disk.
Let’s say we execute pnpm install express into our project. This is how our node_modules look like:
Notice that our code has no way to access debug because it’s not directly under the root node_modules directory.
pnpm creates a special .pnpm directory that contains all the modules’ hard links. Under express/4.0.0, there’s the express module, which is a hard link to the global pnpm-store, and a debug symlink to the debug hard link, which also links to the global pnpm-store.
The global pnpm-store has a roughly similar structure. The actual package we install using pnpm is stored here. It’s normally saved under ~/.pnpm-store.
Huh, Does It Work With Every Package on the npm Registry?
Unfortunately, if you’re moving from Yarn/npm to pnpm, some packages might not work. Most of the time, this is caused by missing dependencies in the package’s package.json file.
Let’s use antd-table-infinity, for example. The package has no dependencies to antd but has some code that imports from antd. The package is also not bundling antd with it before being published. In most cases, when you’re using this package, you probably already also have antd installed. Then, the flattened node_modules structure allows this package to find antd. With pnpm, this package wouldn’t be able to find antd anymore and would fail.
Fortunately, pnpm provides hooks so we can resolve this kind of issue on our end. We can manually add antd as antd-table-infinity’s peerDependency using this simple hook.
How Does pnpm Benefit Us?
The two main benefits from pnpm, in my opinion, are:
No duplicates
- There can only be one version of package on your machine
- Saves disk space, no matter how many JS projects you have on your machine
- No more issues with a duplicate React
Strict
- No accidental access to nondependencies
- More stable, more consistent, and more predictable
- Avoid silly bugs
No duplicates mean no matter how many projects in your machine that depend on, let’s say, Electron, only one copy of each version of Electron will exist on your machine. It also work great for monorepos. No duplicates help in reducing the size of your monorepo on your disk. The strictness helps in catching hard-to-understand bugs earlier.
If you’re moving your project from npm or Yarn to pnpm, chances are you’ll find some unable to resolve module "some-module" errors. Your project might have worked previously because of the flattened node_modules structure, but will fail under the stricter structure — it’s a good thing if you’re aiming for long-term maintainability!
Summary
To summarise, pnpm is strict and helps us save disk space. The strictness makes things more predictable and catches bugs earlier. Whether that’s an important thing for you is up to you to decide. If you’re working with a large-scale monorepo, I highly recommend checking pnpm out.
This writing only covers some of what pnpm has to offer. Hopefully, you find it useful! More resources about pnpm can be found below. If you haven’t read through them yet, it’ll be worth it.
