frontend-builder

前端构建器

概述

使用服务器优先架构构建易于维护、性能出色的 React 和 Next.js 前端。涵盖组件设计、状态管理、数据获取、表单、样式和性能优化。不适用于后端 API 设计、数据库架构或部署基础设施。

快速参考

模式	方法	要点
框架	Next.js App Router（默认），React + Vite（SPA）	服务器优先渲染、基于文件的路由
组件	页面、功能、UI、布局类型	单一职责、类型化属性、组合
服务器与客户端	默认使用服务器组件，在叶子节点添加 'use client'	将交互性推向组件树的边缘
状态（本地）	useState、属性、提升到父组件	尽量让状态靠近其使用位置
状态（全局）	Context API（主题、身份验证）、Zustand（复杂状态）	避免用 Context 管理频繁变化的值
数据获取	服务器组件（服务器端）、TanStack Query（客户端）	使用 Server Actions 进行变更，用 revalidatePath 更新缓存
表单	React Hook Form + Zod，或 Server Actions + useActionState	模式验证，使用 useOptimistic 实现乐观更新
样式	Tailwind CSS v4 + shadcn/ui	使用 @theme 的 CSS 优先配置、OKLCH 颜色
性能	Suspense 流式传输、代码拆分、记忆化	React.lazy()、next/dynamic、有选择地使用 memo()
错误处理	错误边界、每个路由对应一个 error.tsx	包裹功能区块，而非单个组件

常见错误

错误	正确做法
为每个组件添加 'use client'	默认使用服务器组件；仅在需要交互性时添加 'use client'
创建一个职责过多的庞大组件	拆分为职责明确、各有单一用途的子组件
将所有状态都放在组件树顶层	尽可能让状态靠近其使用位置
使用 useEffect 计算派生数据	使用 useMemo 处理派生值；useEffect 仅用于副作用
功能区块周围缺少错误边界	用错误边界包裹功能区域，避免整个页面崩溃
为简单变更创建 API 路由	使用 Server Actions 和 'use server' 处理表单提交和变更
向客户端组件传递不可序列化的属性	跨越服务器/客户端边界的属性必须可序列化（不能包含函数、类）
在 Tailwind v4 中使用 tailwind.config.js	在 CSS 文件中使用 @theme 指令进行 CSS 优先配置
明明服务器组件足以满足需求，却在客户端组件中获取数据	默认在服务器组件中获取数据；仅在需要客户端缓存时使用 TanStack Query

委派

构建前端时，请委派给专门技能：

• react-patterns —— React hooks、渲染模式和性能优化
• nextjs —— Next.js 路由、中间件和部署配置
• tanstack-query —— 客户端数据获取、缓存和变更
• tanstack-form —— 复杂表单处理和字段级验证
• tailwind —— Tailwind CSS 实用工具模式和响应式设计
• design-system —— 设计令牌层级和组件架构
• performance-optimizer —— 性能分析、打包分析和 Core Web Vitals

参考资料

• 组件架构 —— 组件类型、文件夹结构、TypeScript 模式和组合
• 服务端组件 —— 服务端/客户端边界、Server Actions、Suspense 流式传输和数据流
• 状态管理 —— useState、Context API、Zustand 和 URL 状态模式
• 数据获取 —— TanStack Query、服务端组件数据和缓存重新验证
• 表单与验证 —— React Hook Form、Zod schemas、Server Actions 和 useActionState
• 样式 —— Tailwind CSS v4、shadcn/ui、CSS 优先配置和响应式模式
• 性能与错误 —— 记忆化、代码拆分、Suspense 流式传输和错误边界