Reown AppKit — Web Integration
Goal
Help developers integrate Reown AppKit so their users can connect wallets, switch networks, and interact with EVM, Solana, and Bitcoin blockchains. AppKit provides a universal modal UI and hooks/composables for wallet management.
When to use
Adding wallet connection to a web app (React, Next.js, Vue, Nuxt, Svelte, JavaScript)
Setting up multi-chain support (EVM + Solana + Bitcoin)
Configuring blockchain adapters (Wagmi, Ethers, Solana, Bitcoin)
Debugging AppKit initialization, modal, or connection issues
Implementing Sign In With X (SIWX) authentication
Choosing the right adapter for a project
When not to use
Building native mobile apps (use AppKit mobile SDKs — separate product)
WalletKit integration for wallet developers (separate SDK)
WalletConnect Pay (use the walletconnect-pay skill)
Supported Platforms & Adapters
Frameworks:
React, Next.js, Vue, Nuxt, Svelte, vanilla JavaScript
Adapters:
Wagmi (EVM), Ethers v5/v6 (EVM), Solana, Bitcoin
Networks:
All EVM chains, Solana, Bitcoin
Choose Your Framework
Framework
Import path
Notes
React
@reown/appkit/react
Hooks-based
Next.js
@reown/appkit/react
SSR + cookie hydration required
Vue
@reown/appkit/vue
Composables-based
Nuxt
@reown/appkit/vue
SSR + module config required
Svelte
@reown/appkit
Stores-based
JavaScript
@reown/appkit
No framework dependency
Jump to the right reference:
React + Wagmi
React + Ethers
React + Solana
React + Bitcoin
React + Multichain
Next.js + Wagmi
Next.js + Ethers
Next.js + Solana
Next.js + Multichain
Vue + Wagmi
Vue + Ethers
Vue + Solana
Vue + Multichain
Nuxt + Wagmi
Svelte + Wagmi
JavaScript + Wagmi
JavaScript + Ethers
JavaScript + Solana
JavaScript + Multichain
Prerequisites
Project ID
— The examples use
b56e18d47c72ab683b10814fe9495694
, a public projectId for
localhost testing only
. For production, create your own project at
dashboard.reown.com
Node 18+
and a modern bundler (Vite recommended)
Choose an adapter based on your chain requirements
Universal Setup Flow (all frameworks)
Every integration follows these steps:
1. Install packages (appkit + adapter)
↓
2. Configure adapter (projectId, networks)
↓
3. Call createAppKit({ adapters, networks, projectId, metadata })
↓
4. Wrap app with required providers (framework-specific)
↓
5. Add
EVM with Wagmi (most common)
npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi viem @tanstack/react-query
EVM with Ethers v6
npm install @reown/appkit @reown/appkit-adapter-ethers ethers
Solana
npm install @reown/appkit @reown/appkit-adapter-solana
Bitcoin
npm install @reown/appkit @reown/appkit-adapter-bitcoin Step 2 — Configure and create AppKit import { createAppKit } from '@reown/appkit/react' // or /vue or just @reown/appkit import { WagmiAdapter } from '@reown/appkit-adapter-wagmi' import { mainnet , arbitrum } from '@reown/appkit/networks' const projectId = 'b56e18d47c72ab683b10814fe9495694' // Public projectId for localhost only const networks = [ mainnet , arbitrum ] const wagmiAdapter = new WagmiAdapter ( { networks , projectId , } ) const modal = createAppKit ( { adapters : [ wagmiAdapter ] , networks , projectId , metadata : { name : 'My App' , description : 'My App Description' , url : 'https://myapp.com' , // Must match your domain icons : [ 'https://myapp.com/icon.png' ] } , features : { analytics : true } } ) Step 3 — Trigger the modal // Web component (works everywhere) < appkit-button /> // React hook import { useAppKit } from '@reown/appkit/react' const { open } = useAppKit ( ) < button onClick = { ( ) => open ( ) }
Connect </ button
// Vue composable import { useAppKit } from '@reown/appkit/vue' const { open } = useAppKit ( ) Step 4 — Access account and network // React import { useAppKitAccount , useAppKitNetwork } from '@reown/appkit/react' const { address , isConnected , caipAddress } = useAppKitAccount ( ) const { caipNetwork , switchNetwork } = useAppKitNetwork ( ) Key Hooks / Composables Hook Returns Purpose useAppKit open() , close() Control modal useAppKitAccount address , isConnected , caipAddress , status Account state useAppKitNetwork caipNetwork , chainId , switchNetwork() Network state useAppKitProvider walletProvider Raw provider access useAppKitState initialized , loading , open , selectedNetworkId Modal state useDisconnect disconnect() Disconnect wallet useAppKitBalance fetchBalance() Token balance useWalletInfo walletInfo Wallet metadata Best Practices 1. Keep all AppKit package versions aligned All @reown/appkit packages must be the same version . Mixing versions causes subtle runtime errors (missing methods, broken state, silent failures). // package.json — correct: all versions match { "@reown/appkit" : "1.7.1" , "@reown/appkit-adapter-wagmi" : "1.7.1" , "@reown/appkit-adapter-solana" : "1.7.1" } When upgrading, update every @reown/appkit package together. 2. Call createAppKit at module level — never inside a component createAppKit must run once as a side-effect at module scope. Calling it inside a React component, Vue setup() , or Svelte component causes duplicate instances and broken state on re-renders. // DO — module-level (runs once on import) import { createAppKit } from '@reown/appkit/react' import { wagmiAdapter , projectId , networks , metadata } from './config' createAppKit ( { adapters : [ wagmiAdapter ] , networks , projectId , metadata } ) export default function App ( ) { return < appkit - button /
} // DON'T — inside a component (runs on every render) export default function App ( ) { createAppKit ( { adapters : [ wagmiAdapter ] , networks , projectId , metadata } ) // BUG return < appkit - button /
} 3. Wagmi OR Ethers — never both Both WagmiAdapter and EthersAdapter register the EVM ( eip155 ) namespace. Using both in the same project causes conflicts. New projects: use Wagmi — better React hook integration, active ecosystem, broader wallet support Existing ethers.js codebase: use Ethers to avoid rewriting provider logic // DO — one EVM adapter createAppKit ( { adapters : [ wagmiAdapter , solanaAdapter ] , ... } ) // DON'T — two EVM adapters createAppKit ( { adapters : [ wagmiAdapter , ethersAdapter ] , ... } ) // CONFLICT Multichain Setup Pass multiple adapters to createAppKit : import { WagmiAdapter } from '@reown/appkit-adapter-wagmi' import { SolanaAdapter } from '@reown/appkit-adapter-solana' import { mainnet , arbitrum , solana , solanaDevnet } from '@reown/appkit/networks' const wagmiAdapter = new WagmiAdapter ( { networks : [ mainnet , arbitrum ] , projectId } ) const solanaAdapter = new SolanaAdapter ( ) createAppKit ( { adapters : [ wagmiAdapter , solanaAdapter ] , networks : [ mainnet , arbitrum , solana , solanaDevnet ] , projectId , metadata , } ) Validation checklist projectId obtained from dashboard.reown.com metadata.url matches your actual domain (wallets verify this) Networks imported from @reown/appkit/networks (not from viem/wagmi directly) For Next.js: SSR flag set, cookie hydration implemented, webpack externals configured For Wagmi: WagmiProvider and QueryClientProvider wrapping the app Adapter matches target chain (don't use WagmiAdapter for Solana) createAppKit called once at app initialization (not inside components) Common errors Error Cause Fix "Project ID is required" Missing projectId Get one from dashboard.reown.com Hydration mismatch (Next.js) Missing SSR config Add ssr: true to WagmiAdapter, use cookieToInitialState Modal not appearing createAppKit not called Ensure it runs before app renders Network not switching Wrong network import Use @reown/appkit/networks , not viem Webpack error (Next.js) Missing externals config Add pino-pretty , lokijs , encoding to webpack externals Provider undefined Accessing before connection Check isConnected before using provider Examples Example 1 — React + Wagmi basic setup // config.ts import { WagmiAdapter } from '@reown/appkit-adapter-wagmi' import { mainnet , arbitrum , base } from '@reown/appkit/networks' export const projectId = 'b56e18d47c72ab683b10814fe9495694' // localhost testing only export const networks = [ mainnet , arbitrum , base ] export const wagmiAdapter = new WagmiAdapter ( { networks , projectId } ) export const metadata = { name : 'My dApp' , description : 'My dApp description' , url : 'https://mydapp.com' , icons : [ 'https://mydapp.com/icon.png' ] } // App.tsx import { createAppKit } from '@reown/appkit/react' import { WagmiProvider } from 'wagmi' import { QueryClient , QueryClientProvider } from '@tanstack/react-query' import { projectId , networks , wagmiAdapter , metadata } from './config' const queryClient = new QueryClient ( ) createAppKit ( { adapters : [ wagmiAdapter ] , networks , projectId , metadata , features : { analytics : true } } ) export default function App ( ) { return ( < WagmiProvider config = { wagmiAdapter . wagmiConfig }
< QueryClientProvider client = { queryClient }
< appkit-button /> </ QueryClientProvider
</ WagmiProvider
) } Example 2 — Vue + Ethers basic setup