(the above illustration was generated by Midjourney. The tiger symolizes the year of the tiger)

Usage​

Download Stats​

My goal this year was to beat Lerna by the number of downloads. We were able to achieve this goal in August:

pnpm was downloaded more than 5 times more in 2022 than in 2021:

Docs visits​

We collect some unpersonalized stats from our docs using Google Analytics. In 2022, sometimes we had more than 20,000 unique visitors a week. This is 10 times more than in 2021!

GitHub stars​

Our main GitHub repository received almost +7,000 stars this year.

Our contributors​

We had a lot of new and active contributors this year. These are the people the merge at least one PR in 2022:

• Zoltan Kochan
• chlorine
• await-ovo
• Brandon Cheng
• Dominic Elm
• MCMXC
• 那里好脏不可以
• Homyee King
• Shinobu Hayashi
• Black-Hole
• Kenrick
• Weyert de Boer
• Glen Whitney
• Cheng
• zoomdong
• thinkhalo
• 子瞻 Luci
• spencer17x
• liuxingbaoyu
• 장지훈
• Jon de la Motte
• Jack Works
• milahu
• David Collins
• nikoladev
• Igor Bezkrovnyi
• Lev Chelyadinov
• javier-garcia-meteologica

Feature Highlights​

Supporting a symlinkless hoisted node_modules (since v6.25.0)​

Right at the beginning of 2022, we have added support for the "traditional" hoisted (a.k.a flat node_modules). We use Yarn's hoisting algorithm to create a proper hoisted node_modules. This new setting has basically made pnpm compatible with all Node.js stack that are compatible with npm CLI.

To use the hoisted node_modules directory structure, use the node-linker=hoisted setting in an .npmrc file.

Side effects cache (since v7.0.0)​

Since v7, side-effect-cache is enabled by default, so dependencies that should be built are only built once on a machine. This improves installation speed by a lot in projects that have dependencies with build scripts.

Dependencies patching (since v7.4.0)​

The pnpm patch command have been added for patching dependencies in your node_modules.

Time-based resolution strategy (since v7.10.0)​

A new resolution mode was added to pnpm, which should make updating dependencies more secure. You can change the resolution mode with the resolution-mode setting.

Listing licenses of dependencies (since v7.17.0)​

You may now use the pnpm licenses list command to check the licenses of the installed packages.

Usage​

Download Stats​

My goal this year was to beat Bower by the number of downloads. We were able to achieve this goal in November:

pnpm was downloaded about 3 times more in 2021 than in 2020:

Docs visits​

We collect some unpersonalized stats from our docs using Google Analytics. In 2021, sometimes we had more than 2,000 unique visitors a week.

Most of our users are from the United States and China.

GitHub stars​

Our main GitHub repository received +5,000 stars this year.

New users​

Our biggest new user this year is Bytedance (the company behind TikTok).

Also, many great open-source projects started to use pnpm. Some switched to pnpm because of its great support of monorepos:

• Vue
• Vite
• and others

Some switched because they like how efficient, fast, and beautiful pnpm is:

• Autoprefixer
• PostCSS
• Browserslist

Feature Highlights​

New lockfile format (since v6.0.0)​

One of the first and most important changes this year was the new pnpm-lock.yaml format. This was a breaking change, so we had to release v6. But it was a success. The old lockfile was causing Git conflicts frequently. Since the new format was introduced, we did not receive any complaints about Git conflicts.

Managing Node.js versions (since v6.12.0)​

We shipped a new command (pnpm env) that allows to manage Node.js versions. So you may use pnpm instead of Node.js version managers like nvm or Volta.

Also, pnpm is shipped as a standalone executable, so you can run it even with no Node.js preinstalled on the system.

Injecting local dependencies (since v6.20.0)​

You may "inject" a local dependency. By default, local dependencies are symlinked to node_modules but with this new feature you may instruct pnpm to hard link the files of the package instead.

Improved reporting of peer dependency issues (since v6.24.0)​

Peer dependency issues used to be printed as plain text and it was hard to understand them. They are now all grouped and printed in a nice hierarchy structure.

The Competition​

Yarn​

Yarn added a pnpm linker in v3.1. So Yarn can create a similar node-modules directory structure to the one that pnpm creates.

Also, the Yarn team plans to implement a content-addressable storage to be more disk space efficient.

npm​

The npm team decided to also adopt the symlinked node-modules directory structure that pnpm uses (related RFC).

Others​

Bun written in Zig and Volt written in Rust both claim to be faster than npm/Yarn/pnpm. I did not benchmark these new package managers yet.

Future Plans​

Faster, better, best.

The default setup​

By default, pnpm v5 will create a semi-strict node_modules. Semi-strict means that your application will only be able to require packages that are added as dependencies to package.json (with a few exceptions). However, your dependencies will be able to access any packages.

The default configuration looks like this:

; All packages are hoisted to node_modules/.pnpm/node_modules
hoist-pattern[]=*

; All types are hoisted to the root in order to make TypeScript happy
public-hoist-pattern[]=*types*

; All ESLint-related packages are hoisted to the root as well
public-hoist-pattern[]=*eslint*

Plug'n'Play. The strictest configuration​

pnpm supports Yarn's Plug'n'Play since v5.9. With PnP, both your application and the dependencies of your application will have access only to their declared dependencies. This is even stricter then setting hoist=false because inside a monorepo, your application will not be able to access even the dependencies of the root project.

To use Plug'n'Play, set these settings:

node-linker=pnp
symlink=false

A strict, traditional modules directory​

If you are not ready to use PnP yet, you can still be strict and only allow packages to access their own dependencies by setting the hoist configuration to false:

hoist=false

However, if some of your dependencies are trying to access packages that they don't have in dependencies, you have two options:

1. Create a pnpmfile.js and use a hook to add the missing dependency to the package's manifest.

2. Add a pattern to the hoist-pattern setting. For instance, if the not found module is babel-core, add the following setting to .npmrc:

   hoist-pattern[]=babel-core
   

The worst case - hoisting to the root​

Some tools might not work even with the default configuration of pnpm, which hoists everything to the root of the virtual store and some packages to the root. In this case, you can hoist either everything or a subset of dependencies to the root of the modules directory.

Hoisting everything to the root of node_modules:

shamefully-hoist=true

Hoisting only packages that match a pattern:

public-hoist-pattern[]=babel-*

I am going to assume that readers of the article are already familiar with flat node_modules created by npm and Yarn. If you don't understand why npm 3 had to start using flat node_modules in v3, you can find some prehistory in Why should we use pnpm?.

So why is pnpm's node_modules unusual? Let's create two directories and run npm add express in one of them and pnpm add express in the other one. Here's the top of what you get in the first directory's node_modules:

.bin
accepts
array-flatten
body-parser
bytes
content-disposition
cookie-signature
cookie
debug
depd
destroy
ee-first
encodeurl
escape-html
etag
express

You can see the whole directory here.

And this is what you get in the node_modules created by pnpm:

.pnpm
.modules.yaml
express

You can check it here.

So where are all the dependencies? There is only one folder in the node_modules called .pnpm and a symlink called express. Well, we installed only express, so that is the only package that your application has to have access to

Read more about why pnpm's strictness is a good thing here

Let's see what is inside express:

▾ node_modules
  ▸ .pnpm
  ▾ express
    ▸ lib
      History.md
      index.js
      LICENSE
      package.json
      Readme.md
  .modules.yaml

express has no node_modules? Where are all the dependencies of express?

The trick is that express is just a symlink. When Node.js resolves dependencies, it uses their real locations, so it does not preserve symlinks. But where is the real location of express, you might ask?

Here: node_modules/.pnpm/express@4.17.1/node_modules/express.

OK, so now we know the purpose of the .pnpm/ folder. .pnpm/ stores all the packages in a flat folder structure, so every package can be found in a folder named by this pattern:

.pnpm/<name>@<version>/node_modules/<name>

We call it the virtual store directory.

This flat structure avoids the long path issues that were caused by the nested node_modules created by npm v2 but keeps packages isolated unlike the flat node_modules created by npm v3,4,5,6 or Yarn v1.

Now let's look into the real location of express:

  ▾ express
    ▸ lib
      History.md
      index.js
      LICENSE
      package.json
      Readme.md

Is it a scam? It still lacks node_modules! The second trick of pnpm's node_modules structure is that the dependencies of packages are on the same directory level on which the real location of the dependent package. So dependencies of express are not in .pnpm/express@4.17.1/node_modules/express/node_modules/ but in .pnpm/express@4.17.1/node_modules/:

▾ node_modules
  ▾ .pnpm
    ▸ accepts@1.3.5
    ▸ array-flatten@1.1.1
    ...
    ▾ express@4.16.3
      ▾ node_modules
        ▸ accepts
        ▸ array-flatten
        ▸ body-parser
        ▸ content-disposition
        ...
        ▸ etag
        ▾ express
          ▸ lib
            History.md
            index.js
            LICENSE
            package.json
            Readme.md

All the dependencies of express are symlinks to appropriate directories in node_modules/.pnpm/. Placing dependencies of express one level up allows avoiding circular symlinks.

So as you can see, even though pnpm's node_modules structure seems unusual at first:

1. it is completely Node.js compatible
2. packages are nicely grouped with their dependencies

The structure is a little bit more complex for packages with peer dependencies but the idea is the same: using symlinks to create a nesting with a flat directory structure.