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

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

1. Project ID — The examples use b56e18d47c72ab683b10814fe9495694, a public projectId for localhost testing only. For production, create your own project at dashboard.reown.com
2. Node 18+ and a modern bundler (Vite recommended)
3. 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 <appkit-button /> or use hooks/composables to open modal
        ↓
6. Use hooks/composables for account, network, and provider access
        ↓
7. Add your domain at [dashboard.reown.com](https://dashboard.reown.com)

Step 1 — Install packages

Always install @reown/appkit plus the adapter for your chain:

# 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

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

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

<script lang="ts" setup>
import { createAppKit } from '@reown/appkit/vue'
import { EthersAdapter } from '@reown/appkit-adapter-ethers'
import { mainnet, arbitrum } from '@reown/appkit/networks'

const projectId = 'b56e18d47c72ab683b10814fe9495694' // localhost testing only

createAppKit({
  adapters: [new EthersAdapter()],
  networks: [mainnet, arbitrum],
  projectId,
  metadata: {
    name: 'My Vue dApp',
    description: 'My Vue dApp',
    url: 'https://myapp.com',
    icons: ['https://myapp.com/icon.png']
  }
})
</script>

<template>
  <appkit-button />
</template>

Evaluations

1. Activation — "I want to add wallet connection to my React app using Wagmi. How do I set up AppKit?"
2. Non-activation — "How do I build a mobile wallet with WalletConnect?" (use WalletKit, not AppKit)
3. Edge case — "I'm using Next.js and getting hydration mismatch errors with AppKit." (Answer: enable SSR flag, use cookieToInitialState)
4. Framework choice — "I have a Vue 3 app and want to support both Ethereum and Solana. What's the setup?" (Answer: Vue + Wagmi + Solana multichain)
5. Adapter choice — "Should I use Wagmi or Ethers for my React project?" (Answer: Wagmi recommended for most cases; Ethers if already using ethers.js)
6. Edge case — "My AppKit modal shows but wallet connection fails." (Answer: check projectId, metadata.url domain match, and network config)