Bun のカタログは、モノレポ内の複数のパッケージで共通の依存関係バージョンを共有する簡単な方法を提供します。各ワークスペースパッケージで同じバージョンを繰り返し指定するのではなく、ルート package.json で一度定義し、プロジェクト全体で一貫して参照できます。

概要

各ワークスペースパッケージが独立してバージョンを指定する従来の依存関係管理とは異なり、カタログでは次のことが可能です。

1. ルート package.json でバージョンカタログを定義する
2. 簡単な catalog: プロトコルでこれらのバージョンを参照する
3. 1 か所の変更だけで、すべてのパッケージを同時に更新する

これは、数十のパッケージが主要な依存関係の同じバージョンを使用する必要がある大規模なモノレポで特に役立ちます。

使用方法

ディレクトリ構造の例

次の構造を持つモノレポを考えます。

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. ルート package.json でカタログを定義する

ルートレベルの package.json で、workspaces オブジェクト内に catalog または catalogs フィールドを追加します。

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

catalog または catalogs を package.json ファイルのトップレベルに配置することもできます。

2. ワークスペースパッケージでカタログバージョンを参照する

ワークスペースパッケージでは、catalog: プロトコルを使用してバージョンを参照します。

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. Bun install を実行する

bun install を実行して、カタログバージョンに従ってすべての依存関係をインストールします。

Catalog と Catalogs

Bun はカタログを定義する 2 つの方法をサポートしています。

1. catalog (単数形): 一般的に使用される依存関係のための単一のデフォルトカタログ

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   単に catalog: で参照します。

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs (複数形): 依存関係をグループ化するための複数の名前付きカタログ

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   catalog:<name> で参照します。

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

カタログを使用する利点

• 一貫性: すべてのパッケージが重要な依存関係の同じバージョンを使用することを保証します
• メンテナンス: 複数の package.json ファイル全体ではなく、1 か所で依存関係のバージョンを更新できます
• 明確性: モノレポ全体で標準化されている依存関係が明確になります
• シンプルさ: 複雑なバージョン解決戦略や外部ツールは不要です

実世界の例

React アプリケーションのより包括的な例を次に示します。

ルート package.json

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

バージョンの更新

すべてのパッケージのバージョンを更新するには、ルート package.json のバージョンを変更するだけです。

"catalog": {
  "react": "^19.1.0",  // ^19.0.0 から更新
  "react-dom": "^19.1.0"  // ^19.0.0 から更新
}

その後、bun install を実行してすべてのパッケージを更新します。

ロックファイルとの統合

Bun のロックファイルはカタログバージョンを追跡し、異なる環境間で一貫したインストールを簡単に保証します。ロックファイルには次のものが含まれます。

• package.json からのカタログ定義
• 各カタログ化された依存関係の解決

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

制限とエッジケース

• カタログ参照は、catalog または名前付き catalogs のいずれかで定義された依存関係と一致する必要があります
• カタログ名の空文字列と空白は無視されます（デフォルトのカタログとして扱われます）
• カタログ内の無効な依存関係バージョンは、bun install 中に解決に失敗します
• カタログはワークスペース内でのみ利用可能で、モノレポ外では使用できません

Bun のカタログシステムは、ワークフローに追加の複雑さを導入することなく、モノレポ全体で一貫性を維持する強力でシンプルな方法を提供します。

パブリッシュ

bun publish または bun pm pack を実行すると、Bun は自動的に package.json 内の catalog: 参照を解決されたバージョン番号に置き換えます。 公開されるパッケージには通常のセマンティックバージョン文字列が含まれ、 カタログ定義には依存しなくなります。