MetaMask Connect — Conventions & Guardrails

Always-on guardrails for the MetaMask Connect SDK, distilled from the MetaMask Connect Cursor plugin rules. Apply these whenever you generate or review MetaMask Connect (@metamask/connect-evm / -multichain / -solana) or wagmi metaMask() connector code.

MetaMask Connect Best Practices

Best practices for MetaMask Connect SDK — import paths, singleton behavior, required config, error handling, and connection state management

Import Paths

• Import EVM client from @metamask/connect-evm
• Import multichain client from @metamask/connect-multichain
• Import Solana client from @metamask/connect-solana
• Never import from internal sub-packages like @metamask/connect/dist/... or @metamask/connect-evm/src/...
• Use the wagmi connector from the published entrypoint your installed version exposes; do not assume @metamask/connect-evm/wagmi exists unless your package version exports it
• @metamask/connect-multichain is a regular dependency of both @metamask/connect-evm and @metamask/connect-solana (since 2.1.0) and is installed transitively — you do not need to add it yourself. (Only the 2.0.0 releases briefly made it a peer dependency.) Both clients warn at runtime on duplicate or mismatched @metamask/connect-multichain resolutions; if you do depend on it directly (e.g. to use createMultichainClient), use ^1.0.0 — it is a stable 1.x package following strict semver

Required Configuration