Skip to main content
This guide will walk you through the necessary steps to update your existing Reown AppKit React Native integration to the latest multichain version. The new version introduces a more flexible and powerful architecture, centered around a core AppKit library and distinct chain-specific adapters.

Key Changes at a Glance

Before diving into the specific steps, here’s a high-level overview of the most significant changes:
  • Core Library & Adapters: Instead of using monolithic, EVM-specific packages like @reown/appkit-wagmi-react-native or @reown/appkit-ethers-react-native as your primary entry point, you will now use a core package @reown/appkit-react-native. Chain-specific logic for EVM (Ethers, Wagmi), Solana, Bitcoin, and potentially other chains is handled by separate, installable adapter packages (e.g., @reown/appkit-ethers-react-native, @reown/appkit-solana-react-native).
  • Centralized Logic: The new appkit instance (initialized via createAppKit) becomes the central hub for managing connections, adapters, and events across multiple chains.
  • Unified Hooks & Components: Hooks and UI components are now consistently imported from the core @reown/appkit-react-native package.

1. Dependency Updates

Your first step is to update your project’s dependencies.

a. Remove Old Packages (If Applicable)

If you were previously using older, specific AppKit packages like @web3modal/* or potentially differently named predecessors to @reown/appkit-*-react-native, you should remove them. The primary packages to focus on now are @reown/appkit-react-native and the new chain adapters.

b. Install Core Package & Polyfills/Helpers

Install the main AppKit library along with essential peer dependencies for React Native:
Then, for iOS in React Native CLI projects:

c. Install Chain Adapter Packages

Based on the blockchains your dApp needs to support, install the corresponding adapter packages. Here are the primary ones:
  • EVM (Ethers):
  • EVM (Wagmi):
    AppKit is only compatible with wagmi 2.x. Ensure you are using a compatible version.
  • Solana:
  • Bitcoin:
The package names for adapters like @reown/appkit-ethers-react-native and @reown/appkit-wagmi-react-native are the same as some older, more monolithic packages. The key difference is how they are used (as pluggable adapters into the core @reown/appkit-react-native).

2. Crucial Polyfill Import

To ensure proper functioning, especially for WalletConnect features within React Native, the @walletconnect/react-native-compat package must be imported at the very beginning of your application’s entry point or your AppKit configuration file.
This step is critical for avoiding runtime errors related to missing polyfills.

3. AppKit Initialization (createAppKit)

The way you initialize AppKit has changed significantly to support the new adapter-based architecture.

Old Implementation

Previously, for an EVM setup with Wagmi, you might have done something like this

New Multichain Implementation

With the new version, you initialize adapters first and then pass them to createAppKit from the core @reown/appkit-react-native package.
Key differences in initialization:
  • createAppKit is imported from @reown/appkit-react-native.
  • You explicitly create instances of the adapters you need (e.g., new EthersAdapter(), new WagmiAdapter(...)).
  • The adapters array in createAppKit takes these initialized adapter instances.
  • The networks array in createAppKit takes AppKitNetwork objects, which define all supported networks for AppKit’s UI and context. viem/chains objects can be directly used for EVM networks.
  • For the WagmiAdapter, the networks property in its constructor defines which EVM chains it will specifically manage using Wagmi.

4. Provider Setup

The way you set up providers in your App.tsx (or equivalent root file) has minor adjustments, especially if you are using Wagmi.

a. AppKitProvider

You will now need to wrap your application (or the relevant part) with AppKitProvider from @reown/appkit-react-native. This provider makes the AppKit instance, created in the previous step, available to all child components and hooks.

b. Wagmi Specific Providers (WagmiProvider, QueryClientProvider)

If you’re using the WagmiAdapter, you still need to set up WagmiProvider (from wagmi) and QueryClientProvider (from @tanstack/react-query) as you did before. The primary change is that the config prop for WagmiProvider now comes directly from your initialized WagmiAdapter instance’s wagmiConfig property.

c. Rendering AppKit UI

Ensure the <AppKit /> component (imported from @reown/appkit-react-native) is included in your app’s component tree, typically in your root component, to render the modal UI. This was likely already in place.

5. Configuration Options (createAppKit parameters)

Many configuration options previously passed to createAppKit (or defaultConfig/defaultWagmiConfig) are still available but are now part of the single createAppKit call from @reown/appkit-react-native.
  • networks: As described above, an array of AppKitNetwork objects.
  • adapters: As described, an array of initialized adapter instances.
  • defaultNetwork: (Formerly defaultChain).
  • networkImages: (Formerly chainImages).
  • tokens: New property (Record<string, { address: string }>) for displaying token balances.
Refer to the Options documentation for the complete and up-to-date list of configuration parameters.

6. Hooks Migration

All AppKit hooks are now imported directly from @reown/appkit-react-native.
  • useAppKit():
    • Import from @reown/appkit-react-native.
    • Still the primary hook for modal control (open, close, isOpen).
    • Now also includes actions like disconnect and switchNetwork.
  • useAccount():
    • Import from @reown/appkit-react-native.
    • Provides address, chainId, isConnected, and potentially other multichain-aware details. Functionality is largely the same; primary change is the import path and potentially more multichain-aware return values.
  • useAppKitState():
    • Import from @reown/appkit-react-native.
    • Provides real-time access to the modal’s current state and connection status
  • useProvider() (New Hook):
    • Import from @reown/appkit-react-native.
    • Use this to get the underlying chain-specific provider/client (e.g., Ethers provider, Wagmi client, Solana connection).
  • useAppKitEventSubscription() (New Hook):
    • Import from @reown/appkit-react-native.
    • Allows subscription to various AppKit lifecycle events.
  • Deprecated Hooks:
    • useDisconnect: The disconnect function is now available from useAppKit().disconnect().
Review the Hooks documentation for detailed API information.

7. Components Migration

Update all UI component imports to use @reown/appkit-react-native. Key components include:
  • <AppKit />
  • <AppKitButton />
  • <ConnectButton />
  • <AccountButton />
  • <NetworkButton />
Their core functionality and props remain largely the same as before, but ensure you’re importing them from the new unified package. Refer to the Components documentation for details on props if needed.

Summary of Key Actions

  1. Update Dependencies: Switch to @reown/appkit-react-native and add new adapter packages.
  2. Ensure Polyfill: Add import "@walletconnect/react-native-compat"; as the very first import.
  3. Revamp Initialization: Use the new createAppKit signature with networks and adapters arrays.
  4. Adjust Provider Setup: Set up AppKitProvider. For Wagmi, use wagmiAdapter.wagmiConfig for WagmiProvider.
  5. Update Hook Imports: Change all hook imports to @reown/appkit-react-native and adapt to API changes (e.g., useDisconnect -> useAppKit().disconnect, new hooks like useProvider).
  6. Update Component Imports: Change all component imports to @reown/appkit-react-native.
  7. Add <AppKit />: Ensure this component is rendered for the modal UI.
  8. Review Options: Check your createAppKit options against the new Options documentation.
This migration involves some significant structural changes, but the result is a more robust and flexible system for building multichain React Native applications. If you encounter issues, refer to the main documentation pages or seek support.