wagmi v1 → v2 Migration Codemod
A production-grade codemod that automates ~80% of the wagmi v1 → v2 migration with zero false positives.
Built with the Codemod toolkit.
What it automates
| Pattern | Coverage | Method |
|---|---|---|
Hook renames (useContractRead → useReadContract, etc.) | ✅ Automated | Deterministic |
Connector renames + class→function (new WalletConnectConnector → walletConnect()) | ✅ Automated | Deterministic |
Connector import paths (wagmi/connectors/* → @wagmi/connectors) | ✅ Automated | Deterministic |
WagmiConfig → WagmiProvider (import + JSX) | ✅ Automated | Deterministic |
client= prop → config= prop | ✅ Automated | Deterministic |
package.json peer dependency upgrades | ✅ Automated | Deterministic |
createClient → createConfig | ⚠️ Flagged | Manual/AI |
configureChains removal | ⚠️ Flagged | Manual/AI |
TanStack Query options → query: {} | ⚠️ Flagged | Manual/AI |
| Mutation args moved to function | ⚠️ Flagged | Manual/AI |
Hook renames handled
| v1 | v2 |
|---|---|
useContractRead | useReadContract |
useContractReads | useReadContracts |
useContractWrite | useWriteContract |
usePrepareContractWrite | useSimulateContract |
usePrepareSendTransaction | useEstimateGas |
useWaitForTransaction | useWaitForTransactionReceipt |
useSwitchNetwork | useSwitchChain |
useNetwork | useChainId |
useWebSocketPublicClient | usePublicClient |
Connector renames handled
| v1 (class) | v2 (function) |
|---|---|
new CoinbaseWalletConnector({...}) | coinbaseWallet({...}) |
new InjectedConnector() | injected() |
new MetaMaskConnector() | injected() |
new SafeConnector({...}) | safe({...}) |
new WalletConnectConnector({...}) | walletConnect({...}) |
new WalletConnectLegacyConnector({...}) | walletConnect({...}) |
Usage
Output
The CLI:
- ✅ Lists every file it changes
- ⚠️ Prints all items needing manual/AI attention with links to docs
- Tells you to run
npm installafter finishing
Running tests
36 tests, all passing. Coverage includes:
- Every hook rename
- All connector transforms
- Config API changes
- Package.json upgrades
- False positive prevention (hooks from non-wagmi libraries are never touched)
- Full pipeline integration tests
Design principles
Zero false positives. The codemod tracks which hooks are actually imported from wagmi before touching any usage sites. A hook named useContractRead imported from some-other-lib is never renamed.
Detect, don't mangle. For patterns that require understanding control flow or object structure (TanStack Query options, mutation args), we detect and flag them with actionable error messages rather than risk producing incorrect code.
One transform per concern. Each transform file handles exactly one class of change, making them independently testable and easy to audit.
After running
- Run
npm installto install upgraded dependencies - Address all
MANUAL:warnings in the output (these are the ~20% requiring human judgment) - Run your build and test suite
- Key manual items:
- Replace
createClient+configureChainswithcreateConfig+transports - Move TanStack Query options into
query: {}on read hooks - Move mutation args from hook call to the returned function call
- Replace