A few weeks ago nikoladev suggested to implement autompletion in pnpm. After a brief investigation, I have found a brilliant tool that helps with autocompletion of CLI apps written in Node.js. This tool is called tabtab and is currently not maintained, so I forked it and added autocompletions to pnpm👌.

To set up autocompletion, just update pnpm to v4.9 and run pnpm install-completion.

Let’s see what you can do with it.

Type pnpm <tab-tab> and see all the available commands:

Type pnpm remove <tab-tab> and see the list of dependencies currently installed. This also works with pnpm update and pnpm outdated.

Type pnpm --filter <tab-tab> and see the list of projects in the workspace:

Type pnpm run <tab-tab> and see the list of available scripts:

Type any command, type tab-tab and see the list of supported options:

Type an option and see the possible values:

And these are just a few examples! Happy tabbing😃

In a future version of pnpm we will also add descriptions to completions😍

pnpm v4.9 comes with command completion! was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Both pnpm (as of v2.17) and Yarn (as of v1.12) support fast, concurrent installations in monorepos. However, there is a big difference between how they store dependencies in monorepos. Yarn tries to hoist all dependencies from all workspace packages into the root node_modules of the monorepo, which means that packages have access to dependencies of other packages in the workspace. This is described in the Yarn docs:

Be careful when publishing packages in a workspace. If you are preparing your next release and you decided to use a new dependency but forgot to declare it in the package.json file, your tests might still pass locally if another package already downloaded that dependency into the workspace root. However, it will be broken for consumers that pull it from a registry, since the dependency list is now incomplete so they have no way to download the new dependency. Currently, there is no way to throw a warning in this scenario.

Like Yarn, pnpm hoists all packages to the root. However, pnpm stores all dependencies in a hidden folder and only links the direct dependencies of every package into their node_modules.

Let’s see how Yarn and pnpm work on a simple example:

• there is a small monorepo with two packages: foo and bar
• foo has is-negative@1.0.0 as a dependency
• bar has is-positive@1.0.0 as a dependency

Yarn in action

To make this repo work with Yarn, there should be a package.json in the root of the repo with the following content:

{
 "private": true,
 "workspaces": ["foo", "bar"]
}

To install all dependencies of all workspace packages, you should run yarn install.

See results here

In this case, Yarn will create a single node_modules in the root of the repo with both is-negative and is-positive. It means that both foo and bar will have access to the dependencies of each other.

pnpm in action

To make pnpm install dependencies in this repo, you’ll need to create a pnpm-workspace.yaml in the root of the repo (it can be empty) and a .npmrc file with the following content:

shared-workspace-shrinkwrap = true
link-workspace-packages = true

To install all dependencies of all workspace packages with pnpm, you should run pnpm multi install (or just pnpm m i).

See results here

Like Yarn, pnpm creates a node_modules in the root of the repo. However, if you open that folder, you'll see that all directories and files are hidden there:

node_modules
+ .registry.npmjs.org
+ .modules.yaml
+ .shrinkwrap.yaml

This node_modules stores all the dependencies but they are hidden in .registry.npmjs.org. Node's resolution algorithm will not find them.

Now if you check the directory of bar, you’ll see a node_modules there as well, with a single symlink called is-negative. This symlink is pointing at ../../node_modules/.registry.npmjs.org/is-negative/1.0.0/node_modules/is-negative. Likewise, there is a symlink to is-positive in the node_modules directory of foo. So foo is able to resolve only is-positive and bar is only able to resolve is-negative 🎉😊

As you can see, pnpm is strict not only when used with a single package.json but also in a multi-package repository.

pnpm vs Yarn: monorepo node_modules was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Everyone heard about Lerna, which is “A tool for managing JavaScript projects with multiple packages.” A lot fewer devs heard about pnpm, which is a fast, disk space efficient package manager for JavaScript. Both Lerna and pnpm try to improve tooling for multi-package repositories (MPR). For Lerna it was the reason for creation. For pnpm, MPR support is a nice bonus feature that is implemented via a set of commands called recursive. Of course, there are many differences between how Lerna manages a multi-package repo vs pnpm. In this article, I want to compare one seemingly simple aspect: filtering.

Filtering in an MPR is important because, during development, changes are mainly made inside one or two packages. It wouldn’t make sense to run commands on the whole repository if only a few packages were modified.

Filtering in Lerna

Filtering in Lerna (as of v3.2.1) is achieved by the following flags:

• scope - Include only packages with names matching the given glob.
• include-filtered-dependents - Include all transitive dependents when running a command regardless of --scope, --ignore, or --since.
• include-filtered-dependencies - Include all transitive dependencies when running a command regardless of --scope, --ignore, or --since.
• ignore - Exclude packages with names matching the given glob.
• private - Include private packages. Pass --no-private to exclude private packages.
• since - Only include packages that have been updated since the specified [ref]. If no ref is passed, it defaults to the most recent tag.

These flags make filtering in Lerna quite powerful. However, they are pretty hard to type. Let’s say you downloaded a repository and want to work only on login-page component. You'd want to run installation for login-pageand any of its dependencies:

lerna bootstrap --scope login-page --include-filtered-dependencies

Or maybe you changed a component called site-header and would like to run tests on all the dependent packages:

lerna run test --scope site-header --include-filtered-dependents

These flags are not only hard to type but also hard to remember and easy to mix up.

Filtering in pnpm

Unlike Lerna, pnpm uses a special package selector syntax to restrict its commands. So instead of memorizing a set of long flag names, you should only remember a very easy-to-remember selector syntax.

As of version 2.15.0, these are the selectors that pnpm supports:

• <pattern> - Restricts the scope to package names matching the given pattern. E.g.: foo, @bar/*
• <pattern>... - Includes all direct and indirect dependencies of the matched packages. E.g.: foo...
• ...<pattern> - Includes all direct and indirect dependents of the matched packages. E.g.: ...foo, ...@bar/*
• ./<directory> - Includes all packages that are inside a given subdirectory. E.g.: ./components
• . - Includes all packages that are under the current working directory.

These filters may be specified either via the --filter flag or after a --at the end of the command.

Note: as of v2.15.0, filters after -- are not supported by run, exec, test

So if you want to bootstrap login-page and all of its dependencies, this is the way to do it with pnpm:

pnpm recursive install -- login-page...

And if you want to run tests of site-header and all of its dependents, use the ...<pattern> selector:

pnpm recursive test --filter ...site-header

Of course, you can combine as many selectors as you’d like:

pnpm recursive update -- ...site-header login-page... ./utils @style/*

The command above updates dependencies in:

• site-header
• dependents of site-header
• login-page
• dependencies of login-page
• all packages that are located in the utils directory
• all packages from the @style scope

pnpm might not have yet all the features that Lerna provides but for many users it might be enough already.

If you haven’t heard about pnpm yet, I recommend reading also Flat node_modules is not the only way which explains the unique node_modules structure created by pnpm.

Cheatsheet

pnpm vs Lerna: filtering in a multi-package repository was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

When I first started contributing to pnpm (around v0.15), this is how an installation was reported:

It wasn’t really useful but some users of pnpm liked it. They thought it was beautiful. But then as we started adding more features, we realized that it is very important to print the right amount of information in a nice readable format.

So let’s see how pnpm has evolved and how it reports in different scenarios as of v2.13.6.

Reporting installation in a single project

When you first install pnpm and you run pnpm install in a project, you'll see an output like this:

Unlike the old output, this one is very static and minimalistic but it contains a lot more useful information.

We see that:

1. one of the installed packages is deprecated
2. 117 new packages were added to node_modules
3. Installation slowed down a bit because the huge typescript tarball was being downloaded
4. 0 packages were available in the store, so all 117 packages were downloaded (pnpm saves one version of a package only ever once on a disk, so when a package is available in the store, it is just hard linked to the node_modules)
5. express@4.16.0 was added as a production dependency
6. a newer version of express is available in the registry
7. babel-preset-es2015@6.24.1 and typescript@3.0.1 were added as dev dependencies

Now lets update express to the latest version and see what we get:

1. 5 packages were removed from node_modules
2. 5 packages were added to node_modules
3. all 5 packages were downloaded from the registry
4. the newest express was added to the project

Reporting installation in a multi-package repository

pnpm has a set of commands for working with multi-package repositories (MPR). When installing dependencies in an MPR, the amount of information that is being processed is so big that printing all of it would just make an unreadable mess. In order to provide some basic information anyway, we came out with the concept of zoomed-out reporting. A zoomed-out reporting contains just the most important pieces of information.

Every package in the MPR is printed with the number of added/removed packages (inspired by Git):

Zoomed-out reporting also prints warnings (only warnings, no info messages):

When we came out with the concept of zoomed-out reporting for the recursive commands, we realized that there are other scenarios in which they are useful. For instance, when packages are linked in, it should be a mixture of zoomed-out and zoomed-in reporting. Packages that are linked in should be reported briefly and the package in the current working directory should be in focus:

Implementation details

Although the output seems minimalistic and simple, it is produced by a very complex system. pnpm consists of many components and many operations may happen in random order (this is one of the reasons pnpm is so fast). That is why reporting is performed by a specialized part of pnpm called “reporter” (code).

The reporter is a package that listens for logs, filters them, combines and forms an output from them. pnpm uses bole to pass the logs from the loggers to the reporter. This modularization is great because we can mock the logs and cover reporting with tests!

For printing the output to the console, we use ansi-diff. ansi-diff is great because it accepts "frames" of output and it updates only those parts of the console that are changed (and it is fast). Before we switched to ansi-diff, we used another popular library for updating the console output but it was doing the update with noticeable flickering.

P.S.

It is very hard to implement good CLI reporting. But good reporting allows developers to focus on the important things and possibly notice issues earlier.

Of course, pnpm’s reporting can improved a lot and we have many open issues in that area. Give pnpm a try and don’t hesitate to let us know if there are things that can be improved further.

The not fancy CLI output of pnpm was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

New users of pnpm frequently ask me about the weird structure of node_modules that pnpm creates. Why is it not flat? Where are all the sub-dependencies?

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 install express in one of them and pnpm install express in the other one. Here’s the top of what you get in the first directory’s node_modules:

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

So where are all the dependencies? There is only one folder in the node_modules called .registry.npmjs.org 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:

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/.registry.npmjs.org/express/4.16.3/node_modules/express

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

.registry.npmjs.org/<name>/<version>/node_modules/<name>

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.

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

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 /express/4.16.4/node_modules/express/node_modules/ but in /express/4.16.4/node_modules/:

All the dependencies of express are symlinks to appropriate directories in node_modules/.registry.npmjs.org/. 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.

If you’d like to try out pnpm, you can easily install it with npm: npm i -g pnpm. Then just run it instead of npm when you need to install something: pnpm install foo bar.

This article was originally posted on dev.to

Flat node_modules is not the only way was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Last week v2.0 of pnpm was released. It’s been almost a year since version 1.0 came out and we were busy implementing new features (v1 had 43 minor versions). So let’s see what awesome new features were added to pnpm since v1.0 and what are the breaking changes of v2.

So what’s new in pnpm since v1.0?

The store server

We added the store server to pnpm in v1.30. The store server is an app that can run in a separate process and handle all the store manipulations, reducing the number of tasks that pnpm install should do. With a store server, installations are faster and concurrent installations may run using the same store.

To start a store server, open a new tab in your console and run: pnpm server start. Or run installation with the --use-store-server flag: pnpm install --use-store-server. Or set the use-store-server config to true: pnpm set use-store-server true.

In the future, we plan to make installation with a running store server the default behavior. An always running store server will allow us to make really interesting features, like supporting a decentralized registry or keeping the store always hot.

The recursive commands

Everyone seems to like multi-package repositories lately but managing a multi-package repo is hard. In v1.24 of pnpm, we implemented our first recursive commands: pnpm recursive install and pnpm recursive update.

The pnpm recursive commands are implementations of the traditional pnpm commands for multi-package repositories. So for instance, the recursive install command is installing dependencies of every project in every subdirectory of the current working directory. Installation is performed concurrently by a single run of pnpm, so it is a lot faster than separate executions of pnpm for each package in the repo.

For a performance comparison of pnpm recursive with npm, you can read: Trying pnpm on the JustAnswer multi-package repository

As of now, there are 4 recursive commands: install/update/link/unlink. But soon there will be more because we converted the pnpm repo into a monorepo and we are actively dogfooding these commands.

The ability to create flat node_modules

As you may know, one of the great features of pnpm is that it creates a non-flat node_modules (you can read more about why this is a great feature in this article). However, we discovered that many packages in the ecosystem are broken, they use dependencies that are not declared in their package.json. When we see such packages, we try to submit pull requests and fix them. It takes time though, to discipline the ecosystem, that is why Emanuele Tamponi has implemented the shamefully-flatten config in version 1.34.

If your tooling has issues with pnpm, you can create a .npmrc file in the root of your project and set shamefully-flatten = true. But be aware that this is a hack and the right solution is to find the issue and fix it.

Headless installation

The most complex part of the installation is the resolution stage. After the resolution stage pnpm knows what should be installed where. But when a project already has a shrinkwrap.yaml, there is no need to repeat the resolution stage. That’s why we created a dedicated package (@pnpm/headless) that can install really fast but only using information from a shrinkwrap.yaml.

This is basically what the npm team did with the npm ci command but we did it with the regular install command. No actions are required to enjoy the speed improvement, headless installation will be used instead of regular installation when the shrinkwrap file is up-to-date with the package.json (for better results, you should always commit your shrinkwrap.yaml file).

Pro tip. You can use the --frozen-shrinkwrap flag to force a headless install. This flag is good for CI usage. But be aware, if you run pnpm install --frozen-shrinkwrap then an out-of-date lockfile will cause an installation failure.

And many more…

TBH, there were so many new features and improvements that I didn’t even mention them all, like side effects caching, better console reporting and new ways to import packages from the store. So just open our docs and read the descriptions of all the different commands… or just give pnpm a try on your project! (how to install pnpm)

Breaking changes

Node.js 4 is not supported anymore

End of life of Node.js 4 was on April 30th. This was the main reason we needed to make a major version bump. A lot of our dependencies started to drop Node.js 4 support months before its end of life, so we had to make the same as soon as possible.

Non-deprecated versions are preferred during resolution

This is a breaking change that npm v6 did as well. If a semver range can be resolved by a deprecated and non-deprecated version of a package, then the non-deprecated version is used even if it is a smaller version than the deprecated one.

Example. If a package depends on rimraf@2 and rimraf@2.0.1 is deprecated then rimraf@2.0.0 is going to be installed (if v2.0.0 is not deprecated).

`pnpm unlink` is an alias of `pnpm dislink`

In version 1, pnpm unlink was an alias of the pnpm uninstall command. However, we wanted a command that would remove a linked package created by pnpm link and install it from the registry, so we create pnpm dislink. In order to avoid confusion, now we’ve made pnpm unlink an alias of pnpm dislink.

Try it

Just install pnpm via npm: npm install -g pnpm. And use it instead of npm whenever you want to install something: pnpm i foo.

Also, you can read more info at the pnpm GitHub repo. You can follow pnpm on Twitter or ask for help at the pnpm Gitter Chat Room.

If you were afraid to use pnpm in the past because it was not used by big teams/projects then it is not the case anymore. Check out who’s using pnpm.

pnpm version 2 is out! was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

It happened to me a lot! One of the frequent issues is that I started to use a dev dependency but didn’t change it to a prod dependency. This is even a bigger issue when you use npm or Yarn because they create flat node_module. In a flat node_modules, your code has access even to sub-dependencies of your dev dependencies! The later cannot happen when you use pnpm because pnpm creates a strict, non-flat node_modules folder. However, even when you use pnpm, your code will have access to dev dependencies during development.

Workaround

This issue bothered me a lot and my first solution was to create a separate package for my tests. So there was a package.json file in the test/ folder that contained all the dependencies needed by tests. Test dependencies were installed to test/node_modules and they were not accessible by prod code.

However, there are also other issues that may be detected only after a package has been published:

• a file needed by the package is not added to the files field of package.json.
• installation lifecycle scripts fail
• bins are incorrectly declared
• the main file is not specified correctly

package-preview

So I created a package that helps to detect these issues during running the tests of your project: package-preview 🎉✨

package-preview packs your project and installs it the way it’s going to be installed as a dependency, so you can test the exact same package content that is going to be installed by Node.js package managers.

All you have to do is to install package-preview as a dev dependency:

pnpm i -D package-preview

…and run preview before running your tests

{
  "name": "awesome",
  "version": "1.0.0",
  "scripts": {
    "test": "preview && tape test.js"
  }
}

package-preview is going to create the preview version of your package and link it to your project's node_modules. So in your tests, you can require awesome and test the production version of your package:

// Instead of require('.')
const awesome = require('awesome')

assert(awesome() === 'Awesome stuff!')

P.S.

Under the hood, package-preview uses pnpm, so as a bonus, you will also catch errors that you would miss with npm/Yarn’s flat node_modules. If you did not yet try pnpm, check it out, you won’t be disappointed. It is fast, reliable and saves you lots of disk space!

Never ever forget to install a dependency was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why would we want to hook into `node_modules`?

When installing dependencies of a Node-project, the node_modules structure is 100% controlled by the package.json files of the dependencies (a.k.a. manifests). So if your project depends on foo@1.0.0 which depends on bar@2.0.0 then you’ll be going to have two dependencies installed in your node_modules. While you can change your project’s dependency set, you don’t have control over the manifests of your dependencies.

A typical dependency tree is huge and you have no ownership over the majority of your dependencies. Just analyze any of your dependencies at npm.anvaka.com.

What to do if there is a bug in one of the packages inside your node_modules? If the issue is in a root dependency, then you have 3 options:

1. find an alternative, more reliable package
2. submit a pull request (PR) that fixes the issue
3. create your own package and use it instead of the buggy one

The 2nd option seems to be the correct one and I encourage everyone to contribute as frequently as possible. However, submitting a PR doesn’t mean that your changes will be merged/published. Even if they will be merged and published, it won’t happen immediately, you might have to wait for years. Here are some frequent issues:

• the project is unmaintained/poorly maintained
• you did breaking changes and the author doesn’t like bumping major versions. The author will wait for several breaking changes to come in, before publishing a major version
• the author thinks the bug is not a bug

If the problematic package is a root dependency, then you can easily switch to another package or to your fork. The problem is match harder to solve if the package is a sub-dependency. In that case, your options are:

1. submit a PR that fixes the issue
2. submit many PRs to packages that depend on the buggy package

With hooks though, you can have a third option: create a fork and install it instead of the problematic package. So if you have foo@1.0.0 that depends on bar@2.0.0 you can have a hook that will override the dependency.

Let’s say there is a bug in bar@2.0.0 and you submitted a PR with a fix. However, the maintainer of bar is on vacation. You can use a hook to make pnpm install bar from your PR branch instead of bar@2.0.0 from the npm registry.

Why hooks are important for pnpm’s survival

Hooks are nice to have in any PM but for pnpm they are especially important. As you may know already, pnpm creates a strict symlinked node_modules structure. You can read more about it in:

pnpm’s strictness helps to avoid silly bugs

Although the node_modules structure created by pnpm is Node.js-compatible, many packages have bugs that show up only when installed via pnpm. As a consequence, pnpm has issues with some popular frameworks and tools.

Of course, we try to solve these issues via PRs (I want to give a shout out to aecz who managed to fix many such issues in Angular). But besides the usual issues, some of the maintainers are hostile and refuse to accept PRs just because they don’t like pnpm or believe that the flat node_modules created by npm/Yarn is a feature (it is not).

In the end, we have two options to fix the ecosystem for the strict pnpm:

1. make pnpm popular enough. In that case, authors of frameworks/toolings will be testing their product with pnpm as well as npm and Yarn.
2. make a hook system to temporarily substitute the buggy packages that don’t work with pnpm.

IMHO, the 1st scenario is pretty much impossible. pnpm can’t become popular without being a drop-in replacement for npm.

Real-life example

There is a popular package called resolve for resolving dependencies from node_modules (1,3K dependents, 765K downloads a day). Unfortunately for pnpm, resolve preserves symlinks when resolving modules. This is an issue on resolve’s end as Node.js does not preserve symlinks during resolution. I did a PR to fix this issue and now resolve from version 1.4 has an option to not preserve symlinks.

This does not solve the problem for pnpm though. We can’t submit PRs to the 1.3K dependent packages to update resolve and pass preserverSymlink: false to it. The lead maintainer of resolve agreed to switch the option’s default value in the next major version. So I hoped Greenkeeper would create the PRs for us and most of the packages would update resolve to version 2.

I created another PR with the breaking change but resolve’s maintainer wants to wait for more breaking changes before changing resolve to version 2.

I realized that we cannot change the world but we can change pnpm, so I released the readPackage hook. My changes to resolve are available via my fork on GitHub, so all we have to do is to tell pnpm to install resolve from the fork. This can be done by declaring the hook in a file called pnpmfile.js:

During installation, pnpm will pass every package.json to this hook first and use the version of the package.json returned by the hook. So it won’t matter on which version of resolve the package depends, my fork will be installed instead and the project will work fine with pnpm.

Summary

I did not describe all the use cases when the readPackage can be useful. It is a really powerful tool and I think we’ll learn how to use it smartly.

Also, I want to say thanks to Andrei Neculau, who convinced me that this hook-system was a good idea.

To make it a little bit interactive, check how many unresolved PRs you have on GitHub and post the number in the comments section. You can use this link to see all your open PRs.

Do you want to give pnpm a try?

Just install pnpm via npm: npm install -g pnpm. And use it instead of npm whenever you want to install something: pnpm i foo.

Also, you can read more info at the pnpm GitHub repo or pnpm.js.org. You can follow pnpm on Twitter or ask for help at the pnpm Gitter Chat Room.

This post was originally published on kochan.io

Why package managers need hook systems was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why only now? The initial commit to pnpm was made by Rico Sta. Cruz on Jan 27, 2016. It was based on the ideas of ied by Alexander Gugel with initial commit on Aug 6, 2015!

Unlike Yarn, which has decided to use the same node_modules structure that npm creates, pnpm uses a completely new approach (about which you can read more in this article). It was really hard to make a symlinked node_modules structure work with most of the existing npm packages! All the different problems that we have encountered and the dozens of breaking changes we had to make, deserves a post of its own. Finally, almost 2 years since the idea of a symlinked node_modules structure has born, we can tell with confidence: it is possible and it does work.

So what does version 1 mean?

Version 1 means that:

• The store structure that pnpm uses since version 0.70 is reliable enough and we are confident that there will be no need in breaking changes in its structure.
• The node_modules layout that pnpm creates works with most of the ecosystem.
  pnpm@1 also ships with an experimental node_modules layout that can be turned on with the independent-leaves config. The experimental layout boosts installation speed by 8% and works almost with all projects. However, we were not confident enough to make it the default yet.
• The format of the shrinkwrap.yaml file, which is pnpm’s lockfile, is good enough for being committed to VCS.
• When possible, pnpm@1 works the way npm@5 does.

You can rely on these things and they won’t get breaking changes in version 1.

What’s next?

Even faster! The goal is to make installations subsecond fast. So fast that it would run on every Git operation. Maybe one day it would be even integrated to Git?!

As of now, pnpm is faster than Yarn when installing with cold cache but may be a bit slower in different scenarios. For a detailed comparison of npm/pnpm/Yarn speed, see “Why I still don’t use Yarn”. However, there is no reason for pnpm to be slower than Yarn or npm. So we’ll have to find the issues and make pnpm faster.

Simpler codebase. pnpm is currently very hard to contribute to, so it will have to be split into separate packages. The first step will probably be separation of the installation engine.

PR. Although pnpm is public for a longer period of time than Yarn, it is far less popular. So more articles, more documentation, and more interesting tools will be created to promote pnpm. Let’s make our awesome list huge!

Try it

Just install pnpm via npm: npm install -g pnpm. And use it instead of npm whenever you want to install something: pnpm i foo.

Also, you can read more info at the pnpm GitHub repo. You can follow pnpm on Twitter or ask for help at the pnpm Gitter Chat Room.

pnpm version 1 is out! was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.

When using npm, you have access to packages that you don’t reference in your project’s package.json. This is possible because npm creates a flat node_modules folder.

Let me explain this by an example.

• create an empty project: mkdir project && npm init -y
• run npm install express --save
• go to the node_modules folder that was created
• run ls -1

You’ll get an output similar to this one:

accepts
array-flatten
content-disposition
content-type
cookie
cookie-signature
debug
depd
destroy
ee-first
encodeurl
escape-html
etag
express
finalhandler
forwarded
fresh
http-errors
inherits
ipaddr.js
media-typer
merge-descriptors
methods
mime
mime-db
mime-types
ms
negotiator
on-finished
parseurl
path-to-regexp
proxy-addr
qs
range-parser
send
serve-static
setprototypeof
statuses
type-is
unpipe
utils-merge
vary

As you can see, even though you installed only express, a lot more packages are available in the node_modules folder. Node.js doesn’t care what is in your package.json file, you will have access to all the packages that are in the root of node_modules. So you can start using all those packages without even installing them explicitly.

Let’s say you need debug in your project. You can start using it and forget to add it to package.json. Your project will work fine. You will commit your changes and publish it to production. It will work well even in production. However, after a few weeks or months, one of two things can very likely happen:

1. a new major version of debug with a new API can get published. Your code was written for debug@1 and it needs some updates to work with debug@2. You are safe until express uses debug@1 because debug@1 is installed to the root of node_modules. However, express can update its dependency in any moment, fix all usages of debug and publish a new patch (a patch, because express didn’t have any breaking changes). Next time you do npm install, express will be updated and debug@2 installed into the root of your node_modules. The project will break, even though you did not make any changes!
2. another possibility is that express stops using debug. It can just remove it from dependencies and publish a new version. When you’ll update express, your code will break because the debug package won’t be in node_modulesanymore.

Now imagine that your project is not a web app but a package used by many other people. If you don’t include a package used in code into the package.json, your package is a timed bomb. Do you remember left-pad? I can imagine a similar catastrophe happening in the future because of a forgotten dependency.

How does pnpm help with avoiding these type of bugs?

Unlike npm, pnpm does not try to move everything to the root of node_modules. If you remove the node_modules folder created by npm in the previous example and run pnpm install express, you’ll see that ls -1 will print only one symlink in the node_modules folder: express. No debug!

On next run, your app will immediately fail, because it won’t be able to find debug. Which is the way it should be! To fix the project, you’ll just run pnpm install debug and debug will be added to your package.json (pnpm saves packages to package.json by default, even when the --save parameter is not passed). With debug in your package.json, you can be sure that it will always be installed into node_modules and it will work with your code as expected.

pnpm gets a lot of issues opened because some packages/toolings don’t work. These issues are mostly happening because the packages/toolings have package.jsons that miss dependencies. Some developers even think that it is fine to not include dependencies in package.json because “it works with npm/yarn”. It is not OK! It might work today but it will break tomorrow.

You might not use pnpm. But please, publish valid packages. If you don’t use pnpm, use some tooling like dependency-check to validate your package before publishing it to the registry.

npm’s global style installation

A month later after publishing this article, I have found out that it is possible to avoid these kind of bugs with npm as well! It is not the default behavior but npm can install node_modules in a different layout, in which

Only your direct dependencies will show in node_modules and everything they depend on will be flattened in their node_modules folders.

To achieve this, just run npm with the --global-style option or change its value in the configs via npm c set global-style true.

Do you want to give pnpm a try?

Just install pnpm via npm: npm install -g pnpm. And use it instead of npm whenever you want to install something: pnpm i foo.

Also you can read more info at the pnpm GitHub repo or pnpm.js.org. You can follow pnpm on Twitter or ask for help at the pnpm Gitter Chat Room.

(This article was originally posted on https://www.kochan.io/nodejs/pnpms-strictness-helps-to-avoid-silly-bugs.html)

pnpm’s strictness helps to avoid silly bugs was originally published in pnpm on Medium, where people are continuing the conversation by highlighting and responding to this story.