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

Конфігураційні залежності дозволяють вам ділитися і централізовано використовувати конфігураційні файли, налаштування і хуки в декількох проєктах. Вони встановлюються перед усіма звичайними залежностями ("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 must come from an npm registry. pnpm verifies them against their registry before installing them, so installing a new or changed config dependency offline requires cached registry metadata. A config dependency pinned with version+integrity keeps that integrity as its pin. minimumReleaseAge applies to config dependencies that are not pinned with version+integrity. pnpm installs them before any updateConfig hook runs, so a minimumReleaseAgeExclude entry added by a hook does not cover them.

Removing a package from configDependencies removes its installed link and unused lockfile entries on the next pnpm install. This also applies when you remove the entire setting. Run without --frozen-lockfile to update the lockfile after changing the declarations.

How to add a config dependency#

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:

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.

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

Installing dependencies used in hooks#

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

Приклад:

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

export const hooks = {
  readPackage
}

Updating pnpm settings dynamically#

Using the updateConfig hook, you can dynamically update pnpm's settings using config dependencies.

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

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:"
  }
}

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

Loading patch files#

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

Приклад:

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