Config Dependencies

Config dependencies allow you to share and centralize configuration files, settings, and hooks across multiple projects. They are installed before all regular dependencies ("dependencies", "devDependencies", "optionalDependencies"), making them ideal for setting up custom hooks, patches, and catalog entries.

Config dependencies help you keep all the hooks, settings, patches, overrides, catalogs, rules in a single place and use them across multiple repositories.

How to Add a Config Dependency

Config dependencies are defined in your pnpm-workspace.yaml and must be installed using an exact version and an integrity checksum.

Приклад:

pnpm-workspace.yaml

configDependencies:
  my-configs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="

Important:

• Config dependencies cannot have their own dependencies.
• Config dependencies cannot define lifecycle scripts (like preinstall, postinstall, etc.).

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

Loading an Allow List of Built Dependencies

You can load a list of package names that are allowed to be built, using the onlyBuiltDependenciesFile setting.

Example allow.json file inside a config dependency:

allow.json

[
  "esbuild",
  "fsevents"
]

Your workspace configuration:

pnpm-workspace.yaml

configDependencies:
  my-configs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
onlyBuiltDependenciesFile: "node_modules/.pnpm-config/my-configs/allow.json"

Installing Dependencies Used in Hooks

Config dependencies are installed before hooks from your .pnpmfile.cjs are loaded, allowing you to import logic from config packages.

Приклад:

.pnpmfile.cjs

const { readPackage } = require('.pnpm-config/my-hooks')

module.exports = {
  hooks: {
    readPackage
  }
}

Updating pnpm Settings Dynamically

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

For example, the following pnpmfile adds a new catalog entry to pnpm's configuration:

my-catalogs/pnpmfile.cjs

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

Install and load it:

pnpm-workspace.yaml

configDependencies:
  my-catalogs: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
pnpmfile: "node_modules/.pnpm-config/my-catalogs/pnpmfile.cjs"

Then you can run:

pnpm add is-odd@catalog:

This will install is-odd@1.0.0 and add the following to your package.json:

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

This makes it easy to maintain and share centralized configuration and dependency versions across projects.

Loading Patch Files

You can reference patch files stored inside config dependencies.

Приклад:

pnpm-workspace.yaml

configDependencies:
  my-patches: "1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="
patchedDependencies:
  react: "node_modules/.pnpm-config/my-patches/react.patch"