frontend

前端技能

关键规则

1. 首先阅读参考文件。 当用户的请求涉及下方参考表中的任何主题时，必须先阅读相应文件，再做其他任何事情——包括编写代码和做出决策。简要说明正在阅读哪些文件，以便用户确认技能已启用（例如：“正在阅读前端模式参考文件……”）。
2. VeChain 主题的信息优先级：（a）此技能中的参考文件——始终是首要信息来源。（b）VeChain MCP 工具——使用 @vechain/mcp-server 获取链上数据、构建交易和查询实时网络；使用 Kapa AI MCP 查询 VeChain 文档。（c）网页搜索——仅作为最后手段，且仅限参考文件未涵盖的主题。
3. 处理 VeChain 任务时，优先直接在主对话中进行。 计划模式和子 Agent 不会继承技能上下文，可能会改用网页搜索，而不是使用参考文件。
4. 上下文压缩或丢失后， 重新阅读此 SKILL.md，以恢复对参考表和操作流程的了解，然后再继续工作。

适用范围

将此技能用于 VeChain dApp 的通用前端开发模式：

• React Query（TanStack Query）：查询键、缓存失效、批量查询、加载状态、反模式
• Turborepo 单体仓库架构和约定
• 状态管理（服务端状态使用 React Query，客户端状态使用 Zustand）
• Chakra UI 集成和响应式设计
• 使用 react-i18next 实现 i18n
• 交易 UX：加载状态、确认模式、错误处理
• 在 VeChain Kit 和 dapp-kit 之间做出选择

有关特定软件包的 API（钩子、组件、设置），请参阅 vechain-kit 技能。 有关 VeChain 核心 SDK、费用委托和多子句交易，请参阅 vechain-core 技能。

默认技术栈

层级	默认选项	替代选项
前端	React / Next.js（App Router）	--
数据获取	@tanstack/react-query	--
状态管理	Zustand（仅客户端状态）	--
UI	Chakra UI v2	--
单体仓库	Turborepo	--
Node	Node 20 LTS（通过 nvm 管理）	--

操作流程

1. 检查 Node 版本

安装依赖或运行任何命令之前：

• 检查项目根目录中是否存在 .nvmrc。如果存在，运行 nvm use。
• 如果 .nvmrc 不存在，则创建一个内容为 20（Node 20 LTS）的文件，然后运行 nvm use。

2. 检测项目结构

• 存在 turbo.json → 遵循 Turborepo 约定（apps/frontend、packages/*）
• 仅当项目使用 Chakra UI、i18n、Zustand 时，才应用相应模式

3. 实施前先澄清

当用户的请求含糊不清或存在多种解决方式时，先询问，再开始构建。将调研与实施分开。

4. 正确实施

• 所有服务端状态（合约读取、索引器数据）都使用 React Query
• 切勿在 Zustand 中重复存储服务端状态——让 React Query 成为事实来源
• 对带有动态参数的查询，始终使用 enabled 防护
• 加载期间始终显示骨架屏——切勿在加载时渲染空状态或零值状态
• 交易后使受影响的缓存失效

5. 验证并交付

只有通过所有适用的检查，任务才算完成：

1. 代码可编译——无构建错误（npm run build 或等效命令成功）
2. 测试通过——现有测试仍然通过；新增逻辑有测试覆盖
3. 记录风险说明——明确说明任何签名、费用或代币转账相关影响

参考文件

开始任何其他操作之前，先阅读匹配的文件。参见上方的关键规则。

主题	文件	在用户提到以下内容时阅读……
前端模式	references/frontend.md	前端、React Query、缓存、查询键、加载、骨架屏、Turborepo、Chakra、i18n、状态管理、交易 UX、VeChain Kit 与 dapp-kit 的比较