pnpm

Performant npm

pnpm is a fast implementation of npm install. It is loosely based off ied.

Install

Install it via npm.

npm install -g pnpm.js

Use pnpm in place of npm. It overrides pnpm i and pnpm install—all other commands will passthru to npm.

pnpm install lodash

Custom registries

pnpm follows whatever is configured as npm registries. To use a custom registry, use npm config:

# updates ~/.npmrc
npm config set registry http://npmjs.eu

Or to use it for just one command, use environment variables:

env npm_registry=http://npmjs.eu pnpm install

Private registries are supported, as well.

npm config set @mycompany:registry https://npm.mycompany.com
pnpm install @mycompany/foo

Preview release

pnpm will stay in <1.0.0 until it's achieved feature parity with npm install.

• pnpm install
  • npm packages
  • GitHub-hosted packages (npm i rstacruz/scourjs)
  • @scoped packages (npm i @rstacruz/tap-spec)
  • tarball release packages (npm i http://foo.com/tar.tgz)
  • compiled packages (npm i node-sass)
  • bundled dependencies (npm i fsevents@1.0.6)
  • optional dependencies (npm i escodegen@1.8.0 wants source-map@~0.2.0)
  • install from packages
  • file packages (npm i file:../path)
  • bin executables
  • --global installs
  • --save et al
• pnpm uninstall
• pnpm ls

Design

pnpm maintains a flat storage of all your dependencies in node_modules/.store. They are then symlinked whereever they're needed. This is like npm@2's recursive module handling (without the disk space bloat), and like npm@3s flat dependency tree (except with each module being predictably atomic). To illustrate, an installation of chalk@1.1.1 may look like this:

.
└─ node_modules/
   ├─ .store/
   │  ├─ chalk@1.1.1/
   │  │  └─ node_modules/
   │  │     ├─ ansi-styles      -> ../../ansi-styles@2.1.0/_
   │  │     ├─ has-ansi         -> ../../has-ansi@2.0.0/_
   │  │     └─ supports-color   -> ../../supports-color@2.0.0/_
   │  ├─ ansi-styles@2.1.0/
   │  │  ├─ _/
   │  │  └─ node_modules/
   │  ├─ has-ansi@2.0.0/
   │  │  ├─ _/
   │  │  └─ node_modules/
   │  └─ supports-color@2.0.0/
   │     ├─ _/
   │     └─ node_modules/
   └─ chalk                     -> .store/chalk@1.1.1/_

The intermediate _ directories are needed to hide node_modules from npm utilities like npm ls, npm prune, npm shrinkwrap and so on. The name _ is chosen because it helps make stack traces readable.

Benchmark

time npm i babel-preset-es2015 browserify chalk debug minimist mkdirp
    66.15 real        15.60 user         3.54 sys

time pnpm i babel-preset-es2015 browserify chalk debug minimist mkdirp
    11.04 real         6.85 user         2.85 sys

Prior art

ied is built on a very similar premise. pnpm takes huge inspiration from ied.

Unlike ied, however:

• pnpm will eventually be made to support a globally-shared store so you can keep all your npm modules in one place. With this goal in mind, pnpm also doesn't care much about npm@3's flat dependency tree style.
• pnpm also supports circular dependencies.
• pnpm aims to achieve compatibility with npm utilities (eg, shrinkwrap), and so deviates from ied's store schema (see § Design).

Will pnpm replace npm?

No! pnpm is not a replacement for npm; rather, think of it as a supplement to npm.

It's simply a rewrite of the npm install command that uses an alternate way to store your modules. It won't reimplement other things npm is used for (publishing, node_modules management, and so on).

Limitations

• Windows is not supported (yet).
• npm@3-style flattened dependency trees are not supported (yet).
• You can't install from shrinkwrap (yet).
• Things not ticked off in the to do list are obviously not feature-complete.

Got an idea for workarounds for these issues? Share them.

Thanks

pnpm © 2016+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz