How I Automated the Entire Web3 Frontend Stack Migration in One Command

#web3 #ethereum #javascript #opensource

Every production dApp built in 2022–2023 has the same problem sitting in its package.json:

"wagmi": "^1.4.12",
"ethers": "^5.7.2",
"@rainbow-me/rainbowkit": "^1.3.5"

These three libraries are tightly coupled. wagmi v2 dropped ethers entirely in favor of viem. RainbowKit v2 requires wagmi v2. Migrating one without the others breaks everything.

Every team I've seen approach this migration does it the same painful way: manually, file by file, over days or weeks, with a non-trivial chance of introducing bugs.

I built a codemod that does it in one command.

The Approach

The core insight is that these migrations aren't independent — they're a stack. So the tool needs to treat them as one orchestrated workflow, not three separate tools you run and hope don't conflict.

The workflow has three phases:

Phase 1 — Detection
Reads package.json and sets flags for which migrations to run. If you're already on wagmi v2 but still on ethers v5, it only runs the ethers migration. No unnecessary transforms.

Phase 2 — Deterministic transforms
jssg (JavaScript ast-grep) handles every pattern that has exactly one correct answer:

For wagmi v1 → v2:

useContractRead → useReadContract
useContractWrite → useWriteContract
usePrepareContractWrite → useSimulateContract
useWaitForTransaction → useWaitForTransactionReceipt
WagmiConfig → WagmiProvider (import + JSX opening and closing tags)
createClient → createConfig
Import paths: wagmi/chains → viem/chains

For ethers v5 → v6:

ethers.providers.Web3Provider → ethers.BrowserProvider
ethers.providers.JsonRpcProvider → ethers.JsonRpcProvider
Full ethers.utils namespace flattening — parseEther, formatEther, keccak256, arrayify → getBytes, hexZeroPad → zeroPadValue, and more
ethers.BigNumber.from(x) → BigInt(x)
.callStatic.method() → .method.staticCall()

For RainbowKit v1 → v2:

<RainbowKitProvider chains={chains}> → <RainbowKitProvider>
getDefaultWallets chains param removal
configureChains flagged with a TODO comment for AI cleanup

Phase 3 — AI skill for edge cases
A bundled Claude skill handles the ~20% that can't be deterministic:

getSigner() is now async — sync usage needs await
BigNumber arithmetic chains (.add().mul()) → native bigint operators
configureChains removal — restructuring chains into createConfig
QueryClientProvider wrapping between WagmiProvider and RainbowKitProvider

Proving It on a Real Repo

I tested on scaffold-eth-2 pinned to wagmi 1.4.12 + RainbowKit 1.3.5 — one of the most widely forked Ethereum starter repos on GitHub.

Results:

104 files scanned
8 files transformed
0 false positives
19 seconds

Here's what the ScaffoldEthAppWithProviders.tsx diff looked like:

-import { WagmiConfig } from "wagmi";
+import { WagmiProvider } from "wagmi";

-    <WagmiConfig config={wagmiConfig}>
+    <WagmiProvider config={wagmiConfig}>
       <RainbowKitProvider
         chains={appChains.chains}
       >
         <ScaffoldEthApp>{children}</ScaffoldEthApp>
       </RainbowKitProvider>
-    </WagmiConfig>
+    </WagmiProvider>

And the wagmiConnectors file with the configureChains flag:

-export const appChains = configureChains(
-  enabledChains,
-  [
+export const appChains = /* TODO: remove configureChains, move chains to createConfig */ configureChains(enabledChains, [

Clean. Reviewable. No surprises.

Run It

npx codemod@latest @TobieTom/web3-stack-modernizer

Point it at your repo root and it handles the rest.

Why This Matters

The Web3 ecosystem moves fast. Teams stay on old library versions not because they want to — but because migrations are expensive, risky, and never urgent enough to prioritize.

Tools like this make maintenance invisible. One command, zero false positives, reviewable diff. That's the standard every migration tool should hit.

Source: github.com/TobieTom/web3-stack-modernizer