Bun は 分離インストール と呼ばれる代替パッケージインストール戦略を提供し、pnpm のアプローチに似た厳格な依存関係の分離を作成します。このモードはファントム依存関係を防止し、再現可能で決定論的なビルドを保証します。

これは、ロックファイルの configVersion = 1 を持つ新しいワークスペース/モノレポプロジェクトのデフォルトのインストール戦略です。既存のプロジェクトは、明示的に設定しない限り、巻き上げインストールを引き続き使用します。

分離インストールとは

分離インストールは、パッケージが明示的に宣言された依存関係のみにアクセスできる非巻き上げ依存関係構造を作成します。これは、依存関係が共有 node_modules ディレクトリにフラット化される npm や Yarn によって使用される従来の「巻き上げ」インストール戦略とは異なります。

主な利点

• ファントム依存関係を防止 — パッケージは宣言していない依存関係を誤ってインポートできません
• 決定論的解決 — 他に何がインストールされているかに関係なく、同じ依存関係ツリー
• モノレポに最適 — ワークスペースの分離により、パッケージ間の相互汚染を防止
• 再現可能なビルド — 環境全体でより予測可能な解決動作

分離インストールの使用

コマンドライン

--linker フラグを使用してインストール戦略を指定します。

# 分離インストールを使用
bun install --linker isolated

# 従来の巻き上げインストールを使用
bun install --linker hoisted

設定ファイル

bunfig.toml または $HOME/.bunfig.toml のグローバルでデフォルトのリンカ戦略を設定します。

[install]
linker = "isolated"

デフォルトの動作

デフォルトのリンカ戦略は、プロジェクトのロックファイルの configVersion に依存します。

configVersion	ワークスペース使用？	デフォルトリンカ
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

新しいプロジェクト: configVersion = 1 をデフォルトとします。ワークスペースでは、v1 はデフォルトで分離リンカを使用します。それ以外の場合は巻き上げリンカを使用します。

既存の Bun プロジェクト（v1.3.2 より前に作成）: 既存のロックファイルにまだバージョンがない場合、bun install を実行すると Bun は configVersion = 0 を設定し、以前の巻き上げリンカのデフォルトを保持します。

他のパッケージマネージャーからの移行:

• pnpm から: configVersion = 1（ワークスペースで分離インストールを使用）
• npm または yarn から: configVersion = 0（巻き上げインストールを使用）

--linker フラグを明示的に指定するか、設定ファイルで設定することで、デフォルトの動作を上書きできます。

分離インストールの仕組み

ディレクトリ構造

依存関係を巻き上げる代わりに、分離インストールは 2 層構造を作成します。

node_modules/
├── .bun/                          # 中央パッケージストア
│   ├── package@1.0.0/             # バージョン付きパッケージインストール
│   │   └── node_modules/
│   │       └── package/           # 実際のパッケージファイル
│   ├── @scope+package@2.1.0/      # スコープ付きパッケージ（/ を + に置き換え）
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # シンボリックリンク

解決アルゴリズム

1. 中央ストア — すべてのパッケージは node_modules/.bun/package@version/ ディレクトリにインストールされます
2. シンボリックリンク — トップレベルの node_modules には中央ストアを指すシンボリックリンクが含まれます
3. ピア解決 — 複雑なピア依存関係は特殊なディレクトリ名を作成します
4. 重複排除 — 同一のパッケージ ID とピア依存関係セットを持つパッケージは共有されます

ワークスペースの処理

モノレポでは、ワークスペースの依存関係は特別に処理されます。

• ワークスペースパッケージ — ストアではなく、ソースディレクトリに直接シンボリックリンクされます
• ワークスペース依存関係 — モノレポ内の他のワークスペースパッケージにアクセスできます
• 外部依存関係 — 適切な分離で分離ストアにインストールされます

巻き上げインストールとの比較

側面	巻き上げ（npm/Yarn）	分離（pnpm ライク）
依存関係アクセス	パッケージは巻き上げられた依存関係にアクセス可能	パッケージは宣言された依存関係のみ表示
ファントム依存関係	❌ 発生可能	✅ 防止
ディスク使用量	✅ 低減（共有インストール）	✅ 同様（シンボリックリンク使用）
決定論	❌ 決定論的でない	✅ より決定論的
Node.js 互換性	✅ 標準動作	✅ シンボリックリンク経由で互換
最適な用途	単一プロジェクト、レガシーコード	モノレポ、厳格な依存関係管理

高度な機能

ピア依存関係の処理

分離インストールは、高度な解決を通じてピア依存関係を処理します。

# ピア依存関係を持つパッケージは特殊なパスを作成
node_modules/.bun/package@1.0.0_react@18.2.0/

ディレクトリ名はパッケージバージョンとピア依存関係バージョンの両方をエンコードし、各一意の組み合わせが独自のインストールを取得することを保証します。

バックエンド戦略

Bun はパフォーマンスのために異なるファイル操作戦略を使用します。

• Clonefile（macOS）— 最大効率のためのコピーオンライトファイルシステムクローン
• Hardlink（Linux/Windows）— ディスク容量を節約するハードリンク
• Copyfile（フォールバック）— 他の方法が利用できない場合の完全なファイルコピー

分離インストールのデバッグ

インストールプロセスを理解するために詳細ログを有効にします。

bun install --linker isolated --verbose

これにより、次のものが表示されます。

• ストアエントリーの作成
• シンボリックリンク操作
• ピア依存関係の解決
• 重複排除の決定

トラブルシューティング

互換性の問題

一部のパッケージは、次の理由で分離インストールで正しく動作しない可能性があります。

• ハードコードされたパス — フラットな node_modules 構造を想定するパッケージ
• 動的インポート — Node.js 解決に従わないランタイムインポート
• ビルドツール — node_modules を直接スキャンするツール

問題が発生した場合は、次のことができます。

1. 特定のプロジェクトで巻き上げモードに切り替え:

   bun install --linker hoisted

2. 互換性の問題を報告して、分離インストールのサポート向上に貢献

パフォーマンスの考慮事項

• インストール時間 — シンボリックリンク操作のため、わずかに遅くなる可能性があります
• ディスク使用量 — 巻き上げと同様（ファイルコピーではなくシンボリックリンクを使用）
• メモリ使用量 — 複雑なピア解決のため、インストール中に高くなります

移行ガイド

npm/Yarn から

# 既存の node_modules とロックファイルを削除
rm -rf node_modules package-lock.json yarn.lock

# 分離リンカでインストール
bun install --linker isolated

pnpm から

分離インストールは概念的に pnpm と似ているため、移行は簡単です。

# pnpm ファイルを削除
rm -rf node_modules pnpm-lock.yaml

# Bun の分離リンカでインストール
bun install --linker isolated

主な違いは、Bun が node_modules にシンボリックリンクを使用するのに対し、pnpm はシンボリックリンクを持つグローバルストアを使用することです。

分離インストールを使用する時期

分離インストールを使用する場合:

• 複数のパッケージを持つモノレポで作業する
• 厳格な依存関係管理が必要
• ファントム依存関係の防止が重要
• 決定論的依存関係が必要なライブラリを構築

巻き上げインストールを使用する場合:

• フラットな node_modules を想定するレガシーコードで作業する
• 既存のビルドツールとの互換性が必要
• シンボリックリンクが十分にサポートされていない環境で作業する
• よりシンプルな従来の npm 動作を好む

関連ドキュメント

• パッケージマネージャー > ワークスペース — モノレポワークスペース管理
• パッケージマネージャー > ロックファイル — Bun のロックファイル形式の理解
• CLI > install — 完全な bun install コマンドリファレンス