moai-domain-frontend

前端开发专家

快速参考

现代前端开发——React 19、Next.js 16 和 Vue 3.5 的全面模式。

核心能力：

• React 19：服务端组件、并发特性、cache()、Suspense
• Next.js 16：App Router、Server Actions、ISR、路由处理程序
• Vue 3.5：组合式 API、TypeScript、Pinia 状态管理
• 组件架构：设计系统、复合组件、CVA
• 性能：代码拆分、动态导入、记忆化、Framer Motion 动画

适用场景：

• 现代 Web 应用开发
• 创建组件库
• 前端性能优化
• 具备无障碍支持的 UI/UX

---

模式

框架模式

React 19 模式：

• 服务端组件、并发特性、cache() API、表单处理

Next.js 16 模式：

• App Router、Server Actions、ISR、路由处理程序、并行路由

Vue 3.5 模式：

• 组合式 API、组合函数、响应性、Pinia、Provide/Inject

架构模式

组件架构：

• 设计令牌、CVA 变体、复合组件、无障碍支持

状态管理：

• Zustand、Redux Toolkit、React Context、Pinia

性能优化：

• 代码拆分、动态导入、图像优化、记忆化

AI 辅助前端模式：

• 视觉参考策略、Playwright 验证、动效设计、推理级别调优

Vercel React 最佳实践：

• Vercel Engineering 提供的 8 类共 45 条规则
• 消除瀑布请求、优化打包体积、提升服务端性能
• 客户端数据获取、优化重新渲染、提升渲染性能

---

实施快速入门

React 19 服务端组件

创建一个异步页面组件，使用 React 的 cache 函数对数据获取进行记忆化。导入 Suspense 以处理加载状态。定义一个 getData 函数，使用 id 参数从 API 端点获取数据并返回 JSON。在页面组件中，使用 Skeleton 作为后备内容，通过 Suspense 包裹 DataDisplay 组件，并将 await getData 的结果作为 data 属性传入。

Next.js Server Action

创建一个服务端操作文件，并添加 use server 指令。导入 next/cache 中的 revalidatePath，以及用于验证的 zod 中的 z。定义一个 schema，其中 title 至少包含 1 个字符，content 至少包含 10 个字符。createPost 函数接收 FormData，使用 safeParse 进行验证；验证失败时返回错误，验证通过后在数据库中创建帖子，并对帖子页面调用 revalidatePath。

Vue 组合函数

创建一个接收 userId ref 参数的 useUser 组合函数。将 user 定义为可空的 ref，将 loading 定义为布尔型 ref，并将 fullName 定义为 computed 属性，用于拼接 firstName 和 lastName。使用 watchEffect 将 loading 设为 true，异步获取用户数据，将数据赋给 user ref，然后将 loading 设为 false。返回 user、loading 和 fullName refs。

CVA 组件

从 class-variance-authority 导入 cva 和 VariantProps。定义 buttonVariants，其基础类包括 inline-flex、items-center、justify-center、rounded-md 和 font-medium。添加 variants 对象，其中 variant 选项包括 default（带悬停效果的主色背景）和 outline（带悬停强调色的边框）。添加 size 选项：sm（h-9、px-3、text-sm）、default（h-10、px-4）和 lg（h-11、px-8）。为 variant 和 size 设置 defaultVariants。导出一个 Button 组件，将 variants 应用到按钮元素的 className。

---

配合使用效果良好

• moai-domain-backend - 全栈开发
• moai-ref-ui-polish - 组件库集成
• moai-ref-ui-polish - UI/UX 设计原则
• .claude/rules/moai/languages/typescript.md - TypeScript 模式（通过 paths frontmatter 自动加载）
• moai-workflow-testing - 前端测试

---

技术栈

框架：React 19、Next.js 16、Vue 3.5、Nuxt 3

语言：TypeScript 5.9+、JavaScript ES2024

样式：Tailwind CSS 3.4+、CSS Modules、shadcn/ui

动画：Framer Motion

状态管理：Zustand、Redux Toolkit、Pinia

测试：Vitest、Testing Library、Playwright

验证：Playwright（视觉检查、功能测试）

---

资源

官方文档：

• React：https://react.dev/
• Next.js：https://nextjs.org/docs
• Vue：https://vuejs.org/

---

版本：2.1.0

常见的自我开脱

自我开脱	事实
“无障碍功能可以在发布后添加”	发布后再补充无障碍功能，就相当于重写，而不是简单添加。语义化 HTML 和 ARIA 是基础，而非装饰。
“这个组件太简单，不需要单独测试”	简单组件会组合成复杂的 UI。一个简单组件出错，就会导致它所用之处处处出错。
“服务端组件总是更快”	服务端组件会增加网络往返。缓存得当的客户端组件，性能可能优于设计不当的服务端组件。应进行测量，而非想当然。
“我暂时就用 any 作为 TypeScript 类型”	any 会让类型检查器对所有下游代码失效。一个 any 就会影响整个调用链。
“这个项目使用全局 CSS 没问题”	随着项目发展，全局 CSS 会造成优先级冲突。作用域样式（CSS modules、Tailwind）可以避免冲突。

危险信号

• 组件未经清理便渲染用户提供的 HTML（XSS 漏洞）
• 在组件属性或状态定义中使用 TypeScript any 类型
• 异步数据获取组件未定义加载或错误状态
• 交互元素缺少无障碍属性（aria-label、role）
• 未说明原因，包体积就增加了 50KB 以上
• 组件超过 300 行，且未拆分为子组件

验证

• 所有交互元素都有无障碍名称（aria-label 或可见文本）
• 组件能处理加载、错误和空状态
• 新增或修改的代码中没有 TypeScript any（显示 grep 结果）
• 已测量新增依赖对包体积的影响（显示分析器输出）
• 用户提供的内容经过正确转义或清理后再渲染
• 组件少于 300 行，或已拆分，并明确划分子组件边界