migrating-an-onchainkit-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OnchainKit Migration Skill

OnchainKit 迁移技能

Migrate apps from

@coinbase/onchainkit

to standalone

wagmi

viem

components with zero OnchainKit dependency.

将应用从

@coinbase/onchainkit

迁移到独立的

wagmi

viem

组件，完全移除OnchainKit依赖。

Before Starting

开始之前

Create a

mistakes.md

file in the project root:

markdown

undefined

在项目根目录创建

mistakes.md

文件：

markdown

undefined

Migration Mistakes & Learnings

迁移错误与经验总结

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

记录OnchainKit迁移过程中遇到的错误、修复方案和经验教训。

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

步骤1：检测

Scan the project to understand current OnchainKit usage:

Search all files for
```
@coinbase/onchainkit
```
imports

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.

Check

package.json

for existing

wagmi

viem

@tanstack/react-query

dependencies

Identify the project's styling approach (Tailwind, CSS Modules, styled-components, etc.)
Report findings to the user before proceeding

扫描项目以了解当前OnchainKit的使用情况：

搜索所有文件中的
```
@coinbase/onchainkit
```
导入语句

识别使用的组件类型：

提供者：
```
OnchainKitProvider
```
（如果使用OnchainKit则必定存在）

钱包：

Wallet

、

ConnectWallet

、

WalletDropdown

、

WalletModal

、

Connected

交易：

Transaction

、

TransactionButton

、

TransactionStatus

其他：
```
Identity
```
、
```
Avatar
```
、
```
Name
```
、
```
Address
```
、
```
Swap
```
、
```
Checkout
```
等

检查

package.json

中是否已存在

wagmi

、

viem

、

@tanstack/react-query

依赖

识别项目的样式方案（Tailwind、CSS Modules、styled-components等）
在继续之前向用户报告检测结果

Step 2: Provider Migration (always first)

步骤2：提供者迁移（必须首先执行）

Read references/provider-migration.md for detailed instructions and code.

Summary:

Ensure
```
wagmi
```
,
```
viem
```
, and
```
@tanstack/react-query
```
are installed
Create
```
wagmi-config.ts
```
with chain and connector configuration

Replace

OnchainKitProvider

with

WagmiProvider

QueryClientProvider

Remove
```
@coinbase/onchainkit/styles.css
```
import
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

阅读references/provider-migration.md获取详细说明和代码示例。

总结：

确保已安装
```
wagmi
```
、
```
viem
```
和
```
@tanstack/react-query
```
创建
```
wagmi-config.ts
```
文件，配置链和连接器

将

OnchainKitProvider

替换为

WagmiProvider

QueryClientProvider

移除
```
@coinbase/onchainkit/styles.css
```
导入语句
从布局文件中移除所有
```
SafeArea
```
或MiniKit导入

验证关卡：运行

npm run build

（或项目对应的构建命令）。必须通过验证才能继续。如果构建失败，修复错误并将其记录到

mistakes.md

中。

Step 3: Wallet Migration (after provider)

步骤3：钱包迁移（在提供者迁移之后执行）

Read references/wallet-migration.md for detailed instructions and code.

Summary:

Create a

WalletConnect

component using wagmi hooks (

useAccount

useConnect

useDisconnect

)

Component includes a modal with wallet options: Base Account, Coinbase Wallet, MetaMask
Shows truncated address + disconnect button when connected
Replace all OnchainKit wallet imports and component usage

Validation gate: Run

npm run build

. Must pass before continuing. Document any errors in

mistakes.md

阅读references/wallet-migration.md获取详细说明和代码示例。

总结：

使用wagmi钩子（

useAccount

、

useConnect

、

useDisconnect

）创建

WalletConnect

组件

组件包含带有钱包选项的模态框：Base Account、Coinbase Wallet、MetaMask
连接成功后显示截断的地址和断开连接按钮
替换所有OnchainKit钱包导入语句和组件用法

验证关卡：运行

npm run build

。必须通过验证才能继续。将任何错误记录到

mistakes.md

中。

Step 4: Transaction Migration (after wallet)

步骤4：交易迁移（在钱包迁移之后执行）

Read references/transaction-migration.md for detailed instructions and code.

Summary:

Check the
```
chainId
```
prop on existing
```
<Transaction />
```
components -- add any missing chains to
```
wagmi-config.ts
```

Create a

TransactionForm

component using wagmi hooks (

useWriteContract

useWaitForTransactionReceipt

useSwitchChain

)

Component handles the full lifecycle: idle, pending wallet confirmation, confirming on-chain, success, error

Replace all OnchainKit transaction imports (

Transaction

TransactionButton

TransactionStatus

TransactionSponsor

, etc.)

Update the
```
calls
```
array format -- use
```
address
```
,
```
abi
```
,
```
functionName
```
,
```
args
```
with proper
```
as const
```
typing
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

阅读references/transaction-migration.md获取详细说明和代码示例。

总结：

检查现有
```
<Transaction />
```
组件上的
```
chainId
```
属性——将所有缺失的链添加到
```
wagmi-config.ts
```
中

使用wagmi钩子（

useWriteContract

、

useWaitForTransactionReceipt

、

useSwitchChain

）创建

TransactionForm

组件

组件处理完整生命周期：空闲、等待钱包确认、链上确认、成功、错误

替换所有OnchainKit交易导入语句（

Transaction

、

TransactionButton

、

TransactionStatus

、

TransactionSponsor

等）

更新
```
calls
```
数组格式——使用
```
address
```
、
```
abi
```
、
```
functionName
```
、
```
args
```
并添加正确的
```
as const
```
类型声明
将
```
onStatus
```
回调映射到新的生命周期状态名称（init、pending、confirmed、success、error）

验证关卡：运行

npm run build

。必须通过验证才能继续。将任何错误记录到

mistakes.md

中。

Step 5: Cleanup

步骤5：清理

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

搜索所有剩余的
```
@coinbase/onchainkit
```
导入语句——确保没有遗漏
（可选）从
```
package.json
```
依赖中移除
```
@coinbase/onchainkit
```
运行最终的
```
npm run build
```
以验证所有功能正常
将最终的经验教训更新到
```
mistakes.md
```
中

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

缺失依赖：确保已安装
```
wagmi
```
、
```
viem
```
、
```
@tanstack/react-query
```
wagmi配置类型错误：检查
```
chains
```
数组至少包含一条链，且
```
transports
```
有对应的条目
缺少"use client"指令：提供者和钱包组件都必须添加
```
"use client"
```
指令

MetaMask SDK react-native warning

MetaMask SDK react-native警告

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.

警告
```
Can't resolve '@react-native-async-storage/async-storage'
```
在Web构建中是无害的。它来自MetaMask SDK，不影响功能。

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
```

验证wagmi配置是否配置了正确的连接器
检查
```
WagmiProvider
```
是否在任何钱包钩子使用之前包裹了组件树
确保
```
QueryClientProvider
```
位于
```
WagmiProvider
```
内部

Transaction receipt stuck in pending

交易收据一直处于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

症状：交易哈希已显示，交易在链上已确认，但UI一直停留在“交易处理中...”
原因：
```
useWaitForTransactionReceipt
```
没有可轮询的RPC，因为交易所在的链未添加到wagmi配置的
```
chains
```
+
```
transports
```
中
修复方案：(1) 将目标链添加到
```
wagmi-config.ts
```
的chains数组和transports对象中。(2) 始终将
```
chainId
```
传递给
```
useWaitForTransactionReceipt({ hash, chainId })
```
，以便它轮询正确的链

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)

```
TransactionForm
```
会自动切换链，但目标链必须存在于wagmi配置的
```
chains
```
数组和
```
transports
```
对象中
常见情况：为测试网交易添加
```
baseSepolia
```
（chainId 84532）

Next.js page export restrictions

Next.js页面导出限制

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

Next.js仅允许页面文件导出特定的命名导出。从页面文件导出合约调用数组或ABI常量会导致构建错误
修复方案：将它们改为非导出的
```
const
```
声明，或者移至单独的模块中

ABI type errors after transaction migration

交易迁移后ABI类型错误

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

内联定义ABI时，对数组使用
```
as const
```
以获得正确的类型推断

标记单个字段，如

type: 'function' as const

和

stateMutability: 'nonpayable' as const

Existing wagmi setup detected

检测到现有wagmi配置

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

如果项目已使用
```
WagmiProvider
```
包裹，请勿添加另一个
相反，只需更新现有的wagmi配置以包含所需的连接器
OnchainKit的提供者会检测并适配现有的wagmi提供者——独立设置也应如此

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.

始终直接使用
```
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源代码。