配置依赖项

配置依赖项允许你在多个项目之间共享和集中配置文件、设置和钩子。 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.

If your config dependency is named following the pnpm-plugin-* or @*/pnpm-plugin-* pattern, pnpm will automatically load the pnpmfile.cjs from its root.

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.

For example, running pnpm add --config my-configs will add this entry to your pnpm-workspace.yaml:

pnpm-workspace.yaml

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

重要：

• 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

[
  "@airbnb/node-memwatch",
  "@apollo/protobufjs",
  ...
]

Your workspace configuration:

pnpm-workspace.yaml

configDependencies:
  '@myorg/trusted-deps': 0.1.0+sha512-IERT0uXPBnSZGsCmoSuPzYNWhXWWnKkuc9q78KzLdmDWJhnrmvc7N4qaHJmaNKIusdCH2riO3iE34Osohj6n8w==
onlyBuiltDependenciesFile: node_modules/.pnpm-config/@myorg/trusted-deps/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:

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

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

If you install it as config dependency:

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

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.

加载补丁文件

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"