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-nativeor@reown/appkit-ethers-react-nativeas 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
appkitinstance (initialized viacreateAppKit) 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-nativepackage.
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: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):
- 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.
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 thisNew Multichain Implementation
With the new version, you initialize adapters first and then pass them tocreateAppKit from the core @reown/appkit-react-native package.
createAppKitis imported from@reown/appkit-react-native.- You explicitly create instances of the adapters you need (e.g.,
new EthersAdapter(),new WagmiAdapter(...)). - The
adaptersarray increateAppKittakes these initialized adapter instances. - The
networksarray increateAppKittakesAppKitNetworkobjects, which define all supported networks for AppKit’s UI and context.viem/chainsobjects can be directly used for EVM networks. - For the
WagmiAdapter, thenetworksproperty in its constructor defines which EVM chains it will specifically manage using Wagmi.
4. Provider Setup
The way you set up providers in yourApp.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 ofAppKitNetworkobjects.adapters: As described, an array of initialized adapter instances.defaultNetwork: (FormerlydefaultChain).networkImages: (FormerlychainImages).tokens: New property (Record<string, { address: string }>) for displaying token balances.
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
disconnectandswitchNetwork.
- Import from
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.
- Import from
useAppKitState():- Import from
@reown/appkit-react-native. - Provides real-time access to the modal’s current state and connection status
- Import from
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).
- Import from
useAppKitEventSubscription()(New Hook):- Import from
@reown/appkit-react-native. - Allows subscription to various AppKit lifecycle events.
- Import from
- Deprecated Hooks:
useDisconnect: Thedisconnectfunction is now available fromuseAppKit().disconnect().
7. Components Migration
Update all UI component imports to use@reown/appkit-react-native. Key components include:
<AppKit /><AppKitButton /><ConnectButton /><AccountButton /><NetworkButton />
Summary of Key Actions
- Update Dependencies: Switch to
@reown/appkit-react-nativeand add new adapter packages. - Ensure Polyfill: Add
import "@walletconnect/react-native-compat";as the very first import. - Revamp Initialization: Use the new
createAppKitsignature withnetworksandadaptersarrays. - Adjust Provider Setup: Set up
AppKitProvider. For Wagmi, usewagmiAdapter.wagmiConfigforWagmiProvider. - Update Hook Imports: Change all hook imports to
@reown/appkit-react-nativeand adapt to API changes (e.g.,useDisconnect->useAppKit().disconnect, new hooks likeuseProvider). - Update Component Imports: Change all component imports to
@reown/appkit-react-native. - Add
<AppKit />: Ensure this component is rendered for the modal UI. - Review Options: Check your
createAppKitoptions against the new Options documentation.