Каталоги

«Каталоги» — це функція робочого простору для визначення діапазонів версій залежностей як констант багаторазового використання. На константи, визначені в каталогах, пізніше можна посилатися у файлах 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.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 іншими робочими середовищами або менеджерами пакунків.

Застереження

Команда pnpm update поки що не підтримує каталоги.

Для оновлення залежностей, визначених у файлі pnpm-workspace.yaml, новіші діапазони версій потрібно вибирати вручну, доки це не буде реалізовано у наступній версії pnpm.