migrating-an-onchainkit-app

# OnchainKit Migration Skill

Migrate apps from `@coinbase/onchainkit` to standalone `wagmi`/`viem` components with zero OnchainKit dependency.

## Before Starting

Create a `mistakes.md` file in the project root:

```markdown
# Migration Mistakes & Learnings

Track errors, fixes, and lessons learned during OnchainKit migration.

## Errors

## Lessons Learned
```

Append every error, fix, and lesson to this file throughout the migration. This file improves the skill over time.

## Migration Workflow

Migrations MUST happen in this order. Do not skip steps.

### Step 1: Detection

Scan the project to understand current OnchainKit usage:

1. Search all files for `@coinbase/onchainkit` imports
2. Identify which components are used:
   - **Provider**: `OnchainKitProvider` (always present if using OnchainKit)
   - **Wallet**: `Wallet`, `ConnectWallet`, `WalletDropdown`, `WalletModal`, `Connected`
   - **Transaction**: `Transaction`, `TransactionButton`, `TransactionStatus`
   - **Other**: `Identity`, `Avatar`, `Name`, `Address`, `Swap`, `Checkout`, etc.
3. Check `package.json` for existing `wagmi`, `viem`, `@tanstack/react-query` dependencies
4. Identify the project's styling approach (Tailwind, CSS Modules, styled-components, etc.)
5. Report findings to the user before proceeding

### Step 2: Provider Migration (always first)

Read [references/provider-migration.md](references/provider-migration.md) for detailed instructions and code.

Summary:
1. Ensure `wagmi`, `viem`, and `@tanstack/react-query` are installed
2. Create `wagmi-config.ts` with chain and connector configuration
3. Replace `OnchainKitProvider` with `WagmiProvider` + `QueryClientProvider`
4. Remove `@coinbase/onchainkit/styles.css` import
5. Remove any `SafeArea` or MiniKit imports from layout files

**Validation gate**: Run `npm run build` (or the project's build command). Must pass before continuing. If it fails, fix errors and document them in `mistakes.md`.

### Step 3: Wallet Migration (after provider)

Read [references/wallet-migration.md](references/wallet-migration.md) for detailed instructions and code.

Summary:
1. Create a `WalletConnect` component using wagmi hooks (`useAccount`, `useConnect`, `useDisconnect`)
2. Component includes a modal with wallet options: Base Account, Coinbase Wallet, MetaMask
3. Shows truncated address + disconnect button when connected
4. Replace all OnchainKit wallet imports and component usage

**Validation gate**: Run `npm run build`. Must pass before continuing. Document any errors in `mistakes.md`.

### Step 4: Transaction Migration (after wallet)

Read [references/transaction-migration.md](references/transaction-migration.md) for detailed instructions and code.

Summary:
1. Check the `chainId` prop on existing `<Transaction />` components -- add any missing chains to `wagmi-config.ts`
2. Create a `TransactionForm` component using wagmi hooks (`useWriteContract`, `useWaitForTransactionReceipt`, `useSwitchChain`)
3. Component handles the full lifecycle: idle, pending wallet confirmation, confirming on-chain, success, error
4. Replace all OnchainKit transaction imports (`Transaction`, `TransactionButton`, `TransactionStatus`, `TransactionSponsor`, etc.)
5. Update the `calls` array format -- use `address`, `abi`, `functionName`, `args` with proper `as const` typing
6. Map `onStatus` callback to the new lifecycle status names (init, pending, confirmed, success, error)

**Validation gate**: Run `npm run build`. Must pass before continuing. Document any errors in `mistakes.md`.

### Step 5: Cleanup

1. Search for any remaining `@coinbase/onchainkit` imports -- there should be none
2. Optionally remove `@coinbase/onchainkit` from `package.json` dependencies
3. Run final `npm run build` to verify everything works
4. Update `mistakes.md` with final lessons learned

## Troubleshooting

### Build fails after provider migration
- **Missing dependencies**: Ensure `wagmi`, `viem`, `@tanstack/react-query` are installed
- **Type errors with wagmi config**: Check that `chains` array has at least one chain and `transports` has a matching entry
- **"use client" missing**: Both the provider and wallet components must have `"use client"` directive

### MetaMask SDK react-native warning
- The warning `Can't resolve '@react-native-async-storage/async-storage'` is harmless in web builds. It comes from MetaMask SDK and does not affect functionality.

### Wallet won't connect
- Verify the wagmi config has the correct connectors configured
- Check that `WagmiProvider` wraps the component tree before any wallet hooks are used
- Ensure `QueryClientProvider` is inside `WagmiProvider`

### Transaction receipt stuck in pending
- **Symptom**: Transaction hash appears, tx confirms on-chain, but UI stays stuck on "Transaction in progress..." forever
- **Cause**: `useWaitForTransactionReceipt` has no RPC to poll because the transaction's chain is missing from the wagmi config's `chains` + `transports`
- **Fix**: (1) Add the target chain to `wagmi-config.ts` chains array AND transports object. (2) Always pass `chainId` to `useWaitForTransactionReceipt({ hash, chainId })` so it polls the correct chain

### Transaction targets wrong chain
- The `TransactionForm` auto-switches chains, but the target chain must exist in the wagmi config's `chains` array and `transports` object
- Common: add `baseSepolia` for testnet transactions (chainId 84532)

### Next.js page export restrictions
- Next.js only allows specific named exports from page files. Exporting contract call arrays or ABI constants from a page file will cause a build error
- Fix: make them non-exported `const` declarations or move them to a separate module

### ABI type errors after transaction migration
- When defining ABIs inline, use `as const` on the array for proper type inference
- Mark individual fields like `type: 'function' as const` and `stateMutability: 'nonpayable' as const`

### Existing wagmi setup detected
- If the project already wraps with `WagmiProvider`, do NOT add another one
- Instead, just update the existing wagmi config to include the needed connectors
- OnchainKit's provider detects and defers to existing wagmi providers -- the standalone setup should too

## Important Notes

- Always use `wagmi` and `viem` directly. Never import from `@coinbase/onchainkit`.
- The `baseAccount` connector comes from `wagmi/connectors`, not from a separate package.
- `wagmi-config.ts` must include every chain the app transacts on. If the original OnchainKit `<Transaction chainId={X} />` used a specific chain, that chain must be in both `chains` and `transports`. Without it, `useWaitForTransactionReceipt` will hang forever.
- If the project uses Tailwind, use Tailwind classes for the components. If not, adapt to inline styles or the project's existing styling approach (e.g., CSS Modules).
- Do not export contract call arrays, ABI constants, or other non-page values from Next.js page files. Use non-exported constants or a separate module.
- Inspect the OnchainKit source code in `node_modules/@coinbase/onchainkit/src/` if you need to understand how a specific component works internally.