wagmi-v1-to-v2
One command migrates your wagmi v1 codebase to v2. Deterministic AST transforms with zero false positives.
Tested on scaffold-eth-2 with 100% safety.
What it does
Automatically migrates the most common wagmi v1 → v2 patterns:
| Pattern | Migration |
|---|---|
useContractRead | → useReadContract |
useContractWrite | → useWriteContract |
usePrepareContractWrite | → useSimulateContract |
useWaitForTransaction | → useWaitForTransactionReceipt |
useSwitchNetwork | → useSwitchChain |
WagmiConfig | → WagmiProvider |
createClient (from wagmi only) | → createConfig |
configureChains() | Flagged with TODO |
onSuccess/onError callbacks | Flagged with TODO |
autoConnect config | Flagged with TODO |
watch: true | Flagged with TODO |
What needs manual follow-up
- Connector API rewrites:
InjectedConnector()→injected(), etc. - Custom
useBalance()token param removals - Transport configuration setup
- TanStack Query v5 migration patterns
Installation
Usage
Case Study: scaffold-eth-2
Repository: https://github.com/scaffold-eth/scaffold-eth-2
Branch: main (commit)
Results
- Files changed: 1 (code transformations only; CLAUDE.md is skill metadata)
- Hook renames applied: 5+ usages found and transformed
- False positives: 0 (viem
createClientcorrectly preserved) - TypeScript errors before: 0
- TypeScript errors after: 0
- Compile-time safety: ✅ Verified
Key Evidence
The migration successfully avoided false positives:
- ✅
packages/nextjs/services/web3/wagmiConfig.tsxusescreateClientfrom"viem"— correctly untouched - ✅ Hook comment references auto-updated (
useContractRead→useReadContractin JSDoc) - ✅ Zero import errors or unresolved references
- ✅ Zero new TS compilation errors
How it works
- rename-hooks: Global replacement of v1 hook names to v2 using exact word boundaries
- rename-provider:
WagmiConfig→WagmiProvider(lexical substitution) - migrate-config: Source-aware migration of
createClient/createConfig:- ✅ Only renames if imported from
"wagmi" - ✅ Skips imports/calls from
"viem"or other sources - ✅ Preserves code formatting
- ✅ Only renames if imported from
- migrate-callbacks: Flags callback patterns with TODO comments for manual migration
- install-skill: Registers Claude MCP skill for AI-assisted edge cases
False Positive Policy
All transforms verify the import source before modifying code:
createClientfrom"wagmi"→ renamed tocreateConfigcreateClientfrom"viem"→ left untouched- Ambiguous cases → flagged with TODO, never silently rewritten
Test Coverage
Local fixture tests verify:
- ✅ Main transformation case (v1 → v2)
- ✅ Already-v2 code (idempotent, no changes)
- ✅ Aliased imports (preserves alias)
- ✅ Local shadowing (respects local functions)
- ✅ viem createClient (never renamed)
- ✅ Idempotency (running twice = same result)
All tests pass with npx codemod jssg test.
Development
Publish to Registry
Compatibility
- ✅ TypeScript + TSX
- ✅ wagmi v1.x → v2.x
- ✅ Node.js 18+
- ✅ Monorepos (processes all matching files)
License
MIT