Skip to content

Migrate to @metamask/connect-evm #2390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0xFirekeeper wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Migrate to @metamask/connect-evm #2390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
70c2d0e
Migrate to @metamask/connect-evm
0xFirekeeper May 4, 2026
734c77e
metamask: add chain RPC fallback & options
0xFirekeeper May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 35 additions & 17 deletions packages/metamask/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# @web3-onboard/metamask

## Wallet module for connecting MetaMask Wallet SDK to web3-onboard
## Wallet module for connecting MetaMask Connect EVM to web3-onboard

The MetaMask Web3-Onboard module provides a reliable, secure, and seamless connection from your dapp to the MetaMask browser extension and MetaMask Mobile.
See [MetaMask SDK Developer Docs](https://docs.metamask.io/wallet/how-to/connect/set-up-sdk/)

This module uses [MetaMask Connect EVM](https://docs.metamask.io/metamask-connect/evm/) (`@metamask/connect-evm`) under the hood — the successor to the legacy `@metamask/sdk`. The integration surface for `@web3-onboard/metamask` is unchanged: the legacy options below are mapped to their MetaMask Connect EVM equivalents internally so existing dapps keep working without code changes.

![MetaMask SDK ConnectionFlow](https://github.com/blocknative/web3-onboard/blob/develop/assets/metaMaskSDK-connect.gif?raw=true 'MetaMask SDK ConnectionFlow')

Expand All @@ -11,23 +13,37 @@ See [MetaMask SDK Developer Docs](https://docs.metamask.io/wallet/how-to/connect
`npm i @web3-onboard/metamask`

### If using this package with the `@web3-onboard/injected-wallets` module
_When utilizing this package alongside the `@web3-onboard/injected-wallets` module, ensure to list this package prior to the initialized injected-wallets module within the wallets list of the Web3-Onboard init._
_This order prioritizes the SDK when a MetaMask browser wallet is detected, allowing the SDK to take precedence._

_When utilizing this package alongside the `@web3-onboard/injected-wallets` module, ensure to list this package prior to the initialized injected-wallets module within the wallets list of the Web3-Onboard init._
_This order prioritizes the MetaMask Connect EVM client when a MetaMask browser wallet is detected, allowing it to take precedence._

## Options

```typescript
// For a complete list of options check https://docs.metamask.io/wallet/how-to/connect/set-up-sdk/
// All fields are optional. Legacy MetaMaskSDK option names are accepted for
// backwards compatibility and mapped to MetaMask Connect EVM internally.
interface MetaMaskSDKOptions {
dappMetadata: {
url?: string;
name?: string;
base64Icon?: string;
},
dappMetadata?: {
url?: string
name?: string
iconUrl?: string
base64Icon?: string
}
/**
* If MetaMask browser extension is detected, directly use it without prompting the user.
* If MetaMask browser extension is detected, prefer it over the mobile flow.
* Mapped to `ui.preferExtension`.
*/
extensionOnly?: boolean;
extensionOnly?: boolean
/** Mapped to `ui.headless`. */
headless?: boolean
/** Used to populate `api.supportedNetworks` via `getInfuraRpcUrls`. */
infuraAPIKey?: string
/** Merged into `api.supportedNetworks`. */
readonlyRPCMap?: Record<string, string>
/** Mapped to `mobile.preferredOpenLink`. */
openDeeplink?: (deeplink: string) => void
/** Mapped to `mobile.useDeeplink`. */
useDeeplink?: boolean
}
Comment on lines +37 to 47
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Document showInstallModal in the options interface.

The implementation supports showInstallModal, but the README options type omits it.

Proposed fix 
   /** Mapped to `ui.headless`. */
   headless?: boolean
+  /** Mapped to `ui.showInstallModal` (defaults to `false`). */
+  showInstallModal?: boolean
   /** Used to populate `api.supportedNetworks` via `getInfuraRpcUrls`. */
   infuraAPIKey?: string
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/metamask/README.md` around lines 37 - 47, Add documentation for the
missing showInstallModal option to the options interface in the README: declare
the property showInstallModal?: boolean and document it as mapped to
mobile.showInstallModal (or the equivalent runtime option name) so the README
matches the implementation that supports showInstallModal; update the options
block where headless, infuraAPIKey, readonlyRPCMap, openDeeplink, and
useDeeplink are documented to include this new entry.

```

Expand All @@ -38,12 +54,14 @@ import Onboard from '@web3-onboard/core'
import metamaskSDK from '@web3-onboard/metamask'

// initialize the module with options
const metamaskSDKWallet = metamaskSDK({options: {
extensionOnly: false,
dappMetadata: {
name: 'Demo Web3Onboard'
const metamaskSDKWallet = metamaskSDK({
options: {
extensionOnly: false,
dappMetadata: {
Comment on lines +57 to +60
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update example to avoid a no-op extensionOnly: false.

Current mapping only applies extensionOnly when it is true; using false in the example implies behavior that does not change anything.

Proposed fix 
 const metamaskSDKWallet = metamaskSDK({
   options: {
-    extensionOnly: false,
     dappMetadata: {
       name: 'Demo Web3Onboard'
     }
   }
 })
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const metamaskSDKWallet = metamaskSDK({
options: {
extensionOnly: false,
dappMetadata: {
const metamaskSDKWallet = metamaskSDK({
options: {
dappMetadata: {
name: 'Demo Web3Onboard'
}
}
})
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/metamask/README.md` around lines 57 - 60, The README example sets
extensionOnly: false which is a no-op because the code only maps extensionOnly
when true; either remove extensionOnly from the example or set it to
extensionOnly: true to demonstrate the behavior — update the metamaskSDK(...)
call (the metamaskSDKWallet/options/dappMetadata block) to reflect one of these
changes so the example matches actual mapping logic.

name: 'Demo Web3Onboard'
}
}
}})
})

const onboard = Onboard({
// ... other Onboard options
Expand Down
132 changes: 67 additions & 65 deletions packages/metamask/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,69 @@
{
"name": "@web3-onboard/metamask",
"version": "2.2.1",
"description": "MetaMask SDK wallet module for connecting to Web3-Onboard. Web3-Onboard makes it simple to connect Ethereum hardware and software wallets to your dapp. Features standardised spec compliant web3 providers for all supported wallets, framework agnostic modern javascript UI with code splitting, CSS customization, multi-chain and multi-account support, reactive wallet state subscriptions and real-time transaction state change notifications.",
"keywords": [
"Ethereum",
"Web3",
"EVM",
"dapp",
"Multichain",
"Wallet",
"Transaction",
"Provider",
"Hardware Wallet",
"Notifications",
"React",
"Svelte",
"Vue",
"Next",
"Nuxt",
"MetaMask",
"Coinbase",
"WalletConnect",
"Ledger",
"Trezor",
"Connect Wallet",
"Ethereum Hooks",
"Blocknative",
"Mempool",
"pending",
"confirmed",
"Injected Wallet",
"Crypto",
"Crypto Wallet"
],
"repository": {
"type": "git",
"url": "https://github.com/blocknative/web3-onboard.git",
"directory": "packages/metamask"
},
"homepage": "https://web3onboard.thirdweb.com",
"bugs": "https://github.com/blocknative/web3-onboard/issues",
"module": "dist/index.js",
"browser": "dist/index.js",
"main": "dist/index.js",
"type": "module",
"typings": "dist/index.d.ts",
"files": ["dist"],
"license": "MIT",
"scripts": {
"build": "tsc",
"dev": "tsc -w",
"type-check": "tsc --noEmit"
},
"devDependencies": {
"@types/node": "^20.5.7",
"ts-node": "^10.9.1",
"typescript": "^5.2.2"
},
"dependencies": {
"@metamask/sdk": "^0.32.0",
"@web3-onboard/common": "^2.4.1"
},
"engines": {
"node": ">=18.18"
}
"name": "@web3-onboard/metamask",
"version": "2.4.0",
"description": "MetaMask Connect EVM wallet module for connecting to Web3-Onboard. Web3-Onboard makes it simple to connect Ethereum hardware and software wallets to your dapp. Features standardised spec compliant web3 providers for all supported wallets, framework agnostic modern javascript UI with code splitting, CSS customization, multi-chain and multi-account support, reactive wallet state subscriptions and real-time transaction state change notifications.",
"keywords": [
"Ethereum",
"Web3",
"EVM",
"dapp",
"Multichain",
"Wallet",
"Transaction",
"Provider",
"Hardware Wallet",
"Notifications",
"React",
"Svelte",
"Vue",
"Next",
"Nuxt",
"MetaMask",
"Coinbase",
"WalletConnect",
"Ledger",
"Trezor",
"Connect Wallet",
"Ethereum Hooks",
"Blocknative",
"Mempool",
"pending",
"confirmed",
"Injected Wallet",
"Crypto",
"Crypto Wallet"
],
"repository": {
"type": "git",
"url": "https://github.com/blocknative/web3-onboard.git",
"directory": "packages/metamask"
},
"homepage": "https://web3onboard.thirdweb.com",
"bugs": "https://github.com/blocknative/web3-onboard/issues",
"module": "dist/index.js",
"browser": "dist/index.js",
"main": "dist/index.js",
"type": "module",
"typings": "dist/index.d.ts",
"files": [
"dist"
],
"license": "MIT",
"scripts": {
"build": "tsc",
"dev": "tsc -w",
"type-check": "tsc --noEmit"
},
"devDependencies": {
"@types/node": "^20.5.7",
"ts-node": "^10.9.1",
"typescript": "^5.2.2"
},
"dependencies": {
"@metamask/connect-evm": "^1.0.0",
"@web3-onboard/common": "^2.4.1"
},
"engines": {
"node": ">=18.18"
}
}
Loading
Loading