/pnpm

pnpm Config Dependencies

Config dependencies are npm packages that pnpm installs before all regular dependencies, so they can supply hooks, settings, patches, catalogs, and overrides that are reused across many repositories. They let you keep one shared "pnpm config" package and consume it everywhere.

Declaring config dependencies

They live in pnpm-workspace.yaml; their integrity is recorded in a dedicated env-lockfile document inside pnpm-lock.yaml.

configDependencies:
  my-configs: "1.0.0"

Add one with the --config flag:

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

Constraints

• No regular dependencies. They may declare optionalDependencies, but only one level deep.
• No lifecycle scripts (preinstall, postinstall, …).
• optionalDependencies (used for platform-specific binaries, esbuild-style) must use exact versions — ranges/tags are rejected, keeping installs reproducible.

Auto-loaded plugins

A config dependency named pnpm-plugin-*, @*/pnpm-plugin-*, or @pnpm/plugin-* has its pnpmfile.mjs (or .cjs) loaded automatically from the package root.

Use cases

Import hook logic from a shared package

Because config deps install before the pnpmfile loads, you can import from them:

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

export const hooks = { readPackage }

Share settings & catalogs via updateConfig

A plugin can inject settings/catalog entries through the updateConfig hook:

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

After installing it as a config dependency, consumers can use the catalog:

pnpm add is-odd@catalog:   # installs is-odd@1.0.0, writes "is-odd": "catalog:"

Share patch files

Reference patches stored inside a config dependency:

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

Key Points

• Centralize hooks, settings, catalogs, overrides, and patches in one package, consumed across repos.
• Declared via configDependencies in pnpm-workspace.yaml; installed before regular deps.
• No regular dependencies and no lifecycle scripts; optionalDependencies need exact versions.
• pnpm-plugin-* / @pnpm/plugin-* packages auto-load their pnpmfile.
• Pair with the updateConfig hook to push settings/catalogs into consuming projects.