[Feature] Support catalog: protocol in yarn add

[literat]

• I'd be willing to implement this feature (contributing guide)
• This feature is important to have in this repository; a contrib plugin wouldn't do

Describe the user story

As a monorepo maintainer using catalogs for centralized version management, I want yarn add to
understand the catalog: protocol so that adding or updating dependencies follows the same
workflow as every other dependency operation — through the CLI, not manual file editing.

We maintain a design system with 10+ workspaces and 4 named catalogs (~200 catalog: references
across packages). Every time we need to add a new dependency, the workflow breaks:

1. Manually add the version range to .yarnrc.yml under the correct catalog
2. Manually edit package.json to reference catalog:<name>
3. Run yarn install

This is error-prone (typos in catalog names, wrong version ranges, forgetting to use the
catalog) and feels like a step backward from the otherwise excellent DX that catalogs provide
for existing dependencies.

Describe the solution you'd like

Introduce a --catalog flag for yarn add that:

1. Adds the resolved version range to the specified catalog in .yarnrc.yml
2. Sets the dependency in package.json to catalog:<name> instead of a raw version range
3. If the package already exists in the target catalog, skips updating .yarnrc.yml and only adds the catalog: reference to package.json

Proposed API

# Add to a named catalog
yarn add react --catalog=frontend
# → .yarnrc.yml: catalogs.frontend.react = "^19.0.0"
# → package.json: "react": "catalog:frontend"

# Add to the default (unnamed) catalog
yarn add lodash --catalog
# → .yarnrc.yml: catalog.lodash = "^4.17.21"
# → package.json: "lodash": "catalog:"

# Package already exists in catalog — only adds the reference
yarn add react --catalog=frontend
# → .yarnrc.yml: unchanged (react already defined)
# → package.json: "react": "catalog:frontend"

# Combined with other flags
yarn add eslint --catalog=lint --dev
# → .yarnrc.yml: catalogs.lint.eslint = "^9.39.3"
# → package.json devDependencies: "eslint": "catalog:lint"

# Multiple packages to the same catalog
yarn add react react-dom --catalog=frontend
# → both added to catalogs.frontend and referenced as catalog:frontend

Behavior details

• --catalog without a value targets the default (unnamed) catalog
• --catalog=<name> targets a named catalog
• Version resolution follows the same logic as regular yarn add (latest by default, or explicit
  yarn add react@^18 --catalog frontend)
• If the package already exists in the catalog with a different version range, Yarn should warn
  and ask for confirmation (or provide --force to override)
• yarn add without --catalog remains unchanged — no breaking changes

Describe the drawbacks of your solution

• Adds complexity to the yarn add command — it now needs to write to .yarnrc.yml in addition to package.json and the lockfile
• The --catalog flag introduces a new optional parameter that interacts with existing flags (--dev, --peer, --exact, --tilde). These interactions need to be well-defined, particularly --exact and --tilde which affect the version range written to the catalog
• Conflict resolution when a catalog entry already exists with a different range needs a clear UX decision

Describe alternatives you've considered

Why not a plugin?
The catalog: protocol is resolved by Yarn plugin-catalog. A third-party plugin adding a yarn catalog add command would need to duplicate the catalog resolution logic and the yarn add dependency resolution pipeline. It would also fragment the DX — users would need to remember two different commands depending on whether they're using catalogs or not.

Why not a separate yarn catalog command?
A subcommand like yarn catalog add react --name=frontend could work, but it splits the mental
model. yarn add is the established entry point for adding dependencies. Extending it with --catalog keeps the workflow consistent and discoverable.

Manual editing (current workaround)
This is what we do today. It works but it's the only dependency management operation in Yarn that requires manual file editing. Every other operation — add, remove, upgrade — goes through the CLI. Catalogs should not be an exception.

---

Related: #7048 (closed without discussion), #6400 (original catalog feature request where CLI integration was mentioned but not implemented)

[clemyan]

--catalog without a value targets the default (unnamed) catalog
--catalog <name> targets a named catalog

I don't think Clipanion (our CLI framework) can support that. Named catalog would need to be specified using --catalog=<name>.

Adds complexity to the yarn add command — it now needs to write to .yarnrc.yml in addition to package.json and the lockfile

I didn't think about this at first but this does have a significant performance implication. Because currently updating the config file requires re-parsing the config file, and does not return the updated Configuration object. So adding to a catalog requires fully re-parsing the config file 2 additional times (compared to adding non-catalog deps) and the home config 1 additional time.

The catalog: protocol is resolved by Yarn core (specifically plugin-catalog)

First, a bit of terminology. Yarn Modern is written using a core-and-plugin architecture, so "Yarn core" specifically refers only to @yarnpkg/core.

This also brings up a good point about plugin boundaries. While the binary we publish bundles all first-party plugins, we do support building custom Yarn binary to use only a subset of the plugins. Implementing yarn add --catalog would require adding plugin-catalog as a hard dependency to plugin-essentials. If we don't, yarn add --catalog would put the project into an un-installable state (because the catalog/catalogs config would be unrecognized).

On the other hand, if we do add plugin-catalog as a dependency, then to remove catalog support from a custom binary, one would need to remove all of the plugin-essentials commands.

I know we already kinda broke that with jsr:. But I don't think we should break it even more.

A subcommand like yarn catalog add react --name frontend could work

I feel like that is the best option. Even if the UX is slightly worse that best preserve the DX

[arcanis]

I didn't think about this at first but this does have a significant performance implication.

That's fine - yarn add isn't a performance-critical command (it runs infrequently), so a couple of extra ms doesn't impact too much compared to the added convenience.

A subcommand like yarn catalog add react --name frontend could work

I feel like that is the best option. Even if the UX is slightly worse that best preserve the DX

I don't think we should add catalog-specific commands (it may be ok for add, but what about up? we want that command to Just Work™). We can simply move catalog settings in the core settings imo.

[clemyan]

it may be ok for add, but what about up? we want that command to Just Work™

I have been think about this for sometime. Given that plugins can add to the pool of valid descriptors, I am thinking that plugins should also resolve add arguments (which should be a separate concept from descriptors) to descriptors, and to handle upgrades. That way we can invert the dependency to not put the burden on plugin-essentials

I vaguely remember there was an issue about allowing plugins to resolve add arguments but I can't find it now. For the "upgrade" part may be the current Resolver interface can already handle it -- haven't dove too deep there.

That would be a much bigger undertaking though. And over my years as a developer I have come to appreciate the "temporary solutions", so if a PR for add --catalog is submitted then I am not fundamentally opposed to it as long as we agree that's a "temporary solution" (though those tend to be the most permanent things)

[arcanis]

as long as we agree that's a "temporary solution" (though those tend to be the most permanent things)

Berry itself is meant to be somewhat "temporary" (although there's some lifting here as we'll keeping supporting it as a LTS even after zpm is stable) so there's a little more leeway. And since it doesn't support plugins (yet, at least) it's probably ok to relax a little the requirements in Berry.

[literat]

I don't think Clipanion (our CLI framework) can support that. Named catalog would need to be specified using --catalog=.

Hi, thanks for your insights. I will try to keep the issue description up-to-date with the suggestions.

That would be a much bigger undertaking though. And over my years as a developer I have come to appreciate the "temporary solutions", so if a PR for add --catalog is submitted then I am not fundamentally opposed to it as long as we agree that's a "temporary solution" (though those tend to be the most permanent things)

By the time I have dug a little bit into the code. Based on your comments, it seems to me that adding the --catalog option into packages/plugin-essentials/sources/commands/add.ts as a "temporary solution" is a viable way to solve this issue.

So, if you don't mind, I will try to submit a PR with a solution.