Wallet / Auth·EVM
Rainbow + RainbowKit
Rainbow EVM wallet (mobile + extension) plus RainbowKit, the most popular React library for adding a polished wallet-connect UI to wagmi/viem dApps. Bundles connectors for Rainbow, MetaMask, Coinbase Wallet, WalletConnect, and 100+ others.
- 01EVM dApps wanting a turnkey wallet modal
- 02wagmi/viem React stacks
- 03multi-wallet support out of the box
- 04Sign-In with Ethereum (RainbowKitSiweNextAuthProvider)
- 05themed connect button + chain switcher
- pnpm add @rainbow-me/rainbowkit wagmi viem@2.x @tanstack/react-query
- pnpm add @rainbow-me/rainbowkit-siwe-next-auth siwe
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID | Client | WalletConnect / Reown Cloud project ID required by `getDefaultConfig`. Get one at https://cloud.reown.com. Client-safe. |
Use RainbowKit on top of wagmi v2 + viem v2. In a `'use client'` providers file: `const config = getDefaultConfig({ appName: 'My App', projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!, chains: [mainnet, base, optimism, arbitrum], ssr: true });` then wrap the tree in `<WagmiProvider config={config}><QueryClientProvider client={queryClient}><RainbowKitProvider>{children}</RainbowKitProvider></QueryClientProvider></WagmiProvider>`. Render `<ConnectButton />` to expose the modal. Use wagmi hooks for state: `useAccount()`, `useSignMessage()`, `useSendTransaction()`. For SIWE, wrap with `<RainbowKitSiweNextAuthProvider getSiweMessageOptions={() => ({ statement: 'Sign in to My App' })}>` so the connect button auto-prompts a SIWE signature that authenticates the wagmi session against Auth.js.
- ⚑RainbowKit v2 requires wagmi v2 + viem v2 — mixing wagmi v1 (`useNetwork`, `useDisconnect` from v1) with RainbowKit v2 produces silent connector failures; check the migration guide and pin matching majors.
- ⚑`getDefaultConfig` must run on the client (or with `ssr: true`) — calling it in a server component throws because it touches `window` for storage; place it in a `'use client'` providers module.
- ⚑WalletConnect/Reown allowlist: production and Vercel preview URLs must be added in the Reown dashboard or relay requests fail with opaque CORS errors and the modal hangs on QR scan.
- ⚑Mobile deep-links: WalletConnect v2 uses universal links to bounce into wallet apps — iOS Safari requires the `@reown/appkit` `metadata.url` to match the actual host; preview deploys with rotating URLs break the bounce-back.
- ⚑Hardware wallets (Ledger via MetaMask) reject EIP-712 typed-data signing if the `domain.chainId` is sent as a string instead of a number — viem handles this correctly but custom `signTypedData` payloads must use a number.
- ⚑Browser extension lifecycle: MetaMask + Rainbow extension simultaneously installed causes EIP-1193 provider collisions on `window.ethereum` — RainbowKit uses EIP-6963 to disambiguate, but custom code that reads `window.ethereum` directly will hit the wrong wallet randomly.
- ⚑`<ConnectButton.Custom />` is the only supported way to fully restyle the button — overriding internal CSS classes breaks across versions because RainbowKit ships scoped styles.