Конфігураційні залежності

Конфігураційні залежності дозволяють вам ділитися і централізовано використовувати конфігураційні файли, налаштування і хуки в декількох проєктах. Вони встановлюються перед усіма звичайними залежностями ("dependencies", "devDependencies", "optionalDependencies"), що робить їх ідеальними для налаштування власних хуків, патчів і записів у каталогах.

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

If your config dependency is named following the pnpm-plugin-*, @*/pnpm-plugin-*, or @pnpm/plugin-* pattern, pnpm will automatically load its pnpmfile.mjs (falling back to pnpmfile.cjs) from the package root.

Як додати конфігураційну залежність

Config dependencies are defined in your pnpm-workspace.yaml. Their integrity checksums are stored in pnpm-lock.yaml (in a dedicated env lockfile document).

Наприклад, виконання команди pnpm add --config my-configs додасть цей запис до вашого файлу pnpm-workspace.yaml:

pnpm-workspace.yaml

configDependencies:
  my-configs: "1.0.0"

Важливо:

• Config dependencies cannot have their own regular dependencies. They can declare optionalDependencies, but only one level deep — optionalDependencies of optionalDependencies are ignored.
• Конфігураційні залежності не можуть визначати сценарії життєвого циклу (наприклад, preinstall, postinstall тощо).

Platform-specific binaries via optionalDependencies

A config dependency may ship platform-specific binaries via optionalDependencies, the same pattern used by tools like esbuild and swc. Each platform-binary package declares its supported platform with os, cpu, and/or libc fields, and pnpm installs only the variant that matches the current host. The matching binary is symlinked next to the parent config dependency in the global virtual store, so require('my-config-platform-arch') from inside the config dependency resolves at runtime.

The env lockfile records all platform variants regardless of host platform, so the lockfile stays portable across machines.

Each entry in optionalDependencies must be declared with an exact version (e.g. "1.2.3") — ranges ("^1.0.0", "~1.0.0") and tags ("latest") are rejected. This keeps config-dep installs reproducible: the resolved subdep can't drift between machines for a parent that's pinned by integrity.

Використання

Встановлення залежностей, що використовуються в хуках

Конфігураційні залежності встановлюються перед завантаженням хуків з вашого .pnpmfile.mjs, що дозволяє вам імпортувати логіку з конфігураційних пакунків.

Приклад:

.pnpmfile.mjs

import { readPackage } from '.pnpm-config/my-hooks'

export const hooks = {
  readPackage
}

Динамічне оновлення налаштувань pnpm

За допомогою хука updateConfig ви можете динамічно оновлювати налаштування pnpm за допомогою конфігураційних залежностей.

Наприклад, наступний pnpmfile додає новий запис catalog до конфігурації pnpm:

@myorg/pnpm-plugin-my-catalogs/pnpmfile.mjs

export const hooks = {
  updateConfig (config) {
    config.catalogs.default ??= {}
    config.catalogs.default['is-odd'] = '1.0.0'
    return config
  }
}

Якщо ви встановлюєте його як конфігураційну залежність:

pnpm add --config @myorg/pnpm-plugin-my-catalogs

Потім можна виконати команду:

pnpm add is-odd@catalog:

Вона встановить is-odd@1.0.0 і додасть наступне до вашого package.json:

{
  "dependencies": {
    "is-odd": "catalog:"
  }
}

Це спрощує підтримку та обмін централізованими версіями конфігурації та залежностей між проєктами.

Завантаження патчів

Ви можете посилатися на файли виправлень, що зберігаються у конфігураційних залежностях.

Приклад:

pnpm-workspace.yaml

configDependencies:
  my-patches: "1.0.0"
patchedDependencies:
  react: "node_modules/.pnpm-config/my-patches/react.patch"