JSエコシステムぶらり探訪(3): npmとyarnとnode_modules

前回はNode.js単独での機能に焦点をあてて説明しましたが、Node.jsはnpm/yarnなどのパッケージ管理システムと組み合わせて使うことが想定されています。本稿ではライブラリの依存解決としての側面を中心に、npm/yarnの挙動を説明します。

[←前](https://qiita.com/qnighy/items/067dd47c48b96e772a4e) [目次](https://qiita.com/qnighy/items/16fdd8e58309a1f706a0) [次→](https://qiita.com/qnighy/items/faddc72389f6c94421e1)

## モジュールからパッケージへ

モジュールは、JavaScriptプログラムを複数のファイルに分割し、必要に応じてロードする仕組みでした。 (1ファイル = 1モジュール)

一方**パッケージ**は、複数のモジュールファイルをまとめて1つの独立した単位として扱う仕組みです。パッケージというより大きなまとまりを作ることで、バージョン番号を付与し、パッケージをパッケージレジストリに登録し、依存管理をすることができるようになります。

## Node.jsと `package.json`

パッケージはおおよそ `package.json` の存在によって特徴づけることができます。 `package.json` は主に後述するNPMで使われるファイルで、そのほとんどの機能についてNode.js自身は関知しません。しかし[一部のフィールドだけはNode.js自身によって処理されます](https://nodejs.org/docs/latest/api/modules.html#modules_folders_as_modules)。具体的には以下の2つのフィールドです。 [^package-json-esm]

[^package-json-esm]: Node.jsのES Modulesサポートではこれに加えて、[typeフィールドも参照します](https://nodejs.org/docs/latest/api/esm.html#esm_package_json_type_field)。

```json
{
  "name": "some-library",
  "main": "./lib/some-library.js"
}
```

これはNode.jsのrequireの発見のために使われます。たとえば `require('./some-library')` を行った場合、以下のいずれかのファイルが使われます。

```
./some-library.js
./some-library.json
./some-library.node
./some-library/${main} (./some-library/package.jsonがある場合)
./some-library/index.js
./some-library/index.node
```

`package.json` によるリダイレクトがあった場合、そこからの `require` の相対パスはリダイレクト先のファイル名を基準にして解決されます。たとえば、以下のような構成を考えます。

```javascript:./main.js
require('./some-library');
```

```json:./some-library/package.json
{
  "name": "some-library",
  "main": "./dist/index.js"
}
```

```javascript:./some-library/dist/index.js
require('./internal-util.js');
```

```javascript:./some-library/dist/internal-util.js
// ...
```

この場合、 `./some-library` のインポートは `./some-library/dist/index.js` に解決されます。そこから `./internal-util.js` への相対パスは `./some-library` ではなく `./some-library/dist/index.js` が基準になるので、正しく `./some-library/dist/internal-util.js` に解決されます。

## パスからの発見

`require` の引数はその接頭辞から次の3種類に分けられます。

- `./` または `../` で始まる……相対パス (現在のモジュールファイルからの相対)
  - 典型的には、「パッケージ内のファイル」を参照するのに使う
- `/` で始まる……絶対パス
- それ以外
  - 典型的には、「別パッケージのファイル」を参照するのに使う

「それ以外」の場合、真っ先に検索されるのはcoreモジュール、つまり[node自身のlibフォルダ](https://github.com/nodejs/node/tree/master/lib)です。 `fs` や `url` が代表的です。

coreモジュールでなかった場合、以下のように探索されます。

```
./node_modules/
../node_modules/
../../node_modules/
(...以下ルートに至るまでずっと)
$NODE_PATH/   ($NODE_PATH: NODE_PATH環境変数の要素)
$HOME/.node_modules   ($HOME: ホームフォルダ)
$HOME/.node_libraries   ($HOME: ホームフォルダ)
$PREFIX/lib/node   ($PREFIX: Node.jsの定義するprefix)
```

`$NODE_PATH` は `$PATH` と同様、コロン (Windowsではセミコロン) 区切りで複数指定できます。

こんにちのNode.js開発ではライブラリをグローバルに入れることは推奨されていないため、 `node_modules` 以外のルールは基本的に忘れてOKです。

ここで大事なのは、Node.jsのパス解決は**親ディレクトリに対して再帰的に検索をかける**という特徴です。「`node_modules/foo` 内のモジュールは `node_modules/foo/node_modules/bar` と `node_modules/bar` の両方を参照しうる」という性質は、後述するnpmの実装を説明する上でとても重要なポイントです。

## ライブラリ内の別ファイルからのインポート

かつてはhistoryやuuidなど著名なライブラリが、以下のようなインポートを推奨していることがありました。

```javascript
// historyライブラリのうち、createBrowserHistoryという機能だけを狙ってインポートする
const createBrowserHistory = require('history/createBrowserHistory');
// uuidライブラリのうち、v4という機能だけを狙ってインポートする
const uuidv4 = require('uuid/v4');
```

この場合、 `package.json` の `main` フィールドは無視される[^subpackage-json]ため、 `./node_modules/history/createBrowserHistory.js` や `./node_modules/uuid/v4.js` が参照されることになります。この挙動との一貫性を保つため、こういったパッケージでは通常 `index.js` をパッケージルートに置いていました。

[^subpackage-json]: 仮に `node_modules/history/createBrowserHistory/package.json` をわざわざ設置すればそれは参照されると思いますが、これは `package.json` の濫用と言ってしまっていいでしょう。

そもそもこのようなインポートが好まれていたのはwebpackなどのJavaScriptバンドラー(後述)を使った場合のバンドルサイズの削減を狙ってのことです。Tree shaking(後述) が発達した現在では利点が薄く、historyやuuidの場合も現在は以下のようなインポートが推奨されています。

```javascript
const createBrowserHistory = require('history').createBrowserHistory;
const uuidv4 = require('uuid').v4;
```

## シンボリックリンクの解決

Node.jsはシンボリックリンクを解決します。このとき、

- モジュールの同一性は解決後のパスに基づいて判定されます。
- `require` の相対パスは解決後のパスに基づいて行われます。

```javascript:main.js
const module1 = require('./module1'); // => Loading: module1.js
const module2 = require('./module2'); // Prints nothing

module1.printPath(); // => __filename = module1.js
module2.printPath(); // => __filename = module1.js
```

```javascript:module1.js
console.log(`Loading: ${__filename}`);

exports.printPath = () => {
  console.log(`__filename = ${__filename}`);
};
```

```console
ln -s module1.js module2.js
```

## npm

以上はNode.jsの提供する機能ですが、それ単体ではあまり便利ではありません。これらの機能は、**npm**[^node-package-manager]と組み合わせることで真価を発揮します。

[^node-package-manager]: Node Package Managerの略に由来していると考えられます。[古いnpmのFAQには反語的にそのことに触れられています](https://github.com/npm/npm/blob/v2.0.0/doc/misc/npm-faq.md#is-it-npm-or-npm-or-npm)。また、[公式サイトのトップ](https://www.npmjs.com/)には "We're npm, Inc., the company behind Node package manager, the npm Registry, and npm CLI." と記載されています。

npmの仕事は、**パッケージ**のバージョンと依存関係を管理し、それにもとづいて `node_modules` 以下にパッケージのコピーを配置 (ベンダリング) することです。

他のパッケージ管理ツールとの主な比較は以下の通りです:

### npmの特徴1: プロジェクトローカルに依存解決を行う。

たとえばRubyのRubygemsやPythonのpipを単独で使った場合、依存関係はシステムディレクトリ (`/usr/local/lib` など) やユーザーディレクトリ (`/home/user/` 内の隠しディレクトリなど) に保存され、そのバージョンがそのまま使われます。この方式では依存関係のバージョンに関して再現性が低かったり、複数のプロジェクトを同じ環境で同時に開発しようとしたときに無用なコンフリクトが起こるといった問題があります。

npmはRustのCargo, goのgo modulesなどと同じくプロジェクトごとに依存バージョンを管理します。

### npmの特徴2: ベンダリングを行う。

RubyのBundlerやGoのgo modulesは(デフォルトでは)依存ライブラリのデータ自体はシステムディレクトリやユーザーディレクトリに保存し、実行時やビルド時に必要なバージョンを選んで使うようになっています。

npmはNode.jsの制約上、必ず依存関係をプロジェクト内の `node_modules` ディレクトリにコピーして作業します。

### npmの特徴3: 依存グラフ内に複数バージョンが共存可能。

たとえばRubyの場合全てのパッケージはグローバルの名前空間を汚染します。使われる名前(トップレベルのモジュール名)はパッケージ名と同じにする慣習があるため、複数バージョンを同時に利用してうまくいく可能性はほとんどありません。そういった理由もあってか、bundlerでは同じ名前のパッケージの複数バージョンを同時に使うことはできません。

Node.jsでは(特に意図して書かない限り)グローバルの名前空間は汚染せず、お互いのモジュールは互いに干渉せず存在できます。そのため、Rust(Cargo)などと同じく、同じ名前のパッケージの複数のバージョンが同時に存在できます。

(Go(go modules)も複数のメジャーバージョンが共存できるため、ある意味では同じ性質を持っていると考えることもできます。)

### npmの特徴4: 中央集権的なレジストリを持つ。

Ruby, Python, Rustなどはそれぞれ中央集権的なレジストリがあり、 `rails`, `numpy`, `serde` のようにシンプルな名前がつきます。npmも同様の仕組みをとっています。

Goは `github.com/go-yaml/yaml` のようにURLのような形でパッケージ名を記述し、依存解決時は実際に対応するgitリポジトリからパッケージが取得されます。denoも `https://deno.land/std@0.68.0/testing/asserts.ts` のようにURLで依存先モジュールを指定します。

中央集権的なレジストリではname squattingの問題が顕在化しやすいと考えられます。なお、npmは[left-pad問題](https://blog.npmjs.org/post/141577284765/kik-left-pad-and-npm)を起こしたことがありますが、Goも[go-bindata問題](https://www.reddit.com/r/golang/comments/7vv9zz/popular_lib_gobindata_removed_from_github_or_why/)を起こしたことがあり、必ずしも中央集権的なレジストリの問題とは言えないでしょう。

## npmとyarn

Node.jsのパッケージ管理ツールはnpmだけではありません。ここではnpmと互換性の高く、広く使われているyarn (yarn v1, classic yarn)についても説明します。

yarnはFacebookが中心となって作っているnpmの代替パッケージ管理ツールです。yarnの仕事はnpmとほぼ同じです。つまり、パッケージのバージョンと依存関係を管理し、それにもとづいて `node_modules` 以下にパッケージのコピーを配置 (ベンダリング) します。以下が主な差異です。

- 依存解決時の詳細な挙動。
- ロックファイルの種類。npmは `npm-shrinkwrap.json` と `package-lock.json` を使う一方、yarnは `yarn.lock` を使います。
- 読み取り用のデフォルトレジストリ。npmは `registry.npmjs.org` を使いますが、yarnはそのレプリカである `registry.yarnpkg.com` からパッケージを取得します。 (レプリカなのでユーザーから見た挙動は同じです)

![図: npmレジストリとyarnレジストリの関係](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/792654ce-95fb-a9b8-0d0f-e520354db462.png)

## パッケージ

パッケージとは `package.json` を含むディレクトリまたはアーカイブファイル (tar.gz) です。 [`package.json` にはさまざまな情報を乗せられます](https://docs.npmjs.com/files/package.json)が、パッケージ管理の観点から必要な情報だけを説明すると以下のようになります。

```javascript
{
  "name": "some-package",
  "version": "0.1.0",
  // 依存関係とそのバージョン制約
  "dependencies": {
    "library1": "^0.3.1",
    "library2": ">= 1.2.0, < 3.0.0"
  },
  // このパッケージ自身を開発するときに必要な依存関係
  "devDependencies": {
    "testing-library1": "^1.2.3",
    "linter1": "2.x"
  },
  // 同時に入れるべきパッケージとそのバージョン
  "peerDependencies": {
    "state-management-library1": ">= 10.2"
  },
  // dependenciesと似ているが、依存先のインストールが失敗しても無視する
  "optionalDependencies": {
    "windows-specific-library": "3.x"
  }
}
```

他の多くのパッケージ管理ツールと同じく、依存関係には**バージョンの範囲 (バージョンの制約)** を指定します。たとえば `^1.2.3` なら厳密にバージョン `1.2.3` である必要はなく、それより大きなバージョンでも (メジャーバージョンが1であれば) OKという指定になります。これは

Rust (Cargo) や Go (go modules)[^go-modules-version-constraints]と違い、npmでは単に `1.2.3` と書くと `=1.2.3` の意味になってしまうので注意が必要です。npmのパッケージはsemantic versionに従っていることが期待されていますから、基本的にはキャレット制約 (`^1.2.3`) を使っておけばいいでしょう。[^caret-requirements-rationale]

[^go-modules-version-constraints]: go modulesでは指定できるのは「あるバージョン以上」という制約のみだが、semantic import pathの規則により事実上のキャレット制約 (`^1.2.3`) として機能する
[^caret-requirements-rationale]: キャレット制約では、「指定したバージョン以上かつ、同じメジャーバージョン」であることを要求します。semverではメジャーバージョンが上がるときは互換性のない変更が許されているので、次のメジャーバージョンは自動的には含まれません。マイナーバージョンには機能追加、パッチバージョンにはバグ修正が含まれているため、指定したバージョンより小さいバージョンも含まれません。

## npm install / yarn installの流れ

npm / yarnの処理は大きく2段階に分けられます。

1. **依存解決**により、 `package.json` から**依存グラフ**を作成します。
2. 依存グラフを**展開**して、依存グラフから **node_modulesツリー**を作成します。

そうして作成したnode_modulesツリーを書き出すことでnpm install / yarn installの仕事は完了します。

![npm install / yarn installの流れ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/fc3ce3ed-e469-806a-aee8-d0dbb812f6db.png)


## 依存解決

依存解決では、バージョン制約に具体的なバージョンを割り当てていきます。

![図: バージョンを選択する](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/ce014e9d-9b89-8877-6aa9-7bb555afe5ec.png)

バージョンが割り当てられたら、解決先パッケージの依存をさらに再帰的に解決していきます。

![図: 依存を再帰的に解決する](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/f2449b90-2a6c-2ff6-7c10-0ed57d238749.png)

必要なパッケージの依存が全て解決されたら終わりです。

複数のパッケージが同じ制約を持っていたり、複数の制約が同じバージョンに解決されることもあります。そのため、依存解決の結果は木ではなくDAG (無閉路有向グラフ) になります。これをここでは**依存グラフ**と呼びます。

![図: 依存グラフの例](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/ddfa3cda-71d7-1f73-7156-b08dcded7de9.png)

## 依存グラフの展開

npm / yarnの場合、依存グラフができただけでは終わりではありません。Node.jsはnpm / yarnに依存せず動作するので、Node.jsが意図通りのモジュール解決をするようにあらかじめ `node_modules` にパッケージを展開しておく必要があります。このとき、依存グラフをどのように `node_modules` に展開するかは自明ではありません。

先ほどの依存グラフの例を考えます。

![図: 依存グラフの例](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/ddfa3cda-71d7-1f73-7156-b08dcded7de9.png)

### npm@2までの展開

npmのバージョン2まではこの依存グラフを以下のように展開します:

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/ca2dffcb-830d-5bba-736f-fbcf1c3cb80d.png" alt="npmバージョン2による依存グラフの展開" width="300">

**`node_modules` ディレクトリの中にまた `node_modules` ディレクトリがある**ことに注意してください。依存グラフに同じパッケージの複数のバージョンがある場合、全てのバージョンをルートの `node_modules` にそのまま入れることはできません。そこで、npmのバージョン2までは、**間接依存関係は全てルートではなく対応するパッケージの `node_modules` に個別に展開**していました。

この方法はいわゆる依存関係地獄(複数のバージョンが共存できない)を解決しますが、**同じパッケージの同じバージョンが複数回展開される**という問題があります。これは以下の弊害をもたらします:

- [ただでさえ大きい `node_modules`](https://www.reddit.com/r/ProgrammerHumor/comments/6s0wov/heaviest_objects_in_the_universe/) のサイズがさらに大きくなってしまう。
- Node.jsから見て同じモジュールにならないため、副作用のあるモジュールやオブジェクトの同一性が重要になるモジュールでは期待しない挙動になる可能性がある。

### npm@3以降とyarnの展開: パッケージの巻き上げ

残念ながら最新のnpm/yarnでも上記の問題は解決されていませんが、npmバージョン3以降とyarnでは緩和策が実装されています。これらのバージョンのnpm/yarnではこの依存グラフを以下のように展開します。

![npmバージョン3以降とyarnによる依存グラフの展開](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/b790b33f-a99c-84e2-95ea-92b97bcc1665.png)

つまり、**間接依存パッケージから1つのバージョンを選んで、より上位の `node_modules` に配置する**ことができます。これにより多くの場合でパッケージが共有されるようになります。Node.jsの `require` はよりインポート元ファイルに近い `node_modules` から順番に探索するので、依然として依存グラフ通りのバージョンがrequireされます。

この方法を**パッケージの巻き上げ (hoisting)** と呼びます。

パッケージの巻き上げの問題として、依存グラフの展開の非決定性があります。これについては後述します。

#### 間接依存の巻き上げ

間接依存も可能な限り巻き上げられます。たとえば、npm v2で以下のように展開されるような依存グラフを考えます。

```
main
|- foo1 (1.0.0)
|  |- bar1 (2.0.0)
|     |- baz1 (1.0.0)
|     |- baz2 (2.0.0)
|- bar1 (1.0.0)
|- baz2 (1.0.0)
```

この場合 `main` は `bar1` のバージョン1に依存しているため、 `main`→`foo1`→`bar1` の依存関係 (バージョン2を指定している) は巻き上げられません。つまり `bar1` は真の間接依存関係になります。

では `bar1` の依存関係である `baz1` と `baz2` はどうなるでしょうか。npm v3以降では、これらはそれぞれ以下のように巻き上げられます。

- `main` が `baz1` の異なるバージョンに依存しているため、 `baz2` は2段階は巻き上げられません。しかし、1段階の巻き上げは可能です。
- `baz1` は2段階巻き上げが可能なので、2段階巻き上げられます。

結果として以下のようなnode_modulesツリーが生成されます。

```
main
|- foo1 (1.0.0)
|  |- bar1 (2.0.0)
|  |- baz2 (2.0.0)
|- bar1 (1.0.0)
|- baz1 (1.0.0)
|- baz2 (1.0.0)
```

### おまけ: シンボリックリンクを使った展開

同じパッケージの同じバージョンが複数回インストールされる問題を解決することは論理的には可能で、シンボリックリンクを使った方法があります。この方法は[Node.jsのドキュメントに「OSのパッケージ管理ツール向けの方法」として紹介されています](https://nodejs.org/api/modules.html#modules_addenda_package_manager_tips)が、 `node_modules` にも適用可能なはずです。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/54b2542f-62b2-2d79-fd84-fba773521a7d.png" alt="シンボリックリンクを使った展開例" width="300">

シンボリックリンクがある場合は、シンボリックリンクの解決後のパスに基づいて同一性が判定されるため、このようにしておけば `bar@1.0.0` と `bar@2.0.0` はそれぞれ1回ずつ読み込まれることが保証できます。

npmやyarnがこの方法を使わない理由は不明です。もしかしたら筆者の知らない問題点があるのかもしれませんし、何かシンボリックリンクを使いたくない理由があるのかもしれません[^no-symlink-why]。ただ、現在はtinkやberry (yarn v2)のように `node_modules` へのベンダリングを行わない方式のほうが有望視されているので、今から `node_modules` をよりうまく使う方法を実装する利点は少なそうです。

[^no-symlink-why]: Windowsのようにシンボリックリンクが比較的最近導入され、必ずしもエコシステムとして洗練されていないプラットフォームのためかもしれません。また、webpackなど他のツールで、高速化のためにシンボリックリンクの解決を行わないオプションを持っているものがあるため、そういったツールを使いやすいようにという考えかもしれません。

## ロックファイル

npm/yarnに限らず、パッケージ管理はそのままでは非決定的なのが普通です。npm/yarnの場合は以下の2つの要因で非決定的になります。

1. 依存解決の非決定性。go modulesを除くほとんどのパッケージ管理ツールは**できるだけ大きいバージョンに解決する**ため、 `^1.2.3` という指定が何に解決されるかはレジストリの状態に依存します。 `1.2.3` と `1.3.0` しかなければ `1.3.0` に解決されますが、 `1.4.0` がリリースされた後に再度解決を試みた場合は `1.4.0` に解決されます。
2. 展開の非決定性。間接依存関係を上位の `node_modules` に引き上げるとき、どのバージョンが採択されるかは単純なルールでは決まりません。このため後述するような理由で結果が変わる可能性があります。

これらの問題を解決するため、npm/yarnともに**ロックファイル**の仕組みを提供しています。しかし、npmの提供するロックファイルとyarnの提供するロックファイルは少しだけ役割が異なります。

![npm install / yarn installの流れ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/31409/fc3ce3ed-e469-806a-aee8-d0dbb812f6db.png)

### yarn.lock

`yarn.lock` はyarnが生成するロックファイルで、**依存解決の結果**、つまり**依存グラフ**を記録します。以下がその例です。

```
ajv@^5.3.0:
  version "5.5.2"
  resolved "https://registry.yarnpkg.com/ajv/-/ajv-5.5.2.tgz#73b5eeca3fab653e3d3f9422b341ad42205dc965"
  integrity sha512-Ajr4IcMXq/2QmMkEmSvxqfLN5zGmJ92gHXAeOXq1OekoH2rfDNsgdDoL2f7QaRCy7G/E6TpxBVdRuNraMztGHw==
  dependencies:
    co "^4.6.0"
    fast-deep-equal "^1.0.0"
    fast-json-stable-stringify "^2.0.0"
    json-schema-traverse "^0.3.0"

ajv@^6.1.0, ajv@^6.10.0, ajv@^6.10.2:
  version "6.10.2"
  resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.10.2.tgz#d3cea04d6b017b2894ad69040fec8b623eb4bd52"
  integrity sha512-TXtUUEYHuaTEbLZWIKUr5pmBuhDLy+8KYtPYdcV8qC+pOZL+NKqYwvWSRrVXHn+ZmRRAu8vJTAznH7Oag6RVRw==
  dependencies:
    fast-deep-equal "^2.0.1"
    fast-json-stable-stringify "^2.0.0"
    json-schema-traverse "^0.4.1"
    uri-js "^4.2.2"

ajv@^6.12.0:
  version "6.12.0"
  resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.12.0.tgz#06d60b96d87b8454a5adaba86e7854da629db4b7"
  integrity sha512-D6gFiFA0RRLyUbvijN74DWAjXSFxWKaWP7mldxkVhyhAV3+SWA9HEJPHQ2c9soIeTFJqcSdFDGFgdqs1iUU2Hw==
  dependencies:
    fast-deep-equal "^3.1.1"
    fast-json-stable-stringify "^2.0.0"
    json-schema-traverse "^0.4.1"
    uri-js "^4.2.2"

ajv@^6.12.2:
  version "6.12.3"
  resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.12.3.tgz#18c5af38a111ddeb4f2697bd78d68abc1cabd706"
  integrity sha512-4K0cK3L1hsqk9xIb2z9vs/XU+PGJZ9PNpJRDS9YLzmNdX6jmVPfamLvTJr0aDAusnHyCHO6MjzlkAsgtqp9teA==
  dependencies:
    fast-deep-equal "^3.1.1"
    fast-json-stable-stringify "^2.0.0"
    json-schema-traverse "^0.4.1"
    uri-js "^4.2.2"
```

実際にはこのようなエントリがたくさん並んでいます。

ハッシュ値なども記録されていますが本質的には `{バージョン制約→解決されたバージョン}` のマップになっています。これは依存グラフを1つ指定していることにほかなりません[^pathological-dep-graph]。

[^pathological-dep-graph]: 正確には、「同じバージョン制約でも、依存元パッケージによって異なるバージョンに解決される」という状況は排除されていることになります。 `foo` と `bar` がそれぞれ `baz@^1.2.3` に依存しているのに、 `foo` からは `baz v1.2.3` が見えていて `bar` からは `baz v1.3.0` が見えているような状態です。このようなケースを考える必要性は薄いので、以降ではこういうケースはないものとして考えます。

つまり `yarn.lock` 自体は**依存解決 (依存グラフの生成)**までの結果を保証しますが、それ自体では**依存グラフの展開**までの結果は保証しません。yarnは[「決定論的で信頼できるアルゴリズム (deterministic and reliable algorithm)」を使う](https://engineering.fb.com/web/yarn-a-new-package-manager-for-javascript/)ことで後半の再現性を保証するアプローチを取っています。

### npm-shrinkwrap.json / package-lock.json

一方npmは `npm-shrinkwrap.json` / `package-lock.json` のどちらかを生成します。**この2つは同じフォーマットで同じ情報を記録します**。

```javascript
{
  "name": "main",
  "version": "0.1.0",
  "lockfileVersion": 1,
  "requires": true,
  "dependencies": {
    "ajv": {
      "version": "6.10.2",
      "requires": {
        "fast-deep-equal": "^2.0.1",
        "fast-json-stable-stringify": "^2.0.0",
        "json-schema-traverse": "^0.4.1",
        "uri-js": "^4.2.2"
      },
      "dependencies": {
        "fast-deep-equal": {
          "version": "2.0.1"
        }
      }
    },
    // ...
    "babel-loader": {
      "version": "8.1.0",
      "requires": { /* ... */ },
      "dependencies": {
        "ajv": {
          "version": "6.12.0",
          "requires": {
            "fast-deep-equal": "^3.1.1",
            "fast-json-stable-stringify": "^2.0.0",
            "json-schema-traverse": "^0.4.1",
            "uri-js": "^4.2.2"
          }
        },
        // ...
      }
    },
    // ...
    "har-validator": {
      "version": "5.1.0",
      "requires": { /* ... */ },
      "dependencies": {
        "ajv": {
          "version": "5.5.2",
          "requires": {
            "co": "^4.6.0",
            "fast-deep-equal": "^1.0.0",
            "fast-json-stable-stringify": "^2.0.0",
            "json-schema-traverse": "^0.3.0"
          }
        },
        // ...
      }
    },
  }
}
```

yarn.lockがフラットな一覧であったのに対して、こちらは入れ子構造になっています。これは **`node_modules` に展開したときの構造をそのまま記録**しているからです。yarn.lockと違い、 `./node_modules/ajv` にどのバージョンがインストールされたかも一目瞭然です。

つまり、 `npm-shrinkwrap.json` / `package-lock.json` は **`./node_modules` 以下の構造を再現するに足りる情報**を持っていることになります。

ただし、歴史的には `npm-shrinkwrap.json` を使っても `./node_modules` に再現性がないと言われていた時期がありました。これはおそらく `npm-shrinkwrap.json` の読み取りが正しく行われていなかったか、 `npm-shrinkwrap.json` が自動で書き出されない挙動になっていたかのどちらかだと思うのですが、これは調査しても正確なところがわからなかったので保留します。

`npm-shrinkwrap.json` と `package-lock.json` の違いは以下の通りです。

- `npm-shrinkwrap.json` はnpmの初期から存在したが、 `package-lock.json` はnpmバージョン5で登場した。
- 両方存在する場合は `npm-shrinkwrap.json` が優先される。
- どちらも存在しない場合は `package-lock.json` が自動的に生成される。 (npmバージョン5以降)
- `package-lock.json` はレジストリに公開するパッケージには含められない。 `npm-shrinkwrap.json` は含められる。
- トップレベル以外のパッケージに `package-lock.json` があっても無視される。 `npm-shrinkwrap.json` は考慮される。

## `devDependencies`, `optionalDependencies`, `acceptDependencies`

**`devDependencies`** は自分自身がトップレベルパッケージである場合のみ指定される依存関係です。

ライブラリの場合、**そのライブラリ自体を開発するときにしか使わないもの**は通常、 `devDependencies` に指定します。よくあるのは、リントツール (eslint), フォーマッター (prettier), テスト (jest), トランスパイラ (typescript), 型情報 (`@types/*`) などです。ただし、 `devDependencies` に入れるべきかどうかは、ライブラリの種類によって決まるのではなく、**そのライブラリをどう使うかによって決まる**ことに注意が必要です。たとえば `eslint` を呼び出すラッパーライブラリであれば `eslint` は実行時にも必要になるため、 `dependencies` に入れるほうが適切だと考えられます。

npm経由で配布するアプリケーションの場合、そのアプリケーションを起動するのに必要ないものは `devDependencies` に置くとよいでしょう。npm経由ではなく、常にソースツリーから扱うアプリケーションの場合も同様のルールに従うのが望ましいですが、実際のところはどちらに置いても実効的な違いはなさそうです。

**`optionalDependencies`** は `dependencies` と似ていますが、依存先パッケージのインストール失敗を許容します。たとえば[`chokidar`](https://github.com/paulmillr/chokidar)はファイルシステムの変更を監視するライブラリで、macOSでは [`fsevents`](https://github.com/fsevents/fsevents) ライブラリの機能を利用します。 macOS以外では `fsevents` のインストールに失敗しますが、`chokidar`→`fsevents` の依存指定は optionalDependencies で行われているため、 `npm install` には失敗しません。

[**`acceptDependencies`** はnpm v7で追加される新しい依存指定です](https://github.com/npm/rfcs/blob/632557a963e67ad1765a6e81792b3ec3cb1a0694/implemented/0023-acceptDependencies.md)。 `devDependencies` と同様、トップレベルパッケージかどうかで挙動を変える効果があります。npm v6以前との互換性を保ちつつ、 `engine` に関する制約検証が厳しすぎる問題を回避するために実装されたようです。

## `peerDependencies`

`peerDependencies` は**自分自身の依存ではなく、依存元パッケージの依存を指定する機能**です。

典型的なパターンは**プラグインからフレームワークへの依存**です。たとえば有名なJavaScriptバンドラーであるWebpackはその機能を `webpack` パッケージに集約せず、多数のプラグインプラグインパッケージに分けて提供しています。たとえばWebpackにCSSを読み込ませるには `css-loader` が必要なので、 `webpack` と `css-loader` の両方への依存を書くことになりますが、このバージョンの組み合わせによっては正しく動かない可能性があります。 (`webpack` だけ古すぎる or `css-loader` だけ古すぎる)

そこで、 `css-loader` 側の `package.json` には、そのバージョンの `css-loader` と組み合わせて使うことができる `webpack` のバージョンが記載されています。たとえば [`css-loader` 4.3.0 の場合](https://github.com/webpack-contrib/css-loader/blob/v4.3.0/package.json#L42-L44)

```json
  "peerDependencies": {
    "webpack": "^4.27.0 || ^5.0.0"
  }
```

と書かれているため、バージョン 4.27.0以上6未満のwebpackと組み合わせることが想定されていることになります。これは `css-loader` 自身の依存ではなく、 `css-loader` を利用する側のパッケージからの `webpack` の依存に関する指定ととらえることができます。

意図自体は以上の通りなのですが、peerDependenciesが指定されたときの**実際の挙動はnpmのバージョンによって異なります**。

### 主な違い

- **npm v1～v2**では、peerDependenciesに記載されたパッケージは自動的にインストールされ、バージョン制約上不可能な場合はエラーになります。
- **npm v3～v6**および**yarn v1**[^yarn-v1]では、peerDependenciesの記載は警告にのみ使われます。 (指定したパッケージが存在しない場合と、バージョン制約が正しくないときに警告が出る)
- **npm v7**[^npm-v7-beta]では、peerDependenciesに記載されたパッケージは自動的にインストールされ、バージョン制約上不可能な場合 (=別の理由で別のバージョンが既にインストールされている場合) は警告が表示されます。

[^yarn-v1]: 1.22.5 で確認。
[^npm-v7-beta]: 7.0.0-beta.12 で確認。

### peerDependenciesで指定したパッケージが存在しなかったときの挙動

「`webpack` への依存を書き忘れた場合」に相当する挙動は、npmのバージョンによって異なります。

**npm v1～v2**は、peerDependenciesの内容は**自動的にインストールされます**。 `css-loader` への依存を書けば、 `webpack` も自動的にインストールされることになります。

**npm v3～v6**では、peerDependenciesの内容は**自動的にはインストールされません**。存在チェックだけが行われ、**存在しない場合は警告が表示されます**。

**npm v7-beta**では、peerDependenciesの内容は**自動的にインストールされます**。 `--legacy-peer-deps` を指定するとv3～v6と同様の挙動になります。

**yarn v1**はnpm v3～v6と同様です。

### peerDependenciesのバージョン制約が満たされなかったときの挙動

「`webpack` の依存だけ古すぎる場合」に相当する挙動は、npmのバージョンによって異なります。

**npm v1～v2**ではエラーになります。

**npm v3以降**と**yarn v1**では警告が発生し、peerDependenciesに指定したバージョンのインストールは諦められます。

### peerDependenciesで指定したパッケージが存在しなかったが、別の間接依存からの巻き上げによって偶然制約が満たされた場合の挙動

「`webpack` への依存を書き忘れたが、たまたま他の依存からの巻き上げでwebpackが降りてきた場合」に相当する挙動は、npmのバージョンによって異なります。

**npm v1～v2**では巻き上げが存在しません。

**npm v3～**では制約が充足されたものとして扱われ、警告は発生しません。

**yarn v1**では警告が発生します。

### peerDependenciesで指定したパッケージが存在しなかったが、別の間接依存からの巻き上げによって制約を満たさないバージョンが含まれた場合の挙動

「`webpack` への依存を書き忘れたが、たまたま他の依存からの巻き上げでwebpackが降りてきた場合」に相当する挙動は、npmのバージョンによって異なります。

**npm v1～v2**では巻き上げが存在しません。

**npm v3～v6**と**yarn v1**では警告が発生し、peerDependenciesに指定したバージョンのインストールは諦められます。

**npm v7**では巻き上げより先にpeerDependenciesのほうが解決されるため、巻き上げが発生しません。

## bundledDependencies

`bundledDependencies` は他の `*Dependencies` 系のフィールドと異なり、パッケージ名の配列です。 (つまり、他の `dependencies` 系のフィールドと併用します)

通常 `npm pack` は `./node_modules` 以下をアーカイブに含めませんが、当該パッケージが `bundledDependencies` で指定されている場合はそのディレクトリに限り含まれるようです。

使う機会は多くないようなので詳細は省きます。

## スコープ

npmバージョン2以降では**スコープ**がサポートされています。通常npmのパッケージは `babel-core` のように**スラッシュを含まない**名前が使われますが、 `@` で始まる名前はスコープと呼ばれ、スラッシュ区切りの接頭辞として扱われます。たとえば `@babel/core` は `@babel` というスコープに含まれるパッケージになります。

スコープは主に以下のような目的で使われます。

- npm公式レジストリ上で、まとまった名前空間の利用権を予約する。
- npm公式レジストリ上でプライベートパッケージを公開する。 (プライベートパッケージ用のスコープが必要になる)
- 特定のスコープだけ、別のレジストリを参照させる。

スコープは依存解決の観点からは特別な挙動はないですが、ファイルシステム上に展開するときには名前の通り2層のディレクトリに展開されます。たとえば `babel-core` と `babel-runtime` に依存する場合には以下のように展開されますが、

```
main/
|- node_modules/
   |- babel-core/
      |- package.json
   |- babel-runtime/
      |- package.json
```

`@babel/core` と `@babel/runtime` に依存する場合は以下のようになります。

```
main/
|- node_modules
   |- @babel/
      |- core/
         |- package.json
      |- runtime/
         |- package.json
```

Node.jsから見れば、 `require("babel-core")` が `require("@babel/core")` になるだけですが、TypeScriptがDefinitelyTypedの型定義を参照するときなど、この構造が利用されることもあります。

## 存在しないパッケージのrequire

npmは `packages.json` に書いたパッケージが(そのパッケージ内から) `require` 可能なようにパッケージを展開しますが、Node.jsの動作原理上、 `packages.json` に書いていないパッケージも偶然 `require` できてしまう場合があります。

- 間接依存が巻き上げられた場合。
- 直接または間接的な依存元が、そのパッケージに依存している場合。
- 複数の `package.json` からなるプロジェクトで、親ディレクトリでも `npm install` が行われている場合。

もし "Cannot find module" が特定の環境でのみ起こる場合、こういったケースを疑ってみるとよさそうです。

## まとめ

- Node.js自身は `package.json` を `require` のリダイレクトに用いる以外はパッケージシステムに関知せず、npm/yarnなどのパッケージマネージャとの併用が想定されている。
- 現在主流の方式 (npm, yarn v1など) では、 `./node_modules` ディレクトリに依存パッケージをベンダリングする方式が採られている。この制約上、npm/yarnは単に依存グラフの生成を行うだけではなく、それをファイルシステム上に展開するために配置方法を決定する責務も負っている。
- このとき、依存地獄を防ぎつつモジュールツリーの爆発を防ぐ(またできるだけ同一パッケージのモジュール同一性を担保する)ために、巻き上げという方法が使われる。巻き上げはnpm v3以降で導入された。
- npmとyarnは異なるロックファイルの形式を採用しており、これらは上記の2段階解決 (依存グラフの生成→ファイルシステム上の配置方法の決定) の1段階目の結果と2段階目の結果にそれぞれ対応している。
- npmはv5以降では自動的にロックファイルを生成するようになり、ロックファイルの信頼性が向上した。
- npmではdependencies, devDependenciesのほかにpeerDependenciesという特殊な依存記述がある。これは依存元の依存関係を追加指定する効果があるが、挙動がバージョンによって異なる。
- npm v2以前ではpeerDependenciesの記述は強制されていた。
- npm v3～v6およびyarnではpeerDependenciesの記述は警告のためだけに使われていた。
- npm v7ではpeerDependenciesの記述は可能な限り尊重されるが、制約充足に失敗してもエラーにはならない。
- 存在しないパッケージのrequireが成功してしまうケースがいくつかある。特に複数の `package.json` をもつプロジェクトでは注意が必要。

本稿ではnpm/yarnのライブラリベンダリングに注目してまとめましたが、npm/yarnにはコマンドラインアプリケーションを管理する機能もあります。次回はnpm/yarnをアプリケーションの観点からまとめます。

[←前](https://qiita.com/qnighy/items/067dd47c48b96e772a4e) [目次](https://qiita.com/qnighy/items/16fdd8e58309a1f706a0) [次→](https://qiita.com/qnighy/items/faddc72389f6c94421e1)