appkit

SKILL.md

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 <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

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

<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

Activation — "I want to add wallet connection to my React app using Wagmi. How do I set up AppKit?"

Non-activation — "How do I build a mobile wallet with WalletConnect?" (use WalletKit, not AppKit)

Edge case — "I'm using Next.js and getting hydration mismatch errors with AppKit." (Answer: enable SSR flag, use cookieToInitialState)

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)

Adapter choice — "Should I use Wagmi or Ethers for my React project?" (Answer: Wagmi recommended for most cases; Ethers if already using ethers.js)

Edge case — "My AppKit modal shows but wallet connection fails." (Answer: check projectId, metadata.url domain match, and network config)