bun-package-manager

Bun Package Manager

Bun のパッケージマネージャーは、npm、yarn、pnpm を大幅に高速化した代替ツールです。npm install より最大 25 倍高速です。

クイックスタート

# Install all dependencies
bun install

# Add packages
bun add react react-dom
bun add -D typescript @types/react

# Remove packages
bun remove lodash

# Update packages
bun update

# Run package binaries
bunx create-next-app

基本コマンド

コマンド	説明
bun install	すべての依存関係をインストール
bun add <pkg>	依存関係を追加
bun add -D <pkg>	開発用依存関係を追加
bun add -O <pkg>	オプションの依存関係を追加
bun add --peer <pkg>	peer 依存関係を追加
bun remove <pkg>	依存関係を削除
bun update [pkg]	依存関係を更新
bunx <pkg>	パッケージのバイナリを実行
bun pm cache rm	キャッシュをクリア

インストールフラグ

# Production mode (no devDependencies)
bun install --production

# Frozen lockfile (CI/CD)
bun install --frozen-lockfile
bun ci  # shorthand

# Dry run
bun install --dry-run

# Verbose/Silent
bun install --verbose
bun install --silent

# Force reinstall
bun install --force

# Global packages
bun install -g cowsay

ロックファイル

Bun は bun.lock を使用します（v1.2 以降はテキスト形式です）。

# Generate text lockfile
bun install --save-text-lockfile

# Upgrade from binary bun.lockb
bun install --save-text-lockfile --frozen-lockfile --lockfile-only
rm bun.lockb

ワークスペース（モノレポ）

{
  "name": "my-monorepo",
  "workspaces": ["packages/*", "apps/*"]
}

ワークスペース全体でコマンドを実行します。

# Run in matching packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

# Install for specific packages
bun install --filter 'pkg-a'

ライフサイクルスクリプト

Bun はセキュリティ上の理由から、依存関係のライフサイクルスクリプトをデフォルトでは実行しません。信頼できるパッケージを許可リストに追加します。

{
  "trustedDependencies": ["my-trusted-package"]
}

# Skip all lifecycle scripts
bun install --ignore-scripts

# Concurrent scripts
bun install --concurrent-scripts 5

オーバーライドと解決設定

ネストされた依存関係に特定のバージョンを強制的に適用します。

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Yarn 形式の解決設定にも対応しています。

{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

npm 以外の依存関係

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

インストール方式

Bun 1.3 以降のデフォルト変更：Bun 1.3 以降、isolated はワークスペースのデフォルトです（パッケージは、hoist されたルートの node_modules を介して、宣言されていない依存関係にアクセスできなくなります）。hoisted は現在、従来方式へのオプトアウトです。ワークスペースのパッケージが、宣言していない推移的依存関係に依存している場合にのみ使用してください。

Hoisted（従来方式へのオプトアウト。ワークスペースを使用しない単一パッケージでは引き続きデフォルト）

従来のフラットな node_modules 方式です。

bun install --linker hoisted

Isolated（Bun 1.3 以降のワークスペースでデフォルト）

pnpm のような厳格な分離方式です。

bun install --linker isolated

Isolated では「ファントム依存関係」を防ぎ、パッケージは宣言済みの依存関係にのみアクセスできます。この設定を明示する場合や、オプトアウト後に元に戻す場合は、bunfig.toml で設定します。

[install]
linker = "isolated"   # default for workspaces in Bun 1.3+
# linker = "hoisted"  # legacy opt-out

CI/CD

# GitHub Actions
- uses: oven-sh/setup-bun@v2
- run: bun ci  # frozen lockfile

プラットフォーム固有の設定

# Install for different platform
bun install --cpu=x64 --os=linux

安全なインストール

パッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロックする — Bun はデフォルトでスクリプトを無効にします。package.json の trustedDependencies で特定のパッケージを許可できます。
• クールダウン期間 — bunfig.toml で minimumReleaseAge を設定し、新しいバージョンの公開から 7 日間待機します。
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用して、パッケージがプロジェクトに取り込まれる前に確認します。

Socket CLI との統合、クールダウンの設定、ロックファイルの検証、CI での適用など、セキュリティ設定の詳細については dependency-upgrade スキルを読み込んでください。

よくあるエラー

エラー	原因	対処方法
Cannot find module	依存関係が不足しています	bun install を実行します
Lockfile mismatch	package.json が変更されました	bun install を実行します
Peer dependency	peer 依存関係が不足しています	bun add で peer 依存関係を追加します
Lifecycle script failed	信頼されていないパッケージです	trustedDependencies に追加します

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

pnpm からの移行

Bun は pnpm-lock.yaml を自動的に移行します。

bun install  # Auto-converts to bun.lock

ワークスペースの設定は package.json に移動します。

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0"
    }
  }
}

npm/Yarn からの移行

bun install を実行するだけで、Bun が package-lock.json と yarn.lock を読み込みます。

リファレンスを読み込むタイミング

次の場合は references/cli-commands.md を読み込みます。

• CLI フラグの完全なリファレンスが必要な場合
• 高度なオプションを使用する場合

次の場合は references/workspaces.md を読み込みます。

• モノレポを設定する場合
• ワークスペースフィルターを設定する場合

次の場合は references/migration.md を読み込みます。

• npm/yarn/pnpm から移行する場合
• ロックファイルを変換する場合