Upgrade from Web3Modal to Reown AppKit for React Native

This document outlines the steps to migrate from the old @web3modal packages to the new multichain @reown/appkit packages in your React Native project.

Overview of Changes#

The new AppKit architecture introduces a core library with pluggable chain adapters, providing better support for multiple blockchains (EVM, Solana, Bitcoin) in a single integration.

Key Changes:

Core Library: Use @reown/appkit-react-native as the main package
Chain Adapters: Install specific adapters for each blockchain you want to support
Unified API: All hooks and components are imported from the core package
Multichain Support: Native support for EVM, Solana, and Bitcoin chains

Step 1. Replace the dependencies using package manager commands

For Yarn users:

Remove the old Web3Modal packages:

yarn remove @web3modal/wagmi-react-native @web3modal/email-wagmi-react-native @web3modal/coinbase-wagmi-react-native @web3modal/siwe-react-native

Add the new Reown AppKit packages:

Warning

AppKit is only compatible with wagmi 2.x. Ensure you are using a compatible version.

# Core AppKit library and dependenciesyarn add @reown/appkit-react-native @react-native-async-storage/async-storage react-native-get-random-values react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat# Wagmi adapter and its dependenciesyarn add @reown/appkit-wagmi-react-native wagmi viem@2.x @tanstack/react-query# Optional: Additional adapters for other chainsyarn add @reown/appkit-solana-react-native @reown/appkit-bitcoin-react-native

Step 2. Update your AppKit configuration

Create a new AppKitConfig.ts file with the multichain setup:

// src/AppKitConfig.tsimport "@walletconnect/react-native-compat"; // MUST BE THE FIRST IMPORTimport { createAppKit } from "@reown/appkit-react-native";import { WagmiAdapter } from "@reown/appkit-wagmi-react-native";import { mainnet, sepolia } from "wagmi/chains";const projectId = "YOUR_PROJECT_ID"; // Obtain from https://dashboard.reown.com/const metadata = {  name: "My Awesome dApp",  description: "My dApp description",  url: "https://myapp.com",  icons: ["https://myapp.com/icon.png"],  redirect: {    native: "YOUR_APP_SCHEME://",    universal: "YOUR_APP_UNIVERSAL_LINK.com",  },};// Initialize Wagmi adapterconst wagmiAdapter = new WagmiAdapter({  projectId,  networks: [mainnet, sepolia], // Add all chains you want to support});export const appKit = createAppKit({  projectId,  metadata,  networks: [mainnet, sepolia], // Must match the networks in wagmiAdapter  adapters: [wagmiAdapter],  // ... other AppKit options});// Export the wagmi config for provider setupexport const wagmiConfig = wagmiAdapter.wagmiConfig;

Step 3. Update your App.tsx with providers

// App.tsximport React from 'react';import { SafeAreaProvider } from 'react-native-safe-area-context';import { AppKitProvider } from '@reown/appkit-react-native';import { WagmiProvider } from 'wagmi';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';import { appKit, wagmiConfig } from './AppKitConfig';import YourAppRootComponent from './YourAppRootComponent';const queryClient = new QueryClient();function App() {  return (    <SafeAreaProvider>      <AppKitProvider instance={appKit}>        <WagmiProvider config={wagmiConfig}>          <QueryClientProvider client={queryClient}>            <YourAppRootComponent />          </QueryClientProvider>        </WagmiProvider>      </AppKitProvider>    </SafeAreaProvider>  );}export default App;

Step 4. Update your component with AppKit UI

// YourAppRootComponent.tsximport React from 'react';import { AppKit } from '@reown/appkit-react-native';// ... other importsfunction YourAppRootComponent() {  return (    <>      {/* Your application's content */}      <AppKit /> {/* This renders the modal and other AppKit UI */}    </>  );}export default YourAppRootComponent;

Step 5. Update your Hooks usage

Update your hook imports as follows:

// Remove the following code linesimport {  useWeb3Modal,  useWeb3ModalState,  useWeb3ModalEvents,  useWalletInfo,} from "@web3modal/wagmi-react-native";// Add the following code linesimport {  useAppKit,  useAppKitState,  useAppKitEventSubscription,  useWalletInfo,} from "@reown/appkit-react-native";

Step 6. Update your Components usage

Update your component imports as follows:

// Remove the following code linesimport {  W3mAccountButton,  W3mButton,  W3mConnectButton,  W3mNetworkButton,  Web3Modal,} from "@web3modal/wagmi-react-native";// Add the following code linesimport {  AccountButton,  AppKitButton,  ConnectButton,  NetworkButton,  AppKit,} from "@reown/appkit-react-native";

Step 7. Update your config for Universal Wallets

Remove email wallet specific imports as follows:

// Remove the following code linesimport { emailConnector } from "@web3modal/email-wagmi-react-native";

Step 8. Update your import to support Coinbase Wallet

Update coinbase connector import as follows:

// Remove the following code linesimport { coinbaseConnector } from "@web3modal/coinbase-wagmi-react-native";// Add the following code linesimport { MMKV } from 'react-native-mmkv';import { CoinbaseConnector } from '@reown/appkit-coinbase-react-native';export const appKit = createAppKit({  // ...  extraConnectors: [    new CoinbaseConnector({ storage: new MMKV() })  ],  // ...});

If you are using ethers v5, follow the same steps but replacing ethers with ethers5

Step 1. Replace the dependencies using package manager commands

For Yarn users:

Remove the old Web3Modal packages:

yarn remove @web3modal/ethers-react-native @web3modal/ethers5-react-native @web3modal/email-ethers-react-native @web3modal/coinbase-ethers-react-native @web3modal/siwe-react-native

Add the new Reown AppKit packages:

# Core AppKit library and dependenciesyarn add @reown/appkit-react-native @react-native-async-storage/async-storage react-native-get-random-values react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat# Ethers adapteryarn add @reown/appkit-ethers-react-native# Optional: Additional adapters for other chainsyarn add @reown/appkit-solana-react-native @reown/appkit-bitcoin-react-native

Step 2. Update your AppKit configuration

Create a new AppKitConfig.ts file with the multichain setup:

// src/AppKitConfig.tsimport "@walletconnect/react-native-compat"; // MUST BE THE FIRST IMPORTimport { createAppKit } from "@reown/appkit-react-native";import { EthersAdapter } from "@reown/appkit-ethers-react-native";import { mainnet, polygon } from "viem/chains";const projectId = "YOUR_PROJECT_ID"; // Obtain from https://dashboard.reown.com/const metadata = {  name: "My Awesome dApp",  description: "My dApp description",  url: "https://myapp.com",  icons: ["https://myapp.com/icon.png"],  redirect: {    native: "YOUR_APP_SCHEME://",    universal: "YOUR_APP_UNIVERSAL_LINK.com",  },};// Initialize Ethers adapterconst ethersAdapter = new EthersAdapter();export const appKit = createAppKit({  projectId,  metadata,  networks: [mainnet, polygon], // Add all chains you want to support  adapters: [ethersAdapter],  // ... other AppKit options});

Step 3. Update your App.tsx with providers

// App.tsximport React from 'react';import { SafeAreaProvider } from 'react-native-safe-area-context';import { AppKitProvider } from '@reown/appkit-react-native';import { appKit } from './AppKitConfig';import YourAppRootComponent from './YourAppRootComponent';function App() {  return (    <SafeAreaProvider>      <AppKitProvider instance={appKit}>        <YourAppRootComponent />      </AppKitProvider>    </SafeAreaProvider>  );}export default App;

Step 4. Update your component with AppKit UI

// YourAppRootComponent.tsximport React from 'react';import { AppKit } from '@reown/appkit-react-native';// ... other importsfunction YourAppRootComponent() {  return (    <>      {/* Your application's content */}      <AppKit /> {/* This renders the modal and other AppKit UI */}    </>  );}export default YourAppRootComponent;

Step 5. Update your Hooks usage

Update your hook imports as follows:

// Remove the following code linesimport {  useWeb3Modal,  useWeb3ModalState,  useWeb3ModalEvents,  useWeb3ModalAccount,  useWeb3ModalProvider,  useWeb3ModalError,  useWalletInfo,} from "@web3modal/ethers-react-native";// Add the following code linesimport {  useAppKit,  useAppKitState,  useAppKitEventSubscription,  useAccount,  useProvider,  useWalletInfo,} from "@reown/appkit-react-native";

Step 6. Update your Components usage

Update your component imports as follows:

// Remove the following code linesimport {  W3mAccountButton,  W3mButton,  W3mConnectButton,  W3mNetworkButton,  Web3Modal,} from "@web3modal/ethers-react-native";// Add the following code linesimport {  AccountButton,  AppKitButton,  ConnectButton,  NetworkButton,  AppKit,} from "@reown/appkit-react-native";

Step 7. Remove email wallet specific imports as follows:

// Remove the following code linesimport { EmailProvider } from "@web3modal/email-ethers-react-native";

Step 8. Update your import to support Coinbase Wallet

Update coinbase connector import as follows:

// Remove the following code linesimport { CoinbaseProvider } from "@web3modal/coinbase-ethers-react-native";// Add the following code linesimport { MMKV } from 'react-native-mmkv';import { CoinbaseConnector } from '@reown/appkit-coinbase-react-native';export const appKit = createAppKit({  // ...  extraConnectors: [    new CoinbaseConnector({ storage: new MMKV() })  ],  // ...

Key Migration Notes#

New Hook Structure#

useWeb3Modal → useAppKit (includes open, close, disconnect, switchNetwork)
useWeb3ModalState → useAppKitState
useWeb3ModalEvents → useAppKitEventSubscription
useWeb3ModalAccount → useAccount
useWeb3ModalProvider → useProvider
useDisconnect → useAppKit

New Component Structure#

Web3Modal → AppKit
W3mButton → AppKitButton
W3mConnectButton → ConnectButton
W3mAccountButton → AccountButton
W3mNetworkButton → NetworkButton

Multichain Support#

The new AppKit supports multiple blockchains natively. You can add support for Solana and Bitcoin by installing their respective adapters:

# For Solana supportyarn add @reown/appkit-solana-react-native# For Bitcoin supportyarn add @reown/appkit-bitcoin-react-native

Then add them to your AppKitConfig.ts:

import { SolanaAdapter } from "@reown/appkit-solana-react-native";import { BitcoinAdapter } from "@reown/appkit-bitcoin-react-native";import { solana, bitcoin } from "@reown/appkit-react-native";const solanaAdapter = new SolanaAdapter();const bitcoinAdapter = new BitcoinAdapter();export const appKit = createAppKit({  // ...  networks: [mainnet, polygon, solana, bitcoin],  adapters: [ethersAdapter, solanaAdapter, bitcoinAdapter],  // ...});

Final notes#

Ensure that you have updated all relevant configurations and imports in your project to reflect the changes from Web3Modal to the new multichain AppKit.
Test your application thoroughly to ensure that the migration has been successful and that all functionality is working as expected.
Check our AppKit examples for React Native to compare with your implementation in case you are having issues
For detailed information about the new architecture, see the Migration to Multichain guide