Каталоги

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

Протокол каталогу (catalog:)

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

pnpm-workspace.yaml

packages:
  - packages/*

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

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

packages/example-app/package.json

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

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

packages/example-app/package.json

{
  "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 і надають кілька переваг при цьому:

• Зберігайте унікальні версії — Зазвичай бажано мати лише одну версію залежності у робочій області. Каталоги полегшують цю роботу. Дубльовані залежності можуть конфліктувати під час виконання і спричиняти помилки. Дублікати також збільшують розмір при використанні bundler.
• Простіше оновлення — Під час оновлення залежності потрібно редагувати лише запис каталогу у файлі pnpm-workspace.yaml, а не всі файли package.json, що використовують цю залежність. Це економить час — потрібно змінити лише один рядок замість багатьох.
• Менше конфліктів злиття — Оскільки файли package.json не потрібно редагувати при оновленні залежностей, конфлікти злиття git більше не виникають у цих файлах.

Визначення каталогів

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

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

підказка

Якщо у вас є робоче середовище, до якого ви хочете перейти за допомогою каталогів, ви можете скористатися наступним codemod:

pnpx codemod pnpm/catalog

Стандартний каталог

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

pnpm-workspace.yaml

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

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

Іменовані каталоги

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

pnpm-workspace.yaml

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

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

pnpm-workspace.yaml

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

Публікація

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

Наприклад,

packages/example-components/package.json

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

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

packages/example-components/package.json

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

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

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

catalogMode

Додано у: v10.12.1

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

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

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

cleanupUnusedCatalogs

Додано у: v10.15.0

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

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