1---
2name: pnpm-config-dependencies
3description: Share and centralize pnpm hooks, settings, patches, catalogs, and overrides across repos via config dependencies
4---
5 
6# pnpm Config Dependencies
7 
8Config 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.
9 
10## Declaring config dependencies
11 
12They live in `pnpm-workspace.yaml`; their integrity is recorded in a dedicated env-lockfile document inside `pnpm-lock.yaml`.
13 
14```yaml title="pnpm-workspace.yaml"
15configDependencies:
16  my-configs: "1.0.0"
17```
18 
19Add one with the `--config` flag:
20 
21```bash
22pnpm add --config my-configs
23pnpm add --config @myorg/pnpm-plugin-my-catalogs
24```
25 
26## Constraints
27 
28- **No regular `dependencies`.** They may declare `optionalDependencies`, but only one level deep.
29- **No lifecycle scripts** (`preinstall`, `postinstall`, …).
30- `optionalDependencies` (used for platform-specific binaries, esbuild-style) must use **exact** versions — ranges/tags are rejected, keeping installs reproducible.
31 
32## Auto-loaded plugins
33 
34A config dependency named `pnpm-plugin-*`, `@*/pnpm-plugin-*`, or `@pnpm/plugin-*` has its `pnpmfile.mjs` (or `.cjs`) loaded automatically from the package root.
35 
36## Use cases
37 
38### Import hook logic from a shared package
39 
40Because config deps install before the pnpmfile loads, you can import from them:
41 
42```js title=".pnpmfile.mjs"
43import { readPackage } from '.pnpm-config/my-hooks'
44 
45export const hooks = { readPackage }
46```
47 
48### Share settings & catalogs via updateConfig
49 
50A plugin can inject settings/catalog entries through the `updateConfig` hook:
51 
52```js title="@myorg/pnpm-plugin-my-catalogs/pnpmfile.mjs"
53export const hooks = {
54  updateConfig(config) {
55    config.catalogs.default ??= {}
56    config.catalogs.default['is-odd'] = '1.0.0'
57    return config
58  }
59}
60```
61 
62After installing it as a config dependency, consumers can use the catalog:
63 
64```bash
65pnpm add is-odd@catalog:   # installs [email protected], writes "is-odd": "catalog:"
66```
67 
68### Share patch files
69 
70Reference patches stored inside a config dependency:
71 
72```yaml title="pnpm-workspace.yaml"
73configDependencies:
74  my-patches: "1.0.0"
75patchedDependencies:
76  react: "node_modules/.pnpm-config/my-patches/react.patch"
77```
78 
79## Key Points
80 
81- Centralize hooks, settings, catalogs, overrides, and patches in one package, consumed across repos.
82- Declared via `configDependencies` in `pnpm-workspace.yaml`; installed before regular deps.
83- No regular dependencies and no lifecycle scripts; `optionalDependencies` need exact versions.
84- `pnpm-plugin-*` / `@pnpm/plugin-*` packages auto-load their pnpmfile.
85- Pair with the `updateConfig` hook to push settings/catalogs into consuming projects.
86 
87<!--
88Source references:
89- https://pnpm.io/config-dependencies
90- https://pnpm.io/pnpmfile#hooksupdateconfigconfig-config--promiseconfig
91-->
92