Skip to content

Conversation

@mcmire
Copy link
Contributor

@mcmire mcmire commented Nov 20, 2025

Explanation

Some controllers and services expect other controllers and services to pre-exist so that they can communicate with them. Traditionally the way that we have expressed this dependency is via peer dependencies. That is, if a controller in @metamask/foo-controller used a service in @metamask/bar-service, then it would declare a peer dependency on a major version of @metamask/bar-service. This would enforce that clients declare a direct dependency on @metamask/bar-service and the major version used for this dependency matched the major version that @metamask/foo-controller expressed.

However, this approach complicates the release process. If the major version of a package is bumped, it must be synchronized across all peer dependents across the monorepo. But as a result, all peer dependents must be bumped by a major (since changing a peer dependency is a breaking change) and thus must be included in the release. This means that releases can quickly balloon in size, causing pain for other teams.

To address this issue, this commit converts all peer dependencies on controller and service packages to regular direct dependencies. This allows major versions of packages to be released more flexibly as needed.

However, this change also means that, at the client level, it is possible for different versions of packages to be present in the dependency tree. For instance, the client could directly depend on @metamask/foo-controller 1.0.0 and @metamask/bar-controller 1.0.0, but @metamask/bar-controller could itself depend on @metamask/foo-controller 1.1.0. So while @metamask/bar-controller thinks it is talking to a later version of @metamask/foo-controller, it would actually be talking to an earlier version.

In most cases any incompatibilities would show up at compile-time, but they could also show up at runtime. In general we expect client engineers to be aware of these differences when making new releases — perhaps more aware than they might be now.

References

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed, highlighting breaking changes as necessary
  • I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes

Note

Replaces peerDependencies with direct dependencies across controller/service packages and updates Yarn config/lock/validation to enforce the new model.

  • Dependencies:
    • Move controller/service peerDependencies to direct dependencies across many packages (e.g., accounts, assets, bridge, gas-fee, network, profile-sync, signature, transaction, etc.).
    • Remove corresponding peerDependencies and adjust devDependencies accordingly; update yarn.lock.
  • Tooling (yarn.config.cjs):
    • Add rule to disallow workspace controller/service packages as peer deps; require them as direct deps instead.
    • Modify peer-deps check to only require devDependencies for non-workspace peers.
    • Update version-sync logic to handle deps listed in either prod or dev when no peer dep exists.
  • Docs/Changelogs:
    • Update package changelogs to note the dependency model change and list affected packages where relevant.

Written by Cursor Bugbot for commit 47a5aed. This will update automatically on new commits. Configure here.

Some controllers and services expect other controllers and services to
pre-exist so that they can communicate with them. Traditionally the way
that we have expressed this dependency is via peer dependencies. That
is, if a controller in `@metamask/foo-controller` used a service in
`@metamask/bar-service`, then it would declare a peer dependency on
a major version of `@metamask/bar-service`. This would enforce that
clients declare a direct dependency on `@metamask/bar-service` and the
major version used for this dependency matched the major version that
`@metamask/foo-controller` expressed.

However, this approach complicates the release process. If the major
version of a package is bumped, it must be synchronized across all peer
dependents across the monorepo. But as a result, all peer dependents
must be bumped by a major (since changing a peer dependency is a breaing
change) and thus must be included in the release. This means that
releases can quickly balloon in size, causing pain for other teams.

To address this issue, this commit converts all peer dependencies on
controller and service packages to regular direct dependencies. This
allows major versions of packages to be released more flexibly as needed.

However, this change also means that, at the client level, it is
possible for different versions of packages to be present in the
dependency tree. For instance, the client could directly depend on
`@metamask/foo-controller` 1.0.0 and `@metamask/bar-controller` 1.0.0,
but `@metamask/bar-controller` could itself depend on
`@metamask/foo-controller` 1.1.0. So while `@metamask/bar-controller`
thinks it is talking to a later version of `@metamask/foo-controller`,
it would actually be talking to an earlier version.

In most cases any incompatibilities would show up at compile-time, but
they could also show up at runtime. In general we expect client
engineers to be aware of these differences when making new releases —
perhaps more aware than they might be now.
@mcmire mcmire force-pushed the convert-peer-deps-to-deps branch from 9e115bc to 5342e97 Compare November 20, 2025 20:30
@mcmire mcmire changed the title WIP - Convert peer deps to deps Move peer deps for controller/service packages to direct deps Nov 20, 2025
@mcmire
Copy link
Contributor Author

mcmire commented Nov 20, 2025

Adding the no-changelog label because controller-utils removes some peer dependencies outright rather that moving them, and I'm not sure this warrants mention in the changelog.

@mcmire mcmire marked this pull request as ready for review November 21, 2025 04:04
@mcmire mcmire requested review from a team as code owners November 21, 2025 04:04
@mcmire mcmire enabled auto-merge November 21, 2025 04:16
cryptodev-2s
cryptodev-2s previously approved these changes Nov 21, 2025
Copy link
Contributor

@cryptodev-2s cryptodev-2s left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@mcmire mcmire added this pull request to the merge queue Nov 21, 2025
Merged via the queue into main with commit ea5cf6f Nov 21, 2025
273 checks passed
@mcmire mcmire deleted the convert-peer-deps-to-deps branch November 21, 2025 17:41
github-merge-queue bot pushed a commit that referenced this pull request Nov 21, 2025
## Explanation

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->
Minor release of @metamask/transaction-controller. Added
`musdConversion` transaction type.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Releases 691.0.0, publishing @metamask/transaction-controller 62.2.0
(adds `musdConversion` type) and updating all dependents to ^62.2.0 with
corresponding changelog entries.
> 
> - **Core**
>   - Bump monorepo version to `691.0.0`.
> - **Transaction Controller**
> - Release `@metamask/transaction-controller@62.2.0` adding
`musdConversion` transaction type.
> - **Dependents updated to `^62.2.0`**
> - `@metamask/assets-controllers`, `bridge-controller`,
`bridge-status-controller`, `eip-5792-middleware`,
`gator-permissions-controller`, `network-enablement-controller`,
`phishing-controller`, `shield-controller`, `subscription-controller`,
`transaction-pay-controller`, `user-operation-controller`, and devDep in
`earn-controller`.
> - **Changelogs**
> - Note dependency bumps and continued migration of peer deps to direct
deps (refs `#7209`, `#7220`).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b7997e5. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants