Wallet Connectors Are Product Surface, Not Boilerplate

Most DApp tutorials stop at “connect with MetaMask.” Production users abandon flows when mobile deep links fail, sessions expire after a refresh, or chain switching returns an unhandled 4902. MetaMask’s injected provider and WalletConnect cover the majority of users, but their edge cases differ. This guide captures integration lessons from shipping multi-wallet DApps with TypeScript, wagmi, and custom connectors.

What You Will Learn

When injected MetaMask is enough and when WalletConnect is required
WalletConnect session lifecycle, reconnect, and stale session cleanup
Chain switch and add-chain flows for every supported L2
accountsChanged and chainChanged event hygiene
A practical testing matrix for desktop, mobile, and multi-wallet scenarios

1. Injected Provider vs WalletConnect

Injected providers (window.ethereum) work well on desktop when an extension is installed. Mobile Safari and many in-app browsers do not inject a provider. On those surfaces WalletConnect (or a wallet-specific SDK such as Coinbase Wallet) is required.

Recommended approach:

Use a shared abstraction (wagmi + RainbowKit, ConnectKit, or a thin custom layer) so UI code does not branch on connector type.
Prefer injected when available for lower latency and fewer modal steps.
Always offer WalletConnect as a fallback for mobile and for users who prefer QR pairing.
Do not assume a single chain; every connector must declare supported chains and handle missing networks.

Coinbase Wallet and other browser wallets often expose both injected and WalletConnect paths. Test both; the injected path on mobile can behave differently from the QR path.

2. Session Lifecycle and Reconnect

WalletConnect sessions can expire, desync after the dapp restarts, or remain “connected” in the wallet while the dapp lost the pairing key. Silent failures look like a frozen UI.

Production rules:

On app load, attempt a controlled reconnect only if you still hold a valid session topic and the user previously opted in.
On reconnect failure, clear local session state and show an explicit “Reconnect wallet” control — never leave a ghost connected address.
When the user disconnects in the wallet, your dapp must clear address-bound auth tokens and cached balances.
Store only the minimum needed for reconnect (topic, peer metadata). Do not persist private material.

For MetaMask injected sessions, treat page reload as a soft reconnect: re-request accounts only if your product requires a live session; otherwise show a one-click “Connect” that calls eth_requestAccounts.

3. Chain Switching and Add-Chain

Users frequently land on the wrong network. The standard flow is:

Call wallet_switchEthereumChain with the target chainId.
If the wallet returns error code 4902 (unrecognized chain), call wallet_addEthereumChain with full parameters: chainId, chainName, rpcUrls, nativeCurrency, blockExplorerUrls.
Retry switch after add succeeds.
Surface a clear error if the user rejects either prompt.

Never assume the wallet already knows your L2. Maintain a single source of truth for chain metadata (chainId, RPC, explorer) and reuse it in add-chain payloads and in your read clients. Mismatched RPC URLs between the wallet and your app cause “wrong network” bugs that are hard to reproduce.

4. Event Hygiene

Subscribe to accountsChanged and chainChanged as soon as a connector is active.

On accountsChanged: update the active address, invalidate React Query / SWR caches keyed by address, and re-run any signature-gated session if your backend binds tokens to an address.
On chainChanged: update the active chain, refetch balances and allowances, and disable actions that are invalid on the new chain.
On disconnect: clear auth, cancel in-flight writes, and reset UI to a disconnected state.

Failing to unsubscribe on unmount or route change leaks listeners and can fire updates against unmounted components. In React, pair every subscribe with a cleanup in useEffect.

5. Security and UX Considerations

Never ask for eth_sign of arbitrary opaque blobs when personal_sign or typed data (EIP-712) will do. Users and wallets treat eth_sign as high risk.
Show the network name and truncated address near primary actions so users notice mid-session switches.
Rate-limit connection prompts; repeated eth_requestAccounts calls look like phishing to some wallets.
For high-value transactions, display human-readable summaries (amount, token, recipient) before requesting signature.

6. Testing Matrix

Before shipping, exercise at least:

Desktop Chrome + MetaMask: connect, switch chain, add unknown chain, accountsChanged, disconnect
Desktop + WalletConnect QR to a mobile wallet
Mobile Safari + WalletConnect deep link return path
In-app browser (Twitter/X, Discord) where injection may be partial
User rejects connect, rejects switch, and rejects add-chain
Reload while connected; hard clear site data; expired WalletConnect session

7. FAQ

Should I support only WalletConnect?

No. Injected MetaMask remains the fastest path for many desktop users. Support both through one abstraction.

Is WalletConnect v2 required?

Yes for new builds. v1 is deprecated. Use current SDKs and project IDs from the WalletConnect Cloud dashboard.

How do I handle multiple accounts?

Always read the first account as active unless your product explicitly supports multi-account UX. Re-fetch on accountsChanged.

8. Summary

MetaMask injected and WalletConnect are complementary. Injected wins on desktop latency; WalletConnect wins on mobile and QR pairing. Production quality comes from session reconnect design, complete chain switch/add flows, and disciplined event handling — not from the connect button alone.

Key Takeaway

Support injected and WalletConnect, handle chain add/switch for every network, design explicit reconnect UX, and test reject and mid-session change paths as carefully as the happy path.

Need a solid wallet connection layer for a production DApp?

I integrate and harden multi-wallet flows for TypeScript and Next.js DApps. Get in touch or explore Web3 development services.

MetaMask vs WalletConnect for DApps: Production Integration Guide (2026)