ConnectKit is Family's React component library for connecting EVM wallets to a dApp — a polished, themable alternative to RainbowKit and Reown's AppKit. Built on top of wagmi v2 + viem v2 with first-class WalletConnect, MetaMask, Coinbase Wallet, and Safe support, plus a built-in Sign-In with Ethereum (SIWE) button and Auth.js helper.
- 01EVM dApps wanting a beautiful drop-in connect modal
- 02wagmi v2 + viem v2 React stacks
- 03Sign-In with Ethereum (SIWE) flows with Auth.js
- 04themed connect button + chain switcher
- 05alternative to RainbowKit / Reown AppKit
- pnpm add connectkit wagmi viem@2.x @tanstack/react-query
- pnpm add connectkit-siwe-next siwe next-auth
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID | Client | WalletConnect / Reown Cloud project ID required by ConnectKit's `getDefaultConfig`. Get one at https://cloud.reown.com. Client-safe. |
| NEXTAUTH_SECRET | Server | Auth.js (NextAuth) secret used by `connectkit-siwe-next` to sign session cookies. Required server-side for SIWE. |
Use ConnectKit on top of wagmi v2 + viem v2. In a `'use client'` providers file: `const config = createConfig(getDefaultConfig({ appName: 'My App', walletConnectProjectId: 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}><ConnectKitProvider>{children}</ConnectKitProvider></QueryClientProvider></WagmiProvider>`. Render `<ConnectKitButton />` to expose the modal — fully customize via `<ConnectKitButton.Custom>` render-prop. For SIWE in Next.js, install `connectkit-siwe-next`, wrap with `<SIWEProvider {...siweConfig}>`, and use `<SIWEButton />` + `useSIWE()` to gate sessions. Wallet detection uses EIP-6963 — multi-wallet collisions are handled automatically.
- ⚑wagmi v2 lock-in: ConnectKit v2 requires wagmi v2 + viem v2; mixing wagmi v1 hooks (`useNetwork`, `useDisconnect` from v1) produces silent connector failures. Pin matching majors and follow the migration guide before upgrading.
- ⚑SSR pitfalls: `getDefaultConfig` touches `window` for storage hydration — calling it in a server component throws at build time. Place all wagmi/ConnectKit setup in a `'use client'` providers module and wrap your `app/layout.tsx` children with it.
- ⚑WalletConnect / Reown allowlist: production and Vercel preview URLs must be added to the Reown Cloud project allowlist or relay requests fail with opaque CORS errors and the modal hangs on QR scan; rotating preview URLs are particularly painful.
- ⚑SIWE Next.js helper rename: `connectkit-siwe-next` was renamed/refactored to use a `siweServer` helper inside `getServerSideProps` — the old `siwe` import path is deprecated and will silently no-op session checks. Audit your imports against the current migration guide.
- ⚑Mobile deep-links: WalletConnect v2 uses universal links to bounce into wallet apps — the `metadata.url` passed to `getDefaultConfig` must match the actual host. Vercel preview deploys with rotating URLs break the bounce-back; use a stable preview alias or feature-flag SIWE off in previews.
- ⚑Custom theming gotcha: `<ConnectKitButton.Custom>` is the only supported way to fully restyle the trigger — overriding internal CSS classes breaks across versions because ConnectKit ships scoped styles compiled at build time.
- ⚑Browser extension lifecycle: with MetaMask + Rainbow + Coinbase Wallet co-installed, EIP-6963 disambiguates correctly, but custom code reading `window.ethereum` directly will hit a non-deterministic provider — always go through the wagmi connector surface.