Wagmi v1 to v2 Codemod
Automated, safe, and review-friendly migration from wagmi v1 to wagmi v2.
Background
wagmi v2 introduced major API changes compared to v1. These changes include:
- hook renames and removals
- import source changes
- connector API changes
- configuration API changes
- return type and behavior changes
Migrating a real-world wagmi v1 codebase to v2 manually is time-consuming and error-prone.
This codemod is designed to automate the safe parts of the migration while clearly surfacing cases that require manual review.
What This Codemod Does
This codemod performs a best-effort migration from wagmi v1 to v2 using a rule-driven transformation set.
Automatic Migrations
Import Renames
useContractRead→useReadContractuseContractReads→useReadContractsuseContractWrite→useWriteContractuseContractEvent→useWatchContractEventuseContractInfiniteReads→useInfiniteReadContractsuseFeeData→useEstimateFeesPerGasuseSwitchNetwork→useSwitchChainuseWaitForTransaction→useWaitForTransactionReceiptWagmiConfig→WagmiProviderWagmiConfigProps→WagmiProviderProps
Import Source Changes
mainnetandsepoliamove fromwagmitowagmi/chainserc20ABIbecomeserc20Abiand moves toviem- legacy connector imports are migrated to
wagmi/connectors
Hook Call Renames
useContractRead()→useReadContract()useContractReads()→useReadContracts()useContractWrite()→useWriteContract()useContractEvent()→useWatchContractEvent()useContractInfiniteReads()→useInfiniteReadContracts()useFeeData()→useEstimateFeesPerGas()useSwitchNetwork()→useSwitchChain()useWaitForTransaction()→useWaitForTransactionReceipt()
Object Key Migrations
addressOrName→addresscontractInterface→abi
Connector Migrations
new MetaMaskConnector()→injected({ target: "metaMask" })new InjectedConnector()→injected()new CoinbaseWalletConnector()→coinbaseWallet()new SafeConnector()→safe()new WalletConnectConnector()→walletConnect()new WalletConnectLegacyConnector()→walletConnect()
Identifier and JSX Renames
WagmiConfig→WagmiProviderWagmiConfigProps→WagmiProviderPropserc20ABI→erc20Abi- multiple wagmi v1 config and result type names are updated to wagmi v2 equivalents
Review Annotations
Some wagmi v2 changes cannot be migrated safely with a fully automatic rewrite.
For these cases, the codemod adds review annotations instead of making risky silent changes.
Examples include:
- removed hooks such as
usePrepareContractWriteandusePrepareSendTransaction - removed APIs such as
configureChains,useNetwork,useWebSocketPublicClient, andgetConfig - mutation hook setup argument changes
- return value shape changes such as
data?.hash - removed options such as
watchandsuspense useBalance({ token })anduseToken()migration guidancecreateConfiglegacy key review- connector migration review notes
- destructuring and return-shape review for
useAccount,useConnect, anduseDisconnect
Example Annotation
Example
Before
After
Example with Review Annotation
The codemod intentionally adds comments for cases that require manual review instead of performing unsafe automatic rewrites.
Additional Annotated Cases
ENS Behavior Changes
useEnsAddress,useEnsAvatar, anduseEnsResolverno longer perform internal ENS normalization- ENS names may require explicit normalization using viem utilities
TanStack Query Option Changes
Options such as the following are no longer top-level:
enabledstaleTimegcTimerefetchInterval
These options must now be nested under a query property.
Pagination API Changes
paginatedIndexesConfigis removed fromuseInfiniteReadContracts- migrate to
initialPageParamand pagination helpers such asgetNextPageParam
Mutation Hook API Changes
Setup arguments are removed from:
useWriteContractuseSendTransactionuseSignMessageuseSignTypedDatauseDeployContractuseSwitchChain
Parameters must be passed when the returned action is invoked.
Transaction Result Shape Changes
Affects:
useSendTransactionuseWriteContract
data is now the transaction hash directly instead of { hash }.
Account and Connection Return Shape Changes
Destructuring from the following requires review:
useAccountuseConnectuseDisconnect
Fields such as account, chain, and connector require manual validation.
wagmi Provider Removals
Removed import paths:
wagmi/providers/alchemywagmi/providers/publicwagmi/providers/infurawagmi/providers/jsonRpc
Developers should migrate to Viem transports via createConfig.
Config API Changes
Removed or changed properties on config include:
connectordataerrorlastUsedChainIdpublicClientstatuswebSocketClientclearStatesetConnectorssetLastUsedConnectorautoConnect
Design Philosophy
This codemod is a best-effort migration assistant, not a compiler-grade semantic rewrite.
- safe and mechanical changes are automated
- risky or ambiguous changes are surfaced for review
- developer intent is never guessed
This approach prioritizes correctness, stability, and clarity over unsafe full automation.
How to Use
Example
Running the codemod on a Git-tracked project is recommended so changes can be reviewed safely.
Scope and Limitations
- covers the majority of real-world wagmi v1 to v2 migration patterns
- focuses on safe and deterministic transformations
- surfaces risky changes via explicit annotations
- does not attempt unsafe semantic rewrites
- does not guarantee zero manual follow-up
This codemod is a migration assistant, not a one-click upgrade tool.
Summary
This project provides a rule-driven wagmi v1 to v2 codemod.
It automates repetitive migration work, clearly surfaces risky changes, and is designed for real-world production codebases.
The goal is to significantly reduce migration effort while preserving correctness and developer control.