Wagmi — Reactive Primitives for Ethereum Apps

Introduction

Wagmi provides type-safe React hooks (and Vue composables) for every common Ethereum DApp interaction. It wraps the low-level Viem library with a reactive caching layer powered by TanStack Query. Developers use Wagmi to build wallet-connected frontends without managing RPC calls, connection state, or chain switching manually.

What Wagmi Does

• Connects to browser wallets (MetaMask, WalletConnect, Coinbase Wallet) via configurable connectors
• Reads on-chain data with automatic caching, polling, and request deduplication
• Sends transactions and waits for confirmations with useWriteContract and useWaitForTransactionReceipt
• Handles multi-chain configuration and chain switching in a single config object
• Generates type-safe hooks from contract ABIs at build time via the CLI

Architecture Overview

Wagmi is structured around a core configuration object that defines chains, transports (RPC endpoints), and wallet connectors. React hooks (or Vue composables) consume this config through a context provider. Under the hood, each hook delegates to Viem for chain interaction and TanStack Query for state management, caching, and background refetching. The @wagmi/cli tool generates contract hooks from ABIs, Etherscan addresses, or Foundry/Hardhat artifacts.

Self-Hosting & Configuration

• Install wagmi, viem, and @tanstack/react-query as peer dependencies
• Create a config with createConfig({ chains, transports, connectors }) specifying your chains and RPC URLs
• Wrap the React tree with <WagmiProvider> and <QueryClientProvider>
• Use @wagmi/cli to generate typed contract hooks from ABI files or verified Etherscan contracts
• Configure SSR support for Next.js apps by serializing state with cookieStorage

Key Features

• Full TypeScript inference on contract read/write hooks based on ABI
• Built-in connectors for MetaMask, WalletConnect v2, Coinbase, and injected providers
• Automatic request batching via Viem multicall support
• CLI code generation from ABIs, Etherscan, or build artifacts
• Supports React and Vue with a shared core package

Comparison with Similar Tools

• RainbowKit — Pre-built connect modal UI built on Wagmi; Wagmi is the underlying hooks layer
• ConnectKit — Another connect modal built on Wagmi; Wagmi provides the programmatic API
• web3-react — Earlier React integration by Uniswap; Wagmi offers modern hooks and better TypeScript support
• useDApp — React hooks library for Ethereum; Wagmi has broader adoption and Viem integration

FAQ

Q: Do I need Viem to use Wagmi? A: Yes. Wagmi uses Viem internally for all chain interactions. Both are installed together.

Q: Does Wagmi work with Next.js SSR? A: Yes. Wagmi supports server-side rendering by persisting state to cookies and rehydrating on the client.

Q: Can I use Wagmi with Vue? A: Yes. The @wagmi/vue package provides Vue composables with the same API surface as the React hooks.

Q: How do I add a custom chain? A: Define a chain object with the chain ID, name, RPC URLs, and block explorer, then include it in the config.

Sources

• https://github.com/wevm/wagmi
• https://wagmi.sh