Wagmi: React Hooks for Web3 Development - AI-Optimized Reference

Core Technology Overview

Wagmi is a React hooks library for Ethereum development built on Viem and TanStack Query. Current stable version: v2.x

Architecture Stack

• Viem: Blockchain interaction layer (60% smaller bundles than Ethers.js, 2x faster contract reads on M1 Mac)
• TanStack Query: Caching and state management (prevents provider spam, automatic retries)
• React Hooks: Native integration with familiar patterns

Configuration Requirements

Production Settings

• Bundle size: ~1.12 MB including dependencies
• Tree-shaking removes unused wallet connectors and chains
• Requires client-side only for wallet connections (SSR consideration)

Critical Wallet Connector Setup

• MetaMask: injected() connector required
• WalletConnect: walletConnect() connector with project ID required
• Check browser dev tools - wallet extensions can self-disable

Performance Specifications

Bundle Size Comparison

Library	Size	Performance Impact
Wagmi v2	1.12 MB	Reasonable for Web3
Ethers.js v6	~60% larger	Bloated
Raw Viem	Smallest	Manual setup required

RPC Optimization

• Request batching reduces Alchemy/Infura costs significantly
• Background caching prevents duplicate calls across components
• Automatic retry with backoff for network errors

Critical Failure Modes

Wallet Connection Issues

Failure: "Provider not found" errors
Cause: Wallet connector misconfiguration or wallet not installed
Solution: Verify correct connector type and wallet installation

Failure: Connection breaks on page refresh
Cause: Inherent Web3 limitation
Mitigation: Use autoConnect option, some wallets still randomly disconnect

Transaction Failures

Failure: Transactions stuck pending indefinitely
Cause: Gas price spikes or network congestion
Resolution: Manual gas price bump required, check Etherscan for actual status

Failure: "Execution reverted" with no context
Solution: Wagmi provides actual error reasons (insufficient gas, user rejection, etc.)

Migration Considerations

v1 to v2 Migration

• Time Investment: ~3 weeks part-time for typical project
• Breaking Changes: Hook names changed (useContractRead → useReadContract)
• Connector Setup: Complete reconfiguration required
• TypeScript: Expect day of fixing type errors

Ethers.js Migration

• Gradual Approach: Wagmi provides Ethers provider adapters
• Piece-by-piece: Avoid 50k line rewrites
• Performance Gain: Noticeable speed improvement post-migration

TypeScript Integration

Automatic Type Inference

• Import contract ABI → automatic function parameter/return types
• Eliminates runtime "Cannot call function transfer with args" errors
• Global config setup required but provides excellent DX

Error Handling Improvements

• Specific failure reasons instead of generic messages
• Gas estimation details included
• User rejection vs network failure distinction

Multi-Chain Support

Built-in Network Switching

• Automatic provider switching with fallback RPCs
• Separate caches per chain prevent data contamination
• User prompts for network changes handled automatically

Resource Requirements

Development Expertise

• Required: React hooks knowledge
• Learning Curve: Minimal for React developers
• Documentation Quality: "Good enough" - start with getting started guide

Infrastructure Costs

• RPC Provider Savings: Request batching significantly reduces API calls
• Caching Benefits: Background updates reduce provider dependency
• Network Resilience: Multiple RPC fallbacks prevent downtime

Framework Compatibility

Next.js/SSR Implementation

• Critical: Wallet components must be client-side only
• Pattern: Dynamic imports with ssr: false
• Hydration: Requires proper handling to prevent mismatches

Common Implementation Pitfalls

Gas Estimation

• Reality: Gas estimation frequently wrong despite better error messages
• Mitigation: Factor in estimation inaccuracy for user experience

Network Congestion

• Impact: Transactions can fail or delay unpredictably
• User Experience: Implement proper loading states and timeout handling

Production Readiness Assessment

Adoption Indicators

• Major DeFi protocols use in production
• Active maintenance by wevm team
• 6+ months production stability reported
• Responsive maintainer support via Discord

Stability Comparison

Aspect	Wagmi	Web3-React	Ethers.js
Maintenance	Active	Dead project	Active
Production Use	Widespread	Limited	Universal
React Integration	Native	Complex context	Manual
Breaking Changes	Managed	Frequent	Stable

Decision Criteria

Choose Wagmi When:

• Building React applications
• Need TypeScript support that works
• Want built-in caching and state management
• Require multi-chain support
• Bundle size acceptable for use case

Avoid Wagmi When:

• Backend/Node.js applications required
• Bundle size critical constraint
• Team unfamiliar with React hooks
• Legacy Ethers.js integration cannot be migrated

Support Resources

Primary Documentation

• Official docs: Functional getting started guide
• GitHub issues: Responsive maintainer support
• Discord community: Most helpful for troubleshooting

Migration Tools

• v1→v2 migration guide available
• Ethers.js adapter for gradual migration
• CLI tool for contract ABI TypeScript generation