Pnpm

name: pnpm-catalogs description: Centralized dependency version management for workspaces

pnpm Catalogs

Catalogs provide a centralized way to manage dependency versions across a workspace. Define versions once, use everywhere.

Basic Usage

Define a catalog in pnpm-workspace.yaml:

packages:
  - 'packages/*'

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
  typescript: ~5.3.0
  vite: ^5.0.0

Reference in package.json with catalog::

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vite": "catalog:"
  }
}

catalog: is shorthand for catalog:default. The catalog: protocol is valid in package.json dependencies, devDependencies, peerDependencies, and optionalDependencies, plus in overrides inside pnpm-workspace.yaml. It also works on the CLI: pnpm add react@catalog: and pnx shx@catalog:.

The default catalog can also be written as catalogs.default; defining both catalog and catalogs.default fails ("The 'default' catalog was defined multiple times").

Named Catalogs

Create multiple catalogs for different scenarios:

packages:
  - 'packages/*'

# Default catalog
catalog:
  lodash: ^4.17.21

# Named catalogs
catalogs:
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
  
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0
  
  testing:
    vitest: ^1.0.0
    "@testing-library/react": ^14.0.0

Reference named catalogs:

{
  "dependencies": {
    "react": "catalog:react18",
    "react-dom": "catalog:react18"
  },
  "devDependencies": {
    "vitest": "catalog:testing"
  }
}

Adding to a catalog from the CLI

pnpm add --save-catalog <dep> writes the range to the default catalog and catalog: to package.json; --save-catalog-name <name> picks a named catalog. catalogMode controls whether pnpm add does this without the flag.

Errors: ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC (no entry for the dep), ERR_PNPM_CATALOG_ENTRY_INVALID_RECURSIVE_DEFINITION (an entry is itself a catalog: reference).

workspace:, file:, and link: entries

A catalog entry may hold a workspace: range (v12.2.0), so the version a workspace dependency links by is defined once too. It expands to the range and links the project; on publish both protocols are replaced.

catalog:
  '@example/utils': workspace:^
  my-lib: link:./packages/my-lib     # v12.6.0; path measured from pnpm-workspace.yaml
  my-tarball: file:./tarballs/foo.tgz

Keeping overrides in sync with a catalog

Reference a catalog from overrides so the version lives in exactly one place:

catalog:
  foo: ^1.0.0

overrides:
  foo: 'catalog:'          # or catalog:<name>

Settings

# How `pnpm add` interacts with the default catalog (v10.12+)
catalogMode: manual        # manual (default) | prefer | strict
# strict: only catalog versions allowed; prefer: fall back if no match
catalogPrune: true         # remove unused catalog entries on install (v11.22+; was cleanupUnusedCatalogs)

Benefits

1. Single source of truth: Update version in one place

2. Consistency: All packages use the same version

3. Easy upgrades: Change version once, affects entire workspace

4. Fewer merge conflicts: package.json files stay untouched on upgrades

Catalog vs Overrides

Publishing with Catalogs

When publishing, catalog: references are replaced with actual versions:

// Before publish (source)
{
  "dependencies": {
    "react": "catalog:"
  }
}

// After publish (published package)
{
  "dependencies": {
    "react": "^18.2.0"
  }
}

Migration from Overrides

If you're using overrides for version consistency:

# Before (using overrides)
overrides:
  react: ^18.2.0
  react-dom: ^18.2.0

Migrate to catalogs for cleaner dependency management:

# After (using catalogs)
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

Then update package.json files to use catalog:. To migrate an existing workspace automatically:

pnpx codemod pnpm/catalog

Best Practices

1. Use default catalog for commonly shared dependencies

2. Use named catalogs for version variants (e.g., different React versions)

3. Keep catalog minimal - only include shared dependencies

4. Combine with workspace protocol for internal packages

catalog:
  # External shared dependencies
  lodash: ^4.17.21
  zod: ^3.22.0

# Internal packages use workspace: protocol instead
# "dependencies": { "@myorg/utils": "workspace:^" }

<!-- Source references: - https://pnpm.io/catalogs -->