"Catalogs" are aworkspace feature for defining dependency version ranges as reusable constants. Constants defined in catalogs can later be referenced inpackage.json files.

The Catalog Protocol (catalog:)​

Once a catalog is defined inpnpm-workspace.yaml,

packages:
- packages/*

# Define a catalog of version ranges.
catalog:
react: ^18.3.1
redux: ^5.0.1

Thecatalog: protocol can be used instead of the version range itself.

{
"name":"@example/app",
"dependencies":{
"react":"catalog:",
"redux":"catalog:"
}
}

This is equivalent to writing a version range (e.g.^18.3.1) directly.

{
"name":"@example/app",
"dependencies":{
"react":"^18.3.1",
"redux":"^5.0.1"
}
}

You may use thecatalog: protocol in the next fields of yourpackage.json:

• dependencies
• devDependencies
• peerDependencies
• optionalDependencies
• pnpm.overrides

Thecatalog: protocol allows an optional name after the colon (ex:catalog:name) to specify which catalog should be used. When a name is omitted, the default catalog is used.

Depending on the scenario, thecatalog: protocol offers a fewadvantages compared to writing version ranges directly that are detailed next.

Advantages​

In a workspace (i.e. monorepo or multi-package repo) it's common for the same dependency to be used by many packages. Catalogs reduce duplication when authoringpackage.json files and provide a few benefits in doing so:

• Maintain unique versions — It's usually desirable to have only one version of a dependency in a workspace. Catalogs make this easier to maintain. Duplicated dependencies can conflict at runtime and cause bugs. Duplicates also increase size when using a bundler.
• Easier upgrades — When upgrading a dependency, only the catalog entry inpnpm-workspace.yaml needs to be edited rather than allpackage.json files using that dependency. This saves time — only one line needs to be changed instead of many.
• Fewer merge conflicts — Sincepackage.json files do not need to be edited when upgrading a dependency, git merge conflicts no longer happen in these files.

Defining Catalogs​

Catalogs are defined in thepnpm-workspace.yaml file. There are two ways to define catalogs.

1. Using the (singular)catalog field to create a catalog nameddefault.
2. Using the (plural)catalogs field to create arbitrarily named catalogs.

pnpx codemod pnpm/catalog

Default Catalog​

The top-levelcatalog field allows users to define a catalog nameddefault.

catalog:
react: ^18.2.0
react-dom: ^18.2.0

These version ranges can be referenced throughcatalog:default. For the default catalog only, a specialcatalog: shorthand can also be used. Think ofcatalog: as a shorthand that expands tocatalog:default.

Named Catalogs​

Multiple catalogs with arbitrarily chosen names can be configured under thecatalogs key.

catalogs:
# Can be referenced through "catalog:react17"
react17:
react: ^17.0.2
react-dom: ^17.0.2

# Can be referenced through "catalog:react18"
react18:
react: ^18.2.0
react-dom: ^18.2.0

A default catalog can be defined alongside multiple named catalogs. This might be useful in a large multi-package repo that's migrating to a newer version of a dependency piecemeal.

catalog:
react: ^16.14.0
react-dom: ^16.14.0

catalogs:
# Can be referenced through "catalog:react17"
react17:
react: ^17.0.2
react-dom: ^17.0.2

# Can be referenced through "catalog:react18"
react18:
react: ^18.2.0
react-dom: ^18.2.0

Publishing​

Thecatalog: protocol is removed when runningpnpm publish orpnpm pack. This is similar to theworkspace: protocol, which isalso replaced on publish.

Por ejemplo,

{
"name":"@example/components",
"dependencies":{
"react":"catalog:react18",
}
}

Will become the following on publish.

{
"name":"@example/components",
"dependencies":{
"react":"^18.3.1",
}
}

Thecatalog: protocol replacement process allows the@example/components package to be used by other workspaces or package managers.

Caveats​

Thepnpm update command does not yet support catalogs.

To update dependencies defined inpnpm-workspace.yaml, newer version ranges will need to be chosen manually until a future version of pnpm handles this.