setup-evm-react-native-app

name	setup-evm-react-native-app
description	Scaffold a React Native app with MetaMask EVM integration including required polyfills, metro.config.js shims, import order constraints, mobile deeplinks, and a full component example

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.(event)) eventListeners.(event,  ());
      eventListeners.(event)?.(listener);
    },
    :  {
      eventListeners.(event)?.(listener);
    },
    :  ,
  };
}

Step 3: Configure metro.config.js

Metro cannot resolve Node.js built-in modules. Map them to React Native-compatible shims or an empty module:

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const path = require('path');

// Create a path to an empty module for stubs
const emptyModule = path.resolve(__dirname, 'src/empty-module.js');

const config = {
  resolver: {
    extraNodeModules: {
      stream: require.resolve('readable-stream'),
      crypto: emptyModule,
      http: emptyModule,
      https: emptyModule,
      net: emptyModule,
      tls: emptyModule,
      zlib: emptyModule,
      os: emptyModule,
      dns: emptyModule,
      assert: emptyModule,
      url: emptyModule,
      path: emptyModule,
      fs: emptyModule,
    },
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Create the empty module stub:

// src/empty-module.js
module.exports = {};

Step 4: Set up the entry file with correct import order

The import order is critical. react-native-get-random-values must be the very first import:

// index.js or App.tsx (entry file)
import 'react-native-get-random-values';  // MUST be first
import './src/polyfills';                   // MUST be second
import { AppRegistry } from 'react-native';
import App from './src/App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

If you import anything from @metamask/connect-evm before react-native-get-random-values, you will get crypto.getRandomValues is not a function.

Step 5: Create the EVM client with mobile configuration

// src/metamask.ts
import { createEVMClient, getInfuraRpcUrls } from '@metamask/connect-evm';
import { Linking } from 'react-native';
import type { MetamaskConnectEVM } from '@metamask/connect-evm';

let clientPromise: Promise<MetamaskConnectEVM> | null = null;

export function getClient(): Promise<MetamaskConnectEVM> {
  if (!clientPromise) {
    clientPromise = createEVMClient({
      dapp: {
        name: 'My RN DApp',
        url: 'https://mydapp.com',
      },
      api: {
        supportedNetworks: {
          ...getInfuraRpcUrls({ infuraApiKey: 'YOUR_INFURA_KEY', chainIds: ['0x1', '0x89'] }),
        },
      },
      ui: {
        preferExtension: false,
      },
      mobile: {
        preferredOpenLink: (deeplink: string) => Linking.(deeplink),
        : ,
      },
      : {
        
        :  {
          .(, uri);
        },
        :  {
          
          .(, accounts, chainId);
        },
      },
      : ,
    });
  }
   clientPromise;
}

mobile.preferredOpenLink is required for React Native — it tells the SDK how to open deeplinks to the MetaMask Mobile app. Without it, the connection flow will hang silently.

Step 6: Build the React Native component

// src/WalletScreen.tsx
import React, { useEffect, useRef, useState, useCallback } from 'react';
import { View, Text, TouchableOpacity, StyleSheet, Alert } from 'react-native';
import { getClient } from './metamask';
import type { MetamaskConnectEVM } from '@metamask/connect-evm';
import type { Hex, Address } from '@metamask/connect-evm';

export function WalletScreen() {
  const clientRef = useRef<MetamaskConnectEVM | null>(null);
  const [accounts, setAccounts] = useState<Address[]>([]);
  const [chainId, setChainId] = useState<Hex | null>(null);
  const [balance, setBalance] = useState<string>('');
  const [connecting, setConnecting] = useState(false);

  useEffect(() => {
    let mounted = ;

      () {
       client =  ();
       (!mounted) ;
      clientRef. = client;

       provider = client.();

      provider.(,  {
         (mounted) (accs);
      });

      provider.(,  {
         (mounted) (id);
      });

      provider.(,  {
         (mounted) {
          ([]);
          ();
          ();
        }
      });
    }

    ();
      { mounted = ; };
  }, []);

   handleConnect = ( () => {
     client = clientRef.;
     (!client) ;

    ();
     {
       result =  client.({ : [] });
      (result.  []);
      (result.  );
    }  (: ) {
       (err. === ) {
        .(, );
        ;
      }
       (err. === -) {
        .(, );
        ;
      }
      .(, err. ?? );
    }  {
      ();
    }
  }, []);

   handleDisconnect = ( () => {
     client = clientRef.;
     (!client) ;
     client.();
    ([]);
    ();
    ();
  }, []);

   fetchBalance = ( () => {
     client = clientRef.;
     (!client || accounts. === ) ;

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

     ethBalance = (wei, ) / ;
    (ethBalance.());
  }, [accounts]);

   isConnected = accounts. > ;

   (
    
  );
}

 styles = .({
  : { : , : , : , :  },
  : { : , : , : , :  },
  : { : , : , :  },
  : { : , :  },
});

Important Notes

• Import order is critical — react-native-get-random-values must be the very first import in the entry file, followed by polyfills.ts, before any SDK or application code.
• mobile.preferredOpenLink is required — without it, the SDK cannot open deeplinks to MetaMask Mobile and the connection flow will silently fail.
• ui.preferExtension should be false — React Native has no browser extension. Setting this to false (or omitting it) ensures the SDK uses the mobile deeplink/QR flow.
• Chain IDs are always hex strings — use '0x1', '0x89', '0xaa36a7'. Never decimal.
• 0x1 is auto-included in every connect() call.
• The empty module stub (src/empty-module.js) is used for Node built-ins the SDK's transitive dependencies reference but never actually call at runtime in React Native. The stream module is the exception — it needs a real shim (readable-stream).
• createEVMClient is a singleton — do not call it on every render or in a component body. Initialize once and store the promise.
• Session restoration — the EVM client syncs any persisted session before createEVMClient resolves; detect restores via the connect / accountsChanged events (in eventHandlers or on the provider). There is no wallet_sessionChanged handler on the EVM client — that event belongs to the multichain client.
• iOS requires Linking permissions — ensure your Info.plist includes the metamask URL scheme in LSApplicationQueriesSchemes so Linking.openURL can open the MetaMask app.