create-vechain-dapp

创建 VeChain dApp

搭建一个可用于生产环境的 VeChain dApp，支持钱包连接、深色模式和 GitHub Pages 部署。

关键规则

1. 先阅读参考文件。 根据用户选择的模式，在创建任何文件之前阅读相应的参考文件。简要说明正在阅读哪些文件，以便用户确认技能已启用。
2. 始终阅读 shared.md——其中包含两种模式共用的源代码模板。
3. 写入文件前，替换每个模板中的所有占位符。 请参阅下方的变量替换部分。
4. 压缩或上下文丢失后，重新阅读此 SKILL.md，以恢复对参考文件表和操作流程的了解。

技术栈

层级	技术
框架	Next.js 14（App Router，静态导出）
UI	Chakra UI v3、next-themes
钱包	@vechain/vechain-kit（VeWorld + WalletConnect）
状态	React Query
合约	Hardhat + @vechain/sdk-hardhat-plugin + OpenZeppelin UUPS（仅限 monorepo）
构建	Turborepo（仅限 monorepo）
部署	通过 GitHub Actions 部署到 GitHub Pages
Node	20 LTS

操作流程

阶段 1 — 收集需求

向用户提问（如支持，可使用结构化问题）：

1. 项目名称 — kebab-case（例如 my-vechain-dapp）
2. 模式 — standalone（仅前端）或 monorepo（Turbo + 合约）
3. 网络 — test 或 main（默认值：test）
4. 目标目录 — 创建项目的位置（默认值：当前目录）

阶段 2 — 搭建项目

阅读相应的参考文件并创建所有文件。

Standalone 模式：

1. 阅读 references/shared.md
2. 阅读 references/standalone.md
3. 在 {{TARGET_DIR}}/{{PROJECT_NAME}}/ 中创建文件

Monorepo 模式：

1. 阅读 references/shared.md
2. 阅读 references/monorepo.md
3. 在 {{TARGET_DIR}}/{{PROJECT_NAME}}/apps/frontend/ 中创建前端文件
4. 在 monorepo 根目录和 packages/ 中创建其他文件

变量替换

替换所有模板中的以下占位符：

占位符	值
{{PROJECT_NAME}}	kebab-case 项目名称
{{PROJECT_TITLE}}	标题式项目名称（用于 UI 显示）
{{NETWORK_TYPE}}	test 或 main

阶段 3 — 安装并验证

cd {{PROJECT_NAME}}
nvm use
yarn install

Standalone： yarn dev（localhost:3000）、yarn build（静态导出 → out/）

Monorepo： make solo-up（启动 Thor solo 节点，需要 Docker），然后运行 yarn dev（自动将合约部署到 solo）、yarn build、yarn contracts:compile、yarn contracts:test。使用 make solo-down 停止，使用 make solo-clean 重置。

阶段 4 — 初始化 Git

git init && git add . && git commit -m "Initial scaffold: VeChain dApp"

成功标准

• yarn dev 无错误启动
• 页面显示 Navbar 和钱包连接按钮
• 深色/浅色模式切换正常
• yarn build 生成静态输出
• 存在 .github/workflows/deploy.yml

关键模式

仅客户端运行的 VeChain Kit

VeChain Kit 无法在服务端运行。整个应用外壳（ClientApp）通过 layout.tsx 中的 dynamic(() => ..., { ssr: false }) 加载。由于父级已限定为仅客户端，ClientApp 子组件中的所有 VeChain Kit 导入均可正常使用。

用于 GitHub Pages 的静态导出

next.config.js 使用 output: "export"，并通过 NEXT_PUBLIC_BASE_PATH 环境变量配置 basePath/assetPrefix。GitHub Pages 的 GitHub Actions 默认使用 /${{ github.event.repository.name }}。自定义域名请设为空字符串。重要：metadata.icons 和原始 <img src> 路径不会自动添加 basePath——请手动添加前缀。

Chakra UI 版本固定

将 @chakra-ui/react 固定为精确版本（当前为 3.30.0）。VeChain Kit 内部使用 Chakra v2，更新的 v3 版本可能会导致 VeChain Kit 的按钮/模态框主题出现问题。

Provider 链

ChakraProvider → ColorModeProvider → QueryClientProvider → VeChainKitProvider → App

合约架构（仅限 monorepo）

monorepo 脚手架中的所有合约都使用 OpenZeppelin 的可升级合约和自定义的 VeChainProxy.sol（ERC1967）实现 UUPS 可升级。关键文件：

• scripts/helpers/upgrades.ts — 核心代理部署/升级辅助工具。请原样从模板复制。所有部署脚本、升级脚本和测试都依赖它。
• contracts/VeChainProxy.sol — ERC1967 代理合约。请原样复制。
• scripts/deploy/deploy.ts — 使用辅助工具中的 deployProxy 进行生产环境部署。
• scripts/upgrade/ — 带版本化配置注册表的交互式 CLI 升级系统。

关于合约架构、升级模式、存储安全、安全性和测试，请遵循 smart-contract-development 技能。它是 VeChain 上所有 Solidity 开发模式的权威参考。

配置包和自动部署（仅限 monorepo）

monorepo 使用 packages/config 包，集中管理各环境的合约地址和网络设置。主要机制：

• local.ts 被 git 忽略 — 每位开发者的独立部署都会生成不同地址。首次运行时会自动生成模拟配置。
• NEXT_PUBLIC_APP_ENV 控制加载哪个配置文件（local、testnet、mainnet）。
• yarn dev 连接 solo 运行，yarn dev:testnet 连接 testnet 运行，yarn dev:mainnet 连接 mainnet 运行。
• Turbo 流水线会依次：生成模拟配置 → 编译合约 → 在目标网络上检查/部署 → 将地址写入对应配置文件 → 启动前端。
• 在任何环境中，开发服务器启动前都会运行 checkContractsDeployment.ts；如果合约尚未部署，该脚本会进行部署，并将地址写入正确的配置文件（local.ts、testnet.ts 或 mainnet.ts）。

VeChain Kit 集成

• VeChainKitProvider 使用网络配置和钱包选项封装应用
• vechain-kit 中的 WalletButton 用于呈现连接/账户按钮
• 使用 useWallet、useSendTransaction、useCallClause 进行钱包/合约交互
• 进阶模式（钩子、主题设置、社交登录）请参阅 vechain-kit 技能
• SDK 模式（费用代付、多子句）请参阅 vechain-core 技能

参考文件

创建任何文件之前，请先阅读对应文件。请参阅上方的关键规则。

主题	文件	阅读时机……
共享源代码	references/shared.md	始终阅读 — 包含所有组件/提供程序模板
独立配置	references/standalone.md	用户选择独立模式（仅前端）时
Monorepo 配置	references/monorepo.md	用户选择 monorepo 模式（Turbo + 合约）时