Каталоги

«Каталоги» — це функція робочого простору для визначення діапазонів версій залежностей як констант багаторазового використання. На константи, визначені в каталогах, пізніше можна посилатися у файлах package.json.

The catalog protocol (catalog:)#

Після визначення каталогу у файлі pnpm-workspace.yaml,

packages:
  - packages/*

# Визначає каталог діапазонів версій.
catalog:
  react: ^18.3.1
  redux: ^5.0.1

Замість самого діапазону версій можна використовувати протокол catalog:.

{
  "name": "@example/app",
  "dependencies": {
    "react": "catalog:",
    "redux": "catalog:"
  }
}

Це еквівалентно написанню діапазону версій (наприклад, ^18.3.1) безпосередньо.

{
  "name": "@example/app",
  "dependencies": {
    "react": "^18.3.1",
    "redux": "^5.0.1"
  }
}

Ви можете використовувати протокол catalog: у наступних полях:

• package.json:
  • dependencies
  • devDependencies
  • peerDependencies
  • optionalDependencies
• pnpm-workspace.yaml
  • overrides

Протокол catalog: дозволяє вказувати необовʼязкову назву після двокрапки (наприклад: catalog:name), щоб вказати, який каталог слід використовувати. Якщо назву не вказано, використовується стандартний каталог.

Залежно від сценарію, протокол catalog: має декілька переваг порівняно з безпосереднім записом діапазонів версій, які детально описано далі.

Переваги#

У робочому просторі (наприклад, монорепо або багатопакетному репо) зазвичай одна і та ж залежність використовується багатьма пакунками. Каталоги зменшують дублювання при створенні файлів package.json і надають кілька переваг при цьому:

• Maintain unique versions: It's usually desirable to have only one version of a dependency in a workspace. Каталоги полегшують цю роботу. Дубльовані залежності можуть конфліктувати під час виконання і спричиняти помилки. Дублікати також збільшують розмір при використанні bundler.
• Easier upgrades: When upgrading a dependency, only the catalog entry in pnpm-workspace.yaml needs to be edited rather than all package.json files using that dependency. This saves time. Only one line needs to be changed instead of many.
• Fewer merge conflicts: Since package.json files do not need to be edited when upgrading a dependency, git merge conflicts no longer happen in these files.

Defining catalogs#

Каталоги визначаються у файлі "pnpm-workspace.yaml". Існує два способи визначення каталогів.

1. За допомогою поля (в однині) catalog створити каталог з назвою default.
2. Використання поля (множина) catalogs для створення каталогів з довільними назвами.

pnpx codemod pnpm/catalog

Default catalog#

Поле верхнього рівня catalog дозволяє користувачам визначити каталог з назвою default.

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

На ці діапазони версій можна посилатися через catalog:default. Тільки для стандартного каталогу можна також використовувати спеціальне скорочення catalog:. Вважайте catalog: як скорочення, яке розширюється до catalog:default.

Named catalogs#

За допомогою ключа catalogs можна налаштувати декілька каталогів з довільно вибраними іменами.

catalogs:
  # Можна посилатися через "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Можна посилатися через "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

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

catalog:
  react: ^16.14.0
  react-dom: ^16.14.0

catalogs:
  # Можна посилатися через "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Можна посилатися через "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

Workspace dependencies in a catalog#

Added in: v11.26.0

A catalog entry may hold a workspace: range, so the version a workspace dependency is linked by is written once too:

catalog:
  '@example/utils': workspace:^

{
  "name": "@example/app",
  "dependencies": {
    "@example/utils": "catalog:"
  }
}

pnpm expands the catalog: reference to workspace:^ and then links the workspace project, exactly as if the package.json had declared workspace:^ itself. On publish both protocols are replaced, so the example above ships as "^1.4.0" when @example/utils is at 1.4.0.

Публікування#

Протокол catalog: вилучається під час виконання pnpm publish або pnpm pack. Це схоже на протокол workspace:, який також замінюється при публікації.

Наприклад,

{
  "name": "@example/components",
  "dependencies": {
    "react": "catalog:react18"
  }
}

Після публікації стане наступним.

{
  "name": "@example/components",
  "dependencies": {
    "react": "^18.3.1"
  }
}

Процес заміни протоколу catalog: дозволяє використовувати пакунок @example/components іншими робочими середовищами або менеджерами пакунків.

Налаштування#

catalogMode#

Додано у: v10.12.1

• Стандартно: manual
• Тип: manual, strict, prefer

Керує тим, чи додаються залежності до стандартного каталогу при виконанні pnpm add, і якщо так, то як саме. Є три режими:

• strict — дозволяє лише версії залежностей з каталогу. Додавання залежності за межами діапазону версій каталогу призведе до помилки.
• prefer — надає перевагу версіям з каталогу, але повертається до прямих залежностей, якщо сумісну версію не знайдено.
• manual (стандартно) — не додає автоматично залежності до каталогу.

Since v11.26.0, a specifier that names a location rather than a version is never moved into a catalog: local paths, local tarballs, tarball URLs, and workspace:<path> ranges stay in the package.json that declares them. Such a specifier is resolved relative to its own project, so one catalog entry could not mean the same directory for every project that references it.

catalogPrune#

Додано у версії: v11.22.0 (як cleanupUnusedCatalogs починаючи з версії v10.15.0)

• Стандартно: false
• Тип: Boolean

Якщо встановлено значення 'true', pnpm видалить невикористані записи каталогів під час встановлення.

cleanupUnusedCatalogs — це застарілий варіант назви цього параметра, який продовжує працювати; якщо задано обидва параметри, пріоритет має catalogPrune.