migrating-an-onchainkit-app

OnchainKit 移行スキル

@coinbase/onchainkit を使用するアプリを、OnchainKit に依存しない単独の wagmi／viem コンポーネントに移行します。

開始前

プロジェクトのルートに mistakes.md ファイルを作成します。

# Migration Mistakes & Learnings

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

## Errors

## Lessons Learned

移行中に発生したエラー、修正内容、教訓をすべてこのファイルに追記してください。このファイルを通じてスキルを継続的に改善できます。

移行ワークフロー

移行は必ず次の順序で行ってください。手順を省略しないでください。

ステップ 1：検出

プロジェクトをスキャンして、現在の OnchainKit の使用状況を把握します。

1. すべてのファイルを検索し、@coinbase/onchainkit のインポートを探します
2. 使用されているコンポーネントを特定します。
   • プロバイダー：OnchainKitProvider（OnchainKit を使用している場合は必ず存在します）
   • ウォレット：Wallet、ConnectWallet、WalletDropdown、WalletModal、Connected
   • トランザクション：Transaction、TransactionButton、TransactionStatus
   • その他：Identity、Avatar、Name、Address、Swap、Checkout など
3. package.json を確認し、wagmi、viem、@tanstack/react-query の依存関係がすでにあるか調べます
4. プロジェクトのスタイリング方法（Tailwind、CSS Modules、styled-components など）を特定します
5. 作業を続ける前に、調査結果をユーザーに報告します

ステップ 2：プロバイダーの移行（必ず最初に実施）

詳細な手順とコードについては、references/provider-migration.md を参照してください。

概要：

1. wagmi、viem、@tanstack/react-query がインストールされていることを確認します
2. チェーンとコネクターの設定を含む wagmi-config.ts を作成します
3. OnchainKitProvider を WagmiProvider + QueryClientProvider に置き換えます
4. @coinbase/onchainkit/styles.css のインポートを削除します
5. レイアウトファイルから SafeArea や MiniKit のインポートを削除します

検証ゲート：npm run build（またはプロジェクトのビルドコマンド）を実行します。続行する前に、必ず成功させてください。失敗した場合はエラーを修正し、mistakes.md に記録します。

ステップ 3：ウォレットの移行（プロバイダーの後に実施）

詳細な手順とコードについては、references/wallet-migration.md を参照してください。

概要：

1. wagmi フック（useAccount、useConnect、useDisconnect）を使用して WalletConnect コンポーネントを作成します
2. コンポーネントに、Base Account、Coinbase Wallet、MetaMask のウォレット選択肢を含むモーダルを追加します
3. 接続時には、短縮したアドレスと切断ボタンを表示します
4. OnchainKit のウォレット関連インポートとコンポーネントの使用箇所をすべて置き換えます

検証ゲート：npm run build を実行します。続行する前に、必ず成功させてください。エラーがあれば mistakes.md に記録します。

ステップ 4：トランザクションの移行（ウォレットの後に実施）

詳細な手順とコードについては、references/transaction-migration.md を参照してください。

概要：

1. 既存の <Transaction /> コンポーネントの chainId prop を確認し、不足しているチェーンがあれば wagmi-config.ts に追加します
2. wagmi フック（useWriteContract、useWaitForTransactionReceipt、useSwitchChain）を使用して TransactionForm コンポーネントを作成します
3. コンポーネントで、アイドル状態、ウォレット確認待ち、オンチェーン確認中、成功、エラーというライフサイクル全体を処理します
4. OnchainKit のトランザクション関連インポート（Transaction、TransactionButton、TransactionStatus、TransactionSponsor など）をすべて置き換えます
5. calls 配列の形式を更新します。適切な as const 型指定を用いて、address、abi、functionName、args を使用します
6. onStatus コールバックを新しいライフサイクルのステータス名（init、pending、confirmed、success、error）に対応付けます

検証ゲート：npm run build を実行します。続行する前に、必ず成功させてください。エラーがあれば mistakes.md に記録します。

ステップ 5：クリーンアップ

1. 残っている @coinbase/onchainkit のインポートがないか検索します。残っていてはいけません
2. 必要に応じて、package.json の依存関係から @coinbase/onchainkit を削除します
3. 最終確認として npm run build を実行し、すべてが正常に動作することを確認します
4. 学んだ教訓を mistakes.md に追記します

トラブルシューティング

プロバイダーの移行後にビルドが失敗する

• 依存関係が不足している：wagmi、viem、@tanstack/react-queryがインストールされていることを確認してください
• wagmi 設定の型エラー：chains配列に少なくとも1つのチェーンがあり、transportsに対応するエントリがあることを確認してください
• 「use client」がない：プロバイダーとウォレットの両方のコンポーネントに"use client"ディレクティブが必要です

MetaMask SDK の react-native 警告

• Can't resolve '@react-native-async-storage/async-storage'という警告は、Web ビルドでは無害です。MetaMask SDK に起因するもので、機能には影響しません。

ウォレットに接続できない

• wagmi 設定で正しいコネクターが設定されていることを確認してください
• ウォレットフックを使用する前に、WagmiProviderがコンポーネントツリーをラップしていることを確認してください
• QueryClientProviderがWagmiProviderの内側にあることを確認してください

トランザクションのレシートが保留中のままになる

• 症状：トランザクションハッシュが表示され、トランザクションはオンチェーンで確定しているのに、UI が「Transaction in progress...」のままいつまでも変わらない
• 原因：トランザクションのチェーンが wagmi 設定のchainsとtransportsにないため、useWaitForTransactionReceiptにポーリング用の RPC がありません
• 修正方法：(1) 対象のチェーンをwagmi-config.tsのchains配列とtransportsオブジェクトの両方に追加します。(2) 正しいチェーンをポーリングするよう、useWaitForTransactionReceipt({ hash, chainId })に必ずchainIdを渡します

トランザクションが誤ったチェーンを対象にする

• TransactionFormはチェーンを自動で切り替えますが、対象のチェーンが wagmi 設定のchains配列とtransportsオブジェクトに存在する必要があります
• よくある例：テストネットのトランザクションにはbaseSepolia（chainId 84532）を追加します

Next.js のページエクスポートに関する制限

• Next.js では、ページファイルから特定の名前付きエクスポートのみが許可されています。ページファイルからコントラクト呼び出し配列や ABI 定数をエクスポートすると、ビルドエラーが発生します
• 修正方法：エクスポートしないconst宣言にするか、別のモジュールに移動します

トランザクション移行後の ABI 型エラー

• ABI をインラインで定義する場合、適切な型推論のため、配列にas constを使用します
• type: 'function' as constやstateMutability: 'nonpayable' as constのように、個々のフィールドにも指定します

既存の wagmi セットアップが検出された

• プロジェクトがすでにWagmiProviderでラップされている場合、別のプロバイダーを追加しないでください
• 代わりに、既存の wagmi 設定を更新して、必要なコネクターを追加します
• OnchainKit のプロバイダーは既存の wagmi プロバイダーを検出してそちらに処理を委ねます。単独のセットアップでも同様にしてください

重要な注意事項

• 常にwagmiとviemを直接使用してください。@coinbase/onchainkitからインポートしないでください。
• baseAccountコネクターはwagmi/connectorsから提供されます。別のパッケージからではありません。
• wagmi-config.tsには、アプリがトランザクションを実行するすべてのチェーンを含める必要があります。元の OnchainKit の<Transaction chainId={X} />が特定のチェーンを使用していた場合、そのチェーンをchainsとtransportsの両方に含める必要があります。含めないと、useWaitForTransactionReceiptがいつまでも完了しません。
• プロジェクトで Tailwind を使用している場合は、コンポーネントに Tailwind クラスを使用してください。使用していない場合は、インラインスタイルや既存のスタイリング方法（例：CSS Modules）に合わせてください。
• Next.js のページファイルから、コントラクト呼び出し配列、ABI 定数、その他ページ以外の値をエクスポートしないでください。エクスポートしない定数を使用するか、別のモジュールに移動してください。
• 特定のコンポーネントの内部動作を理解する必要がある場合は、node_modules/@coinbase/onchainkit/src/にある OnchainKit のソースコードを確認してください。