setup-evm-react-native-app

Setup EVM React Native App with MetaMask Connect

When to use

Use this skill when:

• Creating a React Native app that connects to MetaMask Mobile
• Setting up polyfills for window and other missing globals
• Configuring metro.config.js with Node.js module shims
• Debugging React Native import order or missing polyfill errors

Workflow

Step 1: Install dependencies

Install the SDK and all required polyfill/shim packages:

npm install @metamask/connect-evm @metamask/connect-multichain react-native-get-random-values buffer @react-native-async-storage/async-storage readable-stream

@metamask/connect-multichain is installed transitively by @metamask/connect-evm (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 on duplicate or mismatched copies. react-native-get-random-values provides crypto.getRandomValues — strictly required only on React Native < 0.72 (Hermes 0.72+ ships globalThis.crypto.getRandomValues natively), but recommended as a safety net on all versions. It must be imported before any other SDK-related code. readable-stream provides the stream shim for Metro. buffer is recommended as a safety net for peer dependencies — @metamask/connect-multichain self-polyfills Buffer internally, but other deps (e.g. eciesjs) may load before it. @react-native-async-storage/async-storage is needed for session persistence.

Step 2: Create polyfills.ts

Create src/polyfills.ts with all required global shims. This file must be imported before anything else:

// src/polyfills.ts
// IMPORTANT: react-native-get-random-values must be imported in the
// entry file BEFORE this polyfills file. See Step 4.

import { Buffer } from 'buffer';

// Buffer global — connect-multichain self-polyfills this, but set it here
// as a safety net for other deps that may load before connect-multichain.
global.Buffer = Buffer;

// window object — required for correct platform detection and deeplink behaviour.
// connect-multichain inspects window.navigator.product and window.location to
// determine platform type and whether to use deeplinks vs install modal.
const eventListeners = new Map<string, Set<EventListener>>();
if (typeof global.window === 'undefined') {
  (global as any).window = {
    location: {
      hostname: 'my-rn-app',
      href: 'https://my-rn-app.local',
    },
    navigator: { product: 'ReactNative' },
    addEventListener: (event: string, listener: EventListener) => {
      if (!eventListeners.has(event)) eventListeners.set(event, new Set());
      eventListeners.get(event)?.add(listener);
    },
    removeEventListener: (event: string, listener: EventListener) => {
      eventListeners.get(event)?.delete(listener);
    },
    dispatchEvent: (_event: Event) => true,
  };
}

// NOTE: Event and CustomEvent polyfills are NOT needed for standalone
// @metamask/connect-evm usage — the SDK uses eventemitter3 internally.
// Add them only if you are also using wagmi (wagmi dispatches DOM events).