Каталоги в Bun предоставляют простой способ обмена общими версиями зависимостей между несколькими пакетами в монорепозитории. Вместо того чтобы указывать одни и те же версии многократно в каждом пакете рабочей области, вы определяете их один раз в корневом package.json и ссылаетесь на них последовательно во всем проекте.

Обзор

В отличие от традиционного управления зависимостями, где каждый пакет рабочей области должен независимо указывать версии, каталоги позволяют:

1. Определять каталоги версий в корневом package.json
2. Ссылаться на эти версии с помощью простого протокола catalog:
3. Обновлять все пакеты одновременно, изменяя версию только в одном месте

Это особенно полезно в больших монорепозиториях, где десятки пакетов должны использовать одну и ту же версию ключевых зависимостей.

Как использовать каталоги

Пример структуры каталогов

Рассмотрим монорепозиторий со следующей структурой:

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

1. Определение каталогов в корневом package.json

В корневом файле package.json добавьте поле catalog или catalogs внутри объекта workspaces:

{
  "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

Выполните bun install для установки всех зависимостей согласно версиям каталогов.

Catalog против Catalogs

Bun поддерживает два способа определения каталогов:

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
• Ясность: Делает очевидным, какие зависимости стандартизированы в вашем монорепозитории
• Простота: Не требуется сложных стратегий разрешения версий или внешних инструментов

Пример из реальной жизни

Вот более полный пример для приложения 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 автоматически заменяет ссылки catalog: в вашем package.json на разрешенные номера версий. Опубликованный пакет включает обычные строки semver и больше не зависит от ваших определений каталогов.