setup-evm-browser-app

name	setup-evm-browser-app
description	Scaffold a vanilla JS/TS browser app with MetaMask EVM integration using createEVMClient, EIP-1193 provider event listeners, RPC methods, and chain switching with chainConfiguration fallback

Setup EVM Browser App with MetaMask Connect

When to use

Use this skill when:

• Building a vanilla JavaScript or TypeScript browser app (no React) with MetaMask
• Integrating createEVMClient into a plain HTML page or a bundler-based project
• Wiring up EIP-1193 provider event listeners for account and chain changes
• Performing RPC calls through provider.request in a non-framework context

Workflow

Step 1: Install dependencies

npm install @metamask/connect-evm

@metamask/connect-multichain is a regular dependency of @metamask/connect-evm and is installed transitively. (Only the 2.0.0 release briefly made it a peer dependency; 2.1.0 reverted that.) Installing it explicitly is harmless but not required. The SDK warns at runtime if duplicate or mismatched copies are resolved.

Or include via CDN/script tag if not using a bundler.

Step 2: Create the EVM client

import { createEVMClient, getInfuraRpcUrls } from '@metamask/connect-evm';

const client = await createEVMClient({
  dapp: {
    name: 'My Browser DApp',
    url: window.location.href,
  },
  api: {
    supportedNetworks: {
      ...getInfuraRpcUrls({ infuraApiKey: 'YOUR_INFURA_KEY', chainIds: ['0x1', '0x89', '0xa4b1', '0xaa36a7'] }),
    },
  },
  ui: {
    headless: false,
    preferExtension: true,
    showInstallModal: true,
  },
  eventHandlers: {
    // Keys are camelCase — `display_uri`/`wallet_sessionChanged` are NOT valid here
    displayUri: (uri: string) => {
      console.log('QR URI:', uri);
      // Render QR code for mobile connection
    },
    connect: ({ accounts, chainId }) => {
      // Fires on connection and on automatic session restore
      updateUI(accounts, chainId);
    },
  },
  debug: false,
});

There is no wallet_sessionChanged handler on the EVM client — session restores surface through the connect handler / provider event and accountsChanged. (wallet_sessionChanged is a multichain-client event.)

Step 3: Register provider event listeners

Set up EIP-1193 event listeners immediately after client creation:

const provider = client.getProvider();

provider.on('accountsChanged', (accounts: string[]) => {
  if (accounts.length === 0) {
    // User disconnected their wallet
    updateUI([], null);
    return;
  }
  updateUI(accounts, null);
  fetchBalance(accounts[0]);
});

provider.on('chainChanged', (chainId: string) => {
  // chainId is a hex string, e.g. '0x1'
  document.getElementById('chain')!.textContent = `Chain: ${chainId}`;
  // Refresh balances since the chain changed
  const currentAccount = document.getElementById('account')?.dataset.address;
  if (currentAccount) fetchBalance(currentAccount);
});

provider.on('disconnect', () => {
  // The connect-evm provider emits `disconnect` with no payload
  console.log('Disconnected');
  updateUI([], );
});

Step 4: Connect and update UI

const connectBtn = document.getElementById('connect-btn')!;
const disconnectBtn = document.getElementById('disconnect-btn')!;

connectBtn.addEventListener('click', async () => {
  try {
    connectBtn.textContent = 'Connecting...';
    connectBtn.setAttribute('disabled', 'true');

    const { accounts, chainId } = await client.connect({
      chainIds: ['0x1'],
    });

    updateUI(accounts, chainId);
  } catch (err: any) {
    if (err.code === 4001) {
      showError('Connection rejected. Click Connect to try again.');
      return;
    }
    if (err.code === -32002) {
      showError('A connection request is already pending. Check MetaMask.');
      return;
    }
    showError(err.message ?? 'Connection failed');
  } finally {
    connectBtn.textContent = 'Connect MetaMask';
    connectBtn.removeAttribute('disabled');
  }
});

disconnectBtn.(,  () => {
   client.();
  ([], );
});

 () {
   accountEl = .()!;
   chainEl = .()!;
   connectedSection = .()!;

   (accounts. === ) {
    connectedSection.. = ;
    connectBtn.. = ;
    ;
  }

  accountEl. = ;
  accountEl.. = accounts[];
   (chainId) chainEl. = ;
  connectedSection.. = ;
  connectBtn.. = ;
}

 () {
   errorEl = .()!;
  errorEl. = message;
  ( { errorEl. = ; }, );
}

Step 5: Make RPC calls via provider.request

const provider = client.getProvider();

// Cached/intercepted reads — safe before connect (no chain selection needed)
const chainId = await provider.request({ method: 'eth_chainId' });
const accounts = await provider.request({ method: 'eth_accounts' });

// Node-routed reads need a SELECTED chain — they throw `No chain ID selected`
// until after connect() (or a restored session). Call these post-connect.
const blockNumber = await provider.request({ method: 'eth_blockNumber' });

async function fetchBalance(address: string) {
  const wei = await provider.request({
    method: 'eth_getBalance',
    params: [address, 'latest'],
  }) as string;

  const ethBalance = parseInt(wei, 16) / 1e18;
  document.getElementById('balance')!.textContent =
    `Balance: ${ethBalance.toFixed(6)} ETH`;
}

// Get gas price
const gasPrice =  provider.({ :  });


 nonce =  provider.({
  : ,
  : [accounts[], ],
});


 result =  provider.({
  : ,
  : [
    {
      : ,
      : ,
    },
    ,
  ],
});

Step 6: Switch chains with chainConfiguration fallback

async function switchChain(targetChainId: string) {
  try {
    await client.switchChain({ chainId: targetChainId });
  } catch (err: any) {
    if (err.code === 4001) {
      showError('Chain switch rejected by user.');
    }
  }
}

// Switch to a chain with fallback configuration
// chainConfiguration triggers wallet_addEthereumChain if the chain
// is not already configured in the user's wallet
async function switchToArbitrum() {
  try {
    await client.switchChain({
      chainId: '0xa4b1',
      chainConfiguration: {
        chainId: '0xa4b1', // optional in the type, but set it to the target chain — if omitted it falls back to the currently selected chain (likely the wrong chain to add)
        chainName: 'Arbitrum One',
        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
        rpcUrls: ['https://arb1.arbitrum.io/rpc'],
        blockExplorerUrls: ['https://arbiscan.io'],
      },
    });
  }  (: ) {
     (err. === ) {
      ();
    }
  }
}


.()!.(,
   ());
.()!.(,
   ());
.()!.(,
   ());
.()!.(,
   ());

Step 7: Complete HTML structure

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>MetaMask Connect</title>
</head>
<body>
  <h1>MetaMask Connect Demo</h1>

  <button id="connect-btn">Connect MetaMask</button>
  <p id="error" style="color: red;"></p>

  <div id="connected" style="display: none;">
    <p id="account"></p>
    <p id="chain"></p>
    <p id="balance"></p>
    <button id=>Mainnet (0x1)
    Polygon (0x89)
    Sepolia (0xaa36a7)
    Arbitrum (0xa4b1)
    Disconnect
  

  

Important Notes

• Call createEVMClient once at app startup — each call returns a new EVM client wrapper, but they all share one underlying multichain core (the core is the singleton whose options merge across calls). Don't recreate the client repeatedly.
• Chain IDs are always hex strings — use '0x1', '0x89', '0xaa36a7'. Never pass decimal numbers or decimal strings.
• 0x1 (Ethereum mainnet) is auto-included in every connect() call regardless of the chainIds you specify.
• The provider exists before connection — client.getProvider() always returns a valid EIP-1193 provider. But node-routed reads (eth_blockNumber, eth_getBalance, eth_call, …) require a selected chain and throw No chain ID selected until one is set (after connect() or a restored session). Only eth_chainId and eth_accounts (intercepted, served from cache) are safe before connecting.
• Convenience getters — use client.getChainId() (returns Hex | undefined) and client.getAccount() (returns Address | undefined) instead of provider.request({ method: 'eth_chainId' }) / eth_accounts for cached state.
• Connection status — client.status returns 'connecting' | 'connected' | 'disconnected'. (The 5-value 'loaded'/'pending' union belongs to the multichain core, not the EVM client.) Use this for UI state instead of tracking manually.
• Register event listeners before connecting — set up accountsChanged, chainChanged, and disconnect handlers immediately after getting the provider.
• chainConfiguration is a fallback, not a forced add — it is only used if the wallet doesn't already have the chain configured. If the chain exists, only wallet_switchEthereumChain fires.
• Page reloads restore automatically — the EVM client syncs any persisted session before resolves and re-emits / on the provider. The EVM client has no method and no handler — use the provider events (or ) to restore UI state.