chore: Add Yarn plugin for using preview builds #39680
Merged
+556
−0
Conversation
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
Some MetaMask repos (e.g. `core`) allow upcoming package changes to be
tested in Extension and/or Mobile prior to release by publishing
"preview builds".
However, using a preview build can be complicated, as care must be taken
to accurately simulate what the dependency tree of a project will look
like when a new production version is released.
To make this process easier, this commit adds a Yarn plugin. The plugin
works like this:
1. First, you must tell the plugin which preview builds you want to use
for which dependencies. You do this by adding an entry to a
`previewBuilds` section in `package.json`. For instance, to specify
that version `29.0.0-preview-3ec2a74` should be used to test
non-breaking changes to `@metamask/network-controller`, you would
add:
"previewBuilds": {
"@metamask/network-controller": {
"type": "non-breaking",
"previewVersion": "29.0.0-preview-3ec2a74"
}
}
Similarly, you could set `type` to "breaking" to test breaking
changes.
By default the plugin will assume the NPM scope of the preview build
to be `metamask-previews`, but you can change this with
`previewScope`:
"previewBuilds": {
"@metamask/network-controller": {
"type": "non-breaking",
"previewScope": "my-custom-scope"
"previewVersion": "29.0.0-preview-3ec2a74",
}
}
2. Next, run `yarn install`. The plugin will read the `previewBuilds`
section to determine how the dependencies you've specified should be
resolved. If the `type` of an entry is "non-breaking", all version
ranges of that dependency in the dependency tree that are
major-compatible with the corresponding entry in `dependencies` will
resolve to the preview build. If the `type` is "breaking", then only
the version range of the corresponding entry in `dependencies` will
resolve to the preview build. Finally, if a dependency is patched,
the preview build will be patched in the same way.
Contributor
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
Contributor
✨ Files requiring CODEOWNER review ✨👨🔧 @MetaMask/extension-platform (1 files, +1 -0)
|
Contributor
Builds ready [4fd9d4c]
UI Startup Metrics (1324 ± 100 ms)
📊 Page Load Benchmark ResultsCurrent Commit: 📄 Localhost MetaMask Test DappSamples: 100 Summary
📈 Detailed Results
Bundle size diffs
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| originalDependencyDescriptor, | ||
| }); | ||
| } | ||
| }, |
There was a problem hiding this comment.
Stale state persists causing unintended preview resolutions
Medium Severity
The module-level state (validatedPreviewBuilds, errors, resolutions) is only cleared in afterAllInstalled. If installation fails before that hook runs, and the user modifies or removes entries from previewBuilds config, the next installation will use stale state. Notably, if all preview builds are removed (packageNames.length === 0), validateProject returns early without clearing validatedPreviewBuilds, causing reduceDependency to silently apply old preview build resolutions that the user explicitly removed.
Additional Locations (1)
Contributor
Author
There was a problem hiding this comment.
validatePreviewBuilds isn't persisted across runs. I don't think the problem presented here is likely to happen.
| (previewBuilds, [packageName, config]) => { | ||
| previewBuilds[packageName] = { | ||
| ...config, | ||
| previewScope: config.previewScope ?? DEFAULT_PREVIEW_SCOPE, |
There was a problem hiding this comment.
Null config value crashes before validation can run
Low Severity
When a previewBuilds entry has a null value (e.g., "@metamask/foo": null), getPreviewBuildConfigurations crashes at config.previewScope with a confusing TypeError before validatePreviewBuildConfiguration can provide the intended "Expected an object" error message. The validation logic exists but is bypassed because the config processing happens first.
Contributor
Author
There was a problem hiding this comment.
Hmm, this is true. I can fix this in a followup PR (I think this is true of the plugin on the mobile side as well).
cryptodev-2s
approved these changes
Feb 2, 2026
metamaskbot
added
the
release-13.18.0
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
Description
Some MetaMask repos (e.g.
core) allow upcoming package changes to be tested in Extension and/or Mobile prior to release by publishing "preview builds".However, using a preview build can be complicated, as care must be taken to accurately simulate what the dependency tree of a project will look like when a new production version is released.
To make this process easier, this commit adds a Yarn plugin. The plugin works like this:
First, you must tell the plugin which preview builds you want to use for which dependencies. You do this by adding an entry to a
previewBuildssection inpackage.json. For instance, to specify that version29.0.0-preview-3ec2a74should be used to test non-breaking changes to@metamask/network-controller, you would add:Similarly, you could set
typeto "breaking" to test breaking changes.By default the plugin will assume the NPM scope of the preview build to be
metamask-previews, but you can change this withpreviewScope:Next, run
yarn install. The plugin will read thepreviewBuildssection to determine how the dependencies you've specified should be resolved. If thetypeof an entry is "non-breaking", all version ranges of that dependency in the dependency tree that are major-compatible with the corresponding entry independencieswill resolve to the preview build. If thetypeis "breaking", then only the version range of the corresponding entry independencieswill resolve to the preview build. Finally, if a dependency is patched, the preview build will be patched in the same way.Changelog
CHANGELOG entry: null
Related issues
https://consensyssoftware.atlassian.net/browse/WPC-199
Manual testing steps
package.json:yarn install. You should see a message at the end of the installation steps:yarn why @metamask-previews/network-controller. You should see only one entry:@metamask/network-controllerwas updated to use the preview build.previewBuildsinpackage.jsonto read:yarn install. You should see a message at the end of the installation steps:yarn why @metamask-previews/network-controller. You should see a bunch of entries:@metamask/network-controllermatching^29.0.0were updated to use the preview build.previewBuildsand re-runyarn install.yarn patch @metamask/network-controller@npm:29.0.0. Open the resulting patch directory and make a modification to any file. Runyarn patch-commit -s <directory>to generate the patch and updatepackage.json, then runyarn installto apply the patch.package.json:yarn install. You should see a message at the end of the installation steps:yarn why @metamask/network-controller. You should see a bunch of entries:Screenshots/Recordings
(N/A)
Before
After
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Medium Risk
Introduces a custom Yarn resolution plugin that can rewrite dependency ranges (including
patch:ranges), which can affect installs across the repo if misconfigured, but is limited to@metamask/*packages and opt-in viapreviewBuilds.Overview
Adds a new Yarn plugin (
.yarn/plugins/@yarnpkg/plugin-preview-builds.cjs) that reads apreviewBuildsconfig frompackage.jsonand rewrites matching@metamask/*dependency resolutions to@metamask-previews/*(or a custom scope), supporting breaking (top-level only) vs non-breaking (major-compatible across the tree) behavior and preservingpatch:dependencies.Updates
.yarnrc.ymlto load the new plugin so the mapping and end-of-install summary/errors run duringyarn install.Written by Cursor Bugbot for commit 4fd9d4c. This will update automatically on new commits. Configure here.