Skip to main content

Catalogs

Overview​

Catalogs provide centralized dependency version management for workspaces. Inspired by pnpm's catalog functionality, they allow you to define version ranges in your .yarnrc.yml and reference them across multiple package.json files using the catalog: protocol.

This eliminates version duplication, ensures consistency across packages, and makes dependency upgrades much simpler — update one place instead of many files.

info

The catalog plugin is included by default starting from Yarn 4.10.0.

Basic usage​

Define a catalog in your .yarnrc.yml:

catalog:
  react: ^18.3.1
  lodash: ^4.17.21

Reference entries in your package.json:

{
  "dependencies": {
    "react": "catalog:",
    "lodash": "catalog:"
  }
}

Named catalogs​

You can define multiple named catalogs using the catalogs field for different purposes:

catalog:
  lodash: ^4.17.21

catalogs:
  react18:
    react: ^18.3.1
    react-dom: ^18.3.1
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

Reference named catalogs by specifying the name:

{
  "dependencies": {
    "lodash": "catalog:",
    "react": "catalog:react18"
  }
}

Publishing​

When publishing packages, the catalog: protocol is automatically replaced with actual version ranges, ensuring compatibility with other package managers:

// Source package.json
{
  "dependencies": {
    "react": "catalog:react18"
  }
}

// Published package.json
{
  "dependencies": {
    "react": "^18.3.1"
  }
}

Supported fields​

The catalog: protocol works in dependencies, devDependencies, peerDependencies.