feat: deprecate $ version references in overrides#12262
Merged
Conversation
Using the "$" syntax in overrides (e.g. "react": "$react") now emits a deprecation warning. The syntax still resolves as before. Catalogs are the recommended replacement: reference a catalog entry with the "catalog:" protocol. Refs #12160
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🧰 Additional context used📓 Path-based instructions (2)**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
**/*.test.{ts,tsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
🧠 Learnings (23)📓 Common learnings📚 Learning: 2026-06-05T13:47:05.929ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-05-05T23:03:30.044ZApplied to files:
📚 Learning: 2026-05-20T21:18:56.391ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-05-24T08:18:06.019ZApplied to files:
📚 Learning: 2026-05-15T11:37:17.491ZApplied to files:
📚 Learning: 2026-05-07T20:38:01.796ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-05-24T16:07:54.784ZApplied to files:
📚 Learning: 2026-06-06T22:48:27.363ZApplied to files:
📚 Learning: 2026-05-14T09:04:00.133ZApplied to files:
📚 Learning: 2026-06-05T13:47:26.046ZApplied to files:
📚 Learning: 2026-06-06T22:48:27.363ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-05-20T22:49:17.652ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-05-20T23:08:06.093ZApplied to files:
📚 Learning: 2026-05-26T21:01:06.666ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
📚 Learning: 2026-06-05T13:47:05.929ZApplied to files:
📚 Learning: 2026-05-29T18:03:15.372ZApplied to files:
🔇 Additional comments (3)
📝 WalkthroughWalkthroughThe PR adds a deprecation warning system for the ChangesDeprecation warning for dollar-syntax version overrides
🎯 2 (Simple) | ⏱️ ~12 minutes
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review Summary by QodoDeprecate
WalkthroughsDescription• Warn on deprecated $ overrides • Keep override resolution unchanged • Add coverage for warning behavior • Publish patch changeset Diagramflowchart LR
A["`getOptionsFromPnpmSettings`"] -- "checks overrides" --> B["`warnAboutDeprecatedVersionReferences`"]
B -- "calls" --> C["`globalWarn`"]
A -- "still resolves with manifest" --> D["`createVersionReferencesReplacer`"]
E["`deprecatedVersionReferences.test.ts`"] -- "verifies" --> B
F["`.changeset/dollar-overrides-deprecation.md`"] -- "documents release note" --> G["patch release"]
File Changes1. config/reader/src/getOptionsFromRootManifest.ts
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Using the
$version reference syntax inoverrides(e.g."react": "$react") now prints a deprecation warning. The syntax still resolves exactly as before — this only adds a warning that nudges users toward catalogs.Why
The
$reactsyntax resolves the override against the root manifest's direct dependencies. This makes it fragile — for example,pnpm fetchwith a minimalpackage.json(onlypackageManager) crashes withERR_PNPM_CANNOT_RESOLVE_OVERRIDE_VERSION, even though the lockfile already has everything (#12160).Catalogs cover the same "maintain the version in one place" use case without that fragility: a
catalog:reference is self-contained (the version lives in the catalog, not in the direct deps), and catalogs are already supported insideoverrides. The plan is deprecate now, remove in a future major.Changes
@pnpm/config.reader: emit aglobalWarnwhen any override value uses the$syntax (ingetOptionsFromRootManifest.ts). Resolution behavior is unchanged.Docs were updated separately in the
pnpm.iorepo (theoverridessection now documents thecatalog:approach instead of$).Parity note (pacquet)
No pacquet-side change is needed: pacquet's
config-parse-overridesdoes not implement$version-reference resolution at all yet, so there is nothing to deprecate there. When pacquet ports the$syntax, this deprecation warning should be ported alongside it.Follow-ups (not in this PR)
$resolution lazy/skipped on thepnpm fetchpath so existing$users stop hitting the crash in pnpm fetch fails with$references in pnpm-workspace.yaml #12160 during the deprecation window.$support in a major release.Written by an agent (Claude Code, claude-opus-4-8).
Summary by CodeRabbit
Release Notes
Documentation
$version reference syntax in pnpm overrides; users are encouraged to adoptcatalog:protocol instead for maintaining synchronized override versions.New Features
$syntax is detected in overrides, guiding users toward the recommended migration path.