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 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-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: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.
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 increateAppKit
takes these initialized adapter instances. - The
networks
array increateAppKit
takesAppKitNetwork
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
, thenetworks
property 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 ofAppKitNetwork
objects.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
disconnect
andswitchNetwork
.
- 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
: Thedisconnect
function 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-native
and add new adapter packages. - Ensure Polyfill: Add
import "@walletconnect/react-native-compat";
as the very first import. - Revamp Initialization: Use the new
createAppKit
signature withnetworks
andadapters
arrays. - Adjust Provider Setup: Set up
AppKitProvider
. For Wagmi, usewagmiAdapter.wagmiConfig
forWagmiProvider
. - Update Hook Imports: Change all hook imports to
@reown/appkit-react-native
and 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
createAppKit
options against the new Options documentation.