pnpmとは何ですか？ 使用ガイド

フロントエンド開発の世界では、パッケージマネージャーは私たちが日々使うツールです。最も初期のnpmから、後続のyarn、そして現在「最先端」と称される **pnpm** まで、ツールの進化は常に3つのコア指標、すなわち**速度、空間効率、依存関係の安全性**を中心に展開してきました。

この記事では、pnpmについて理解を深め、その使い方を学びます。

## pnpmとは？

**pnpm** (Performant npm) は、極めて高速でディスク容量を節約するパッケージマネージャーです。

### コアメリット

- **超高速（Performance）：** pnpmはnpmやyarnよりもはるかに高速です（通常2倍以上）。これは、大量のファイルの重複コピーを回避する独自のインストールメカニズムを採用しているためです。
- **容量節約（Efficiency）：** これがpnpmの切り札です。**コンテンツアドレスストレージ（Content-addressable storage）**を使用しています。もし10個のプロジェクトがすべて同じバージョンの`lodash`を使用している場合、ディスク上では1つしか保存されません。
- **「ゴースト依存関係」の完全な解決（Safety）：** 従来のnpm/yarnは依存関係を「フラット化」（flat）するため、`package.json`に宣言していないパッケージにもコードからアクセスできてしまう問題がありました。pnpmは**シンボリックリンク（Symlinks）**を使用して厳格な依存関係ツリーを構築し、宣言されたパッケージのみにアクセスできるようにします。

## pnpmの「正しい使い方」

### pnpmのインストール

Node.jsが既にインストールされている場合は、コア管理ツールから直接インストールすることをお勧めします。

```Bash
corepack enable
corepack prepare pnpm@latest --activate
```

または、npmを使用してグローバルにインストールすることもできます: `npm install -g pnpm`

### よく使うコマンド対照表

| **操作**     | **npm コマンド**          | **pnpm コマンド**                   |
| ------------ | --------------------- | ------------------------------- |
| 依存関係のインストール     | `npm install`         | `pnpm install` (または `pnpm i`)    |
| パッケージの追加       | `npm install <pkg>`   | `pnpm add <pkg>`                |
| 開発依存関係の追加 | `npm i <pkg> -D`      | `pnpm add <pkg> -D`             |
| パッケージの削除       | `npm uninstall <pkg>` | `pnpm remove <pkg>`             |
| スクリプトの実行     | `npm run <script>`    | `pnpm <script>` (run は不要) |
| グローバルインストール     | `npm install -g`      | `pnpm add -g`                   |

### Nodeバージョンの管理

pnpmにはバージョン管理機能が組み込まれており、nvmをインストールする必要すらありません。

- 指定バージョンのインストール：`pnpm env use --global 20`



## 応用

### ストレージパス（Store Path）の設定

pnpmのコアロジックは、すべてのパッケージをグローバルな`store`に保存し、そこから各プロジェクトの`node_modules`にハードリンクでマッピングすることです。

デフォルトでは、storeは現在のドライブのルートディレクトリに配置されます。ストレージの場所をカスタマイズしたい場合（例えばCドライブの空き容量を心配している場合）：

```Bash
# 現在のstoreパスを表示
pnpm store path

# カスタムパスを設定
pnpm config set store-dir D:\.pnpm-store
```

### Monorepoのベストプラクティス

pnpmは、**Monorepo**（マルチパッケージ管理プロジェクト）を処理する上で、現在最適な選択肢です。ルートディレクトリに`pnpm-workspace.yaml`ファイルを作成するだけです。

```yaml
packages:
  - 'packages/*'
  - 'apps/*'
```

その後、プロジェクト間で依存関係をインストールできます: `pnpm add lodash --filter @my-app/web`。

### npm/yarnとの違い

- **npm/yarn (v1):** フラットな構造を採用しており、依存関係の競合が発生しやすく、ディスク容量の消費も大きいです。
- **yarn (v2/v3) Berry:** PnPモードを導入しましたが、高速である一方で互換性の課題が大きいです。
- **pnpm:** バランスの取れた解決策を見つけました。`node_modules`の物理構造（シンボリックリンクとハードリンク経由）を維持し、非常に高い互換性を保証しつつ、極限のパフォーマンスを実現しています。

## 古いプロジェクトをpnpmに移行する

プロジェクトのルートディレクトリで以下の操作を行います。

1. **pnpmのインストール**（まだインストールしていない場合）：

   ```Bash
   npm install -g pnpm
   ```

2. **pnpmロックファイルの生成**： 以下のコマンドを実行すると、既存の`package-lock.json`または`yarn.lock`を自動的に読み込み、パッケージをダウンロードせずに`pnpm-lock.yaml`を生成します。

   ```Bash
   pnpm import
   ```

3. **古いファイルの削除**： プロジェクトを整理するために、古い`node_modules`と古いロックファイルを削除します。

   ```Bash
   # Windowsユーザーはdelコマンドを使用するか、手動で削除してください
   rm -rf node_modules package-lock.json yarn.lock
   ```

4. **依存関係の再インストール**： pnpmを使用して最後のステップを完了します。

   ```Bash
   pnpm install
   ```