diff --git a/README.md b/README.md index 67864d1e96..5fca5a80d0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # pnpm + + > **P**erformant **npm** pnpm is a fast implementation of `npm install`. It is loosely based off [ied]. @@ -25,45 +27,11 @@ pnpm install lodash ## Custom registries -pnpm follows whatever is configured as npm registries. To use a custom registry, use `npm config`: - -```sh -# 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. - -```sh -npm config set @mycompany:registry https://npm.mycompany.com -pnpm install @mycompany/foo -``` +pnpm uses whatever npm's configured to use as its registry. See: [custom registries](docs/custom-registries.md). ## Preview release -`pnpm` will stay in `<1.0.0` until it's achieved feature parity with `npm install`. - -- [ ] `pnpm install` - - [x] npm packages - - [x] install from packages (`npm i`) - - [x] @scoped packages (`npm i @rstacruz/tap-spec`) - - [x] tarball release packages (`npm i http://foo.com/tar.tgz`) - - [x] compiled packages (`npm i node-sass`) - - [x] bundled dependencies (`npm i fsevents@1.0.6`) - - [ ] git-hosted packages (`npm i rstacruz/scourjs`) - - [ ] optional dependencies (`npm i escodegen@1.8.0` wants `source-map@~0.2.0`) - - [ ] file packages (`npm i file:../path`) - - [x] bin executables - - [ ] `--global` installs - - [x] `--save` (et al) -- [ ] `pnpm uninstall` -- [x] `pnpm ls` +`pnpm` will stay in `<1.0.0` until it's achieved feature parity with `npm install`. See [roadmap](docs/roadmap.md) for details. ## Design @@ -102,34 +70,8 @@ time pnpm i babel-preset-es2015 browserify chalk debug minimist mkdirp ## 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](#design)). - -[ied]: https://github.com/alexanderGugel/ied - -## 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 fully supported](https://github.com/rstacruz/pnpm/issues/6) (yet). -- You can't install from [shrinkwrap][] (yet). -- Things not ticked off in the [to do list](#preview-release) are obviously not feature-complete. - -Got an idea for workarounds for these issues? [Share them.](https://github.com/rstacruz/pnpm/issues/new) - -[shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap -[npm ls]: https://docs.npmjs.com/cli/ls -[npm prune]: https://docs.npmjs.com/cli/prune -[npm dedupe]: https://docs.npmjs.com/cli/dedupe +* [Compared to ied](docs/vs-npm.md) +* [Compared to npm](docs/vs-npm.md) ## Thanks diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..a66231978f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Table of contents + +* [pnpm](../README.md) +* Features + * [Custom registries](custom-registries.md) + * [Roadmap](roadmap.md) +* Comparison + * [npm](vs-npm.md) + * [ied](vs-ied.md) diff --git a/docs/custom-registries.md b/docs/custom-registries.md new file mode 100644 index 0000000000..44ee49d194 --- /dev/null +++ b/docs/custom-registries.md @@ -0,0 +1,21 @@ +# Custom registries + +pnpm follows whatever is configured as npm registries. To use a custom registry, use `npm config`: + +```sh +# 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. + +```sh +npm config set @mycompany:registry https://npm.mycompany.com +pnpm install @mycompany/foo +``` diff --git a/docs/docpress.json b/docs/docpress.json new file mode 100644 index 0000000000..5598d4bb95 --- /dev/null +++ b/docs/docpress.json @@ -0,0 +1,16 @@ +{ + "github": "rstacruz/pnpm", + "css": [ + "http://ricostacruz.com/docpress-rsc/style.css" + ], + "markdown": { + "typographer": true, + "plugins": { + "decorate": {} + } + }, + "googleAnalytics": { + "id": "UA-20473929-1", + "domain": "ricostacruz.com" + } +} diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000000..7b286030aa --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,19 @@ +# Roadmap + +`pnpm` will stay in `<1.0.0` until it's achieved feature parity with `npm install`. + +- [ ] `pnpm install` + - [x] npm packages + - [x] install from packages (`npm i`) + - [x] @scoped packages (`npm i @rstacruz/tap-spec`) + - [x] tarball release packages (`npm i http://foo.com/tar.tgz`) + - [x] compiled packages (`npm i node-sass`) + - [x] bundled dependencies (`npm i fsevents@1.0.6`) + - [ ] git-hosted packages (`npm i rstacruz/scourjs`) + - [ ] optional dependencies (`npm i escodegen@1.8.0` wants `source-map@~0.2.0`) + - [ ] file packages (`npm i file:../path`) + - [x] bin executables + - [ ] `--global` installs + - [x] `--save` (et al) +- [ ] `pnpm uninstall` +- [x] `pnpm ls` diff --git a/docs/vs-ied.md b/docs/vs-ied.md new file mode 100644 index 0000000000..5796926ce2 --- /dev/null +++ b/docs/vs-ied.md @@ -0,0 +1,10 @@ +# Ied + +[ied][] is built on a very similar premise. `pnpm` takes huge inspiration from ied. + +Unlike ied, however: + +- pnpm aims to achieve compatibility with npm utilities (eg, shrinkwrap), and so deviates from ied's store schema (see [§ Design](#design)). +- pnpm has a different (but still very similar) store layout than ied. + +[ied]: https://github.com/alexanderGugel/ied diff --git a/docs/vs-npm.md b/docs/vs-npm.md new file mode 100644 index 0000000000..6120425c82 --- /dev/null +++ b/docs/vs-npm.md @@ -0,0 +1,39 @@ +# npm + +pnpm is made as a more performance + +## Why is npm2 faster than npm3? + +_(This article is a stub. you can help by expanding it.)_ + +## Why is pnpm faster than npm? + +npm performs its action in stages. That is, it performs one stage for all dependencies in the tree, then moves onto the next stage. In general, these are: + +- Resolving: get package data and what dependencies it has. (high requests, low bandwidth) +- Fetching: fetch module contents (low requests, high bandwidth) +- Building: build compiled modules (no network IO) + +On the other hand, pnpm will eagerly move onto the next stage for a module even if other modules are stuck in earlier stages. This allows you to pnpm to more efficiently manage network IO: for instance, it can build compiled modules in the background while resolutions/fetches are still happening. + +There's more to it than this, but this is one of the big reasons. + +## 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 fully supported](https://github.com/rstacruz/pnpm/issues/6) (yet). +- You can't install from [shrinkwrap][] (yet). +- Things not ticked off in the [to do list](../README.md#preview-release) are obviously not feature-complete. + +Got an idea for workarounds for these issues? [Share them.](https://github.com/rstacruz/pnpm/issues/new) + +[shrinkwrap]: https://docs.npmjs.com/cli/shrinkwrap +[npm ls]: https://docs.npmjs.com/cli/ls +[npm prune]: https://docs.npmjs.com/cli/prune +[npm dedupe]: https://docs.npmjs.com/cli/dedupe + diff --git a/test/index.js b/test/index.js index c009fa982c..406a48f698 100644 --- a/test/index.js +++ b/test/index.js @@ -142,7 +142,7 @@ test('tarballs (is-array-1.0.1.tgz)', function (t) { stat = fs.statSync( join(process.cwd(), 'node_modules', '.store', - 'is-array-1.0.1@a83102a9c117983e6ff4d85311fb322231abe3d6')) + 'is-array-1.0.1#a83102a9c117983e6ff4d85311fb322231abe3d6')) t.ok(stat.isDirectory(), 'stored in the proper location') t.end() }, t.end)