pnpm 9.5 Introduces Catalogs: Shareable Dependency Version Specifiers

pnpm is eight years into its unique approach to package management, and continues to gain traction, especially among those who need efficiency and support for monorepo setups. Contributors to the project have released the highly anticipated version 9.5 over the weekend. This update includes the new Catalogs feature, which has been in discussion as an RFC since 2022.

A previous version of the RFC for Catalogs was titled: “First-Class Support for Workspace Consistent Versions,” but was renamed to Catalogs, inspired by a similar idea from the Gradle build tool, which allows for a central declaration of dependencies through the creation of a version catalog.

pnpm contributor Brandon Cheng, who implemented the feature, along with other members of the community, thought it would be useful to be able to share workspace consistent versions through the npm registry. The new Catalogs feature allows multiple package.json files to share the same version specifier of a dependency through a new catalog: protocol.

“We thought the idea of ‘sharing’ package.json files could be extended just a bit further to solve many other pnpm feature requests,” Cheng said. “This eventually became ‘Templates’ and was proposed as RFC: Templates - Reusable packages to share dependencies and configuration.” Catalogs matured independently of Templates as a first-class concept for sharing version specifiers.

As of version 9.5, pnpm users can now declare catalogs in the pnpm-workspace.yaml file, as outlined in the release notes:

# Default catalogs
catalog:
  chalk: ^4.1.2

# Named catalogs
catalogs:
  react16:
    react: ^16.7.0
    react-dom: ^16.7.0
  react17:
    react: ^17.10.0
    react-dom: ^17.10.0

The catalog: protocol is then used in package.json files to reference a "default" or "named" catalog.

There are also changes coming to the add and update commands in future releases:

• The pnpm add command will add versions from the default catalog if it's configured.
• The pnpm update command will prompt users if they wish to update specifiers in a catalog.

The pnpm update command does not yet support catalogs in the 9.5 release. In the meantime, updating dependencies defined in pnpm-workspace.yaml will require specifying newer version ranges manually until pnpm handles this.

The Catalog Feature Is a Product Distinction for pnpm#

Cheng noted that pnpm isn’t the first package manager to implement the workspace: protocol - it was originally a feature of Yarn v2. Catalogs take it a step further as a product distinction for pnpm. It works in a similar way to the workspace: protocol in that pnpm publish will need to replace instances of catalog: with valid specifiers before publishing.

“From my perspective, the answer is a strong ‘yes, it adds significant product value to build this into package.json and pnpm,” he said. “Catalogs give another reason for users to choose pnpm if there’s built-in support.

“My opinion is a bit biased from working heavily in huge monorepos day to day, but I do personally believe catalogs are a feature that uniquely boosts pnpm, and substantially. In the last few years, pnpm has shown that it scales much better than its alternatives.”

A few factors and motivations influencing the addition of the catalogs feature are outlined in the RFC:

• Synchronization: A common workflow in monorepos is the need to synchronize on the same version of a dependency.
• Merge Conflict Resistance: In addition to reducing the likelihood of multiple versions of the same dependency in a monorepo, the new catalog: protocol reduces merge conflicts, a primary motivator for introducing it as a first-class feature. Any package.json files using the catalog protocol to declare a dependency do not need to be edited when changing the version of that dependency. This side steps package.json merge conflicts by avoiding edits to them in the first place.

Catalogs has so far received positive feedback with strong buy-in from the community, as many pnpm users have been eagerly awaiting this feature. Users have commented on the painful experience of maintaining consistent versions in a monorepo. Some have even attempted to cobble together their own solutions involving strictly pinning every workspace package’s dependencies to one version and other unsustainable workarounds.

The Catalogs feature suits these use cases and significantly reduces maintenance overhead, making it easier to maintain unique versions of a dependency. It enables easier upgrades with fewer merge conflicts. Check out the documentation for more details on how it works.