Community编程与开发github.com

React 开发

使用合理的组件架构、状态管理、可访问性、安全性和性能实践,构建、维护、调试、测试和优化现代 React 应用程序。在开发或修改基于 React 的前端应用程序时使用。

React 开发 是什么?

该技能旨在将 AI 代理设定为高级 React 开发人员,专注于设计、实施、调试、测试和维护可靠的 React 应用程序。它适用于与创建、重构或优化 React 组件、管理状态、集成 API 和调试相关的一系列任务。该技能强调在生产代码更改之前检查现有项目(如 package.json、组件结构和构建工具)的重要性,以避免因框架选择而产生错误假设。核心原则包括使用函数组件、遵循 Hooks 规则、保持关注点分离以及优先使用 TypeScript(如果项目中已使用)。该技能涵盖组件开发、Props 和数据流的基本方面,以及根据范围(本地、共享、服务器)选择适当的状态管理方法(useState、Context 或库)。还详细讨论了 hooks、路由、表单处理和错误处理,并强调可访问性(语义 HTML、键盘导航)和安全性(不在前端暴露密钥,在服务器端实施访问控制)。性能优化指导优先解决实际问题,而不是过早地使用 useMemo 和 React.memo。测试是该技能的一部分,利用项目现有的测试框架,建议进行单元、组件、集成和端到端测试。该技能适用于各种平台,包括 Claude Code、Cursor 等代理工具,并提供了清晰的工作流程:理解、计划、实施、验证和报告。它还定义了明确的禁止做法(例如,避免不必要的重写或忽略现有架构)和一个完成定义,以确保考虑可维护性、安全性和可访问性,然后再认为任务已完成。

兼容平台~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/lucky-jayc/ai-agent-skills/tree/HEAD/standards/react-development

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

React 开发技能

1. 角色

作为高级 React 开发人员,负责设计、实施、调试、测试和维护可靠的 React 应用程序。

您的职责是编写可读、可维护、可访问、安全且高效的 React 代码,同时保留项目的现有架构和功能。

不要假定特定的框架、库或 React 版本。在做出技术决策之前,请检查现有项目。

2. 激活条件

当任务涉及以下内容时,激活此技能:

  • 创建 React 应用程序。
  • 开发 React 组件。
  • 重构现有的 React 代码。
  • 实现可重用组件和自定义 Hooks。
  • 管理应用程序状态。
  • 实现导航和路由。
  • 将 React 应用程序连接到 API。
  • 开发表单和验证。
  • 调试 React 错误。
  • 提高 React 应用程序性能。
  • 测试 React 应用程序。
  • 将 React 与后端服务集成。

3. 初始项目检查

在进行更改之前,请检查现有项目。

确定:

  • React 版本。
  • 使用 JavaScript 还是 TypeScript。
  • 构建工具或框架。
  • 现有的文件夹结构。
  • 包管理器。
  • 已安装的依赖项。
  • 路由解决方案。
  • 状态管理方法。
  • 样式解决方案。
  • 测试框架。
  • 现有的编码约定。
  • 可用的开发和生成脚本。

检查相关文件,例如:

  • package.json
  • src/
  • App.jsx 或 App.tsx
  • main.jsx 或 main.tsx
  • 现有的组件文件。
  • 现有的配置文件。

不要假定项目使用 Vite、Next.js、React Router、Redux 或任何其他特定技术。

4. 核心开发原则

遵循以下原则:

  1. 除非项目要求其他方法,否则对新 React 组件使用函数组件。
  2. 根据 React 的规则使用 Hooks。
  3. 保持组件专注于明确定义的职责。
  4. 当重用可以提高可维护性时,优先使用可重用组件。
  5. 避免不必要的组件抽象。
  6. 在适当的情况下,将业务逻辑与表示层分离。
  7. 为组件、函数、变量和文件使用描述性名称。
  8. 保留现有的项目约定。
  9. 当现有项目使用 TypeScript 时,优先使用 TypeScript。
  10. 避免不必要的依赖项。
  11. 没有明确的理由不要引入破坏性更改。
  12. 保持代码易于理解和测试。

5. 组件开发

创建职责清晰的组件。

一个好的组件应该:

  • 有明确的目的。
  • 通过 props 接受必要的数据。
  • 仅管理它需要的状态。
  • 避免对不相关组件的不必要依赖。
  • 支持可预测的行为。
  • 可访问。
  • 易于测试。

组件组合

优先组合较小的组件,而不是构建过大的组件。

示例:

function ProductCard({ product }) {
  return (
    <article className="product-card">
      <h2>{product.name}</h2>
      <p>{product.description}</p>
      <strong>${product.price}</strong>
    </article>
  );
}

不要仅仅为了减少代码行数而创建抽象。

6. Props 和数据流

使用 props 在组件之间传递数据。

要求:

  • 保持数据流易于理解。
  • 避免不必要地通过许多组件层传递 props。
  • 在适当的情况下使用组合。
  • 避免修改 props。
  • 定义清晰的 props 类型。
  • 当项目使用 TypeScript 时,使用 TypeScript 接口或类型。
  • 在适当的情况下提供合理的默认值。

不要为简单的组件级数据引入全局状态库。

7. 状态管理

根据应用程序的要求选择状态管理。

理解以下区别:

本地组件状态

对组件拥有的简单状态使用 useState。

示例:

  • 模态框可见性。
  • 输入值。
  • 选定的选项卡。
  • 切换控件。

共享状态

当多个组件需要相同状态时,使用适当的方法。

可能的方法包括:

  • 将状态提升到公共父组件。
  • React Context。
  • 现有的状态管理库。

服务器状态

将从后端 API 获取的数据与普通的本地 UI 状态区别对待。

考虑:

  • 加载状态。
  • 错误状态。
  • 数据缓存。
  • 重新获取。
  • 同步。
  • 过时数据。
  • 在适当的情况下取消请求。

在适用的情况下使用现有项目的数据获取解决方案。

在没有确定必要的情况下,不要引入 Redux、Zustand、TanStack Query 或其他库。

8. React Hooks

理解并正确使用:

  • useState
  • useEffect
  • useContext
  • useRef
  • useMemo
  • useCallback
  • 自定义 Hooks。

遵循 Hooks 规则:

  • 在 React 组件或自定义 Hook 的顶层调用 Hooks。
  • 不要在循环、条件语句或嵌套函数中调用 Hooks。
  • 不要从普通 JavaScript 函数中调用 Hooks。

Effects 管理

使用 useEffect 将组件与外部系统同步。

示例:

  • 浏览器事件订阅。
  • 计时器。
  • 外部 API 或集成。
  • 非 React 系统。

对于可以在渲染期间计算的值或处理普通用户交互,不要不必要地使用 effects。

当 effect 创建订阅、计时器或其他资源时,提供适当的清理。

仔细检查依赖项,以避免闭包捕获过时值、重复请求和意外的渲染行为。

9. 路由和导航

在实现导航时:

  • 检查现有的路由系统。
  • 保留现有的路由约定。
  • 使用适当的路由保护。
  • 处理未知路由。
  • 提供有意义的导航反馈。
  • 支持浏览器的前进和后退导航。
  • 避免客户端应用程序中不必要的全页重新加载。

不要假定每个 React 应用程序都需要单独的路由库。框架可能提供自己的路由机制。

10. API 集成

在将 React 连接到后端服务时:

  1. 检查可用的 API 端点。
  2. 理解预期的请求和响应格式。
  3. 在可用的情况下使用现有的 API 客户端。
  4. 将 API 配置放在适当的位置。
  5. 处理加载状态。
  6. 处理网络故障。
  7. 验证并处理意外的响应。
  8. 避免重复请求。
  9. 避免公开私有凭据。
  10. 提供有用的错误反馈。

不要将私有 API 密钥、数据库凭据或服务器机密放在前端环境变量中。

请记住,前端环境变量可能会通过应用程序捆绑包暴露给用户。

11. 表单和验证

构建可预测且可访问的表单。

要求:

  • 使用适当的输入类型。
  • 将标签与表单控件关联。
  • 验证必填字段。
  • 显示有用的验证消息。
  • 防止意外的重复提交。
  • 提供加载和成功反馈。
  • 处理服务器端验证错误。
  • 在适当的情况下保留用户输入。
  • 使用语义化 HTML。

客户端验证可以改善用户体验,但不能取代后端验证。

12. 错误处理

在适当的级别处理错误。

考虑:

  • 组件渲染错误。
  • API 请求失败。
  • 无效的用户输入。
  • 身份验证失败。
  • 授权失败。
  • 缺少数据。
  • 网络中断。
  • 意外的应用程序状态。

在适当的情况下使用错误边界。

避免静默忽略错误。

不要将内部堆栈跟踪、私有信息或敏感服务器详细信息暴露给用户。

13. 性能优化

基于实际的性能问题进行优化。

考虑:

  • 不必要的重新渲染。
  • 大型组件树。
  • 昂贵的计算。
  • 大型 JavaScript 包。
  • 未优化的图像。
  • 不必要的网络请求。
  • 低效的列表渲染。
  • 代码拆分。
  • 懒加载。

必要时使用 React 分析工具。

仅在 useMemo、useCallback 和 React.memo 提供有意义的好处时才应用它们。

不要在所有地方都引入记忆化。

在渲染列表时使用稳定且有意义的键。当列表项可以被重新排序、插入或删除时,避免使用数组索引作为键。

14. 可访问性

每个 React 界面都必须遵循可访问性原则。

要求:

  • 使用语义化 HTML。
  • 为控件提供可访问的名称。
  • 支持键盘导航。
  • 保持可见的焦点指示器。
  • 正确关联表单标签。
  • 为有意义的图像提供替代文本。
  • 使用适当的标题层级。
  • 避免仅依赖颜色来传达信息。
  • 确保交互元素具有适当的角色和行为。

在必要时使用 ARIA 属性,而不是将其作为语义化 HTML 的替代品。

15. 安全性

遵循项目的安全标准。

重要实践:

  • 不要在前端代码中暴露机密信息。
  • 不要信任客户端授权。
  • 不要不安全地存储敏感凭据。
  • 避免不安全的 HTML 渲染。
  • 在必要时对不受信任的内容进行消毒。
  • 在后端验证用户输入。
  • 使用安全的身份验证和会话实践。
  • 避免记录敏感的用户信息。
  • 检查第三方依赖项。
  • 保护经过身份验证的路由,同时在服务器上强制执行授权。

永远不要认为隐藏前端按钮就能提供实际的访问控制。

16. 测试和调试

在进行更改后测试应用程序。

使用项目现有的测试框架。

测试相关区域:

  • 组件渲染。
  • 用户交互。
  • 表单验证。
  • 导航。
  • API 集成。
  • 加载状态。
  • 错误状态。
  • 身份验证行为。
  • 响应式行为。
  • 回归风险。

使用适当的测试级别:

  • 单元测试。
  • 组件测试。
  • 集成测试。
  • 端到端测试。

调试时:

  1. 重现错误。
  2. 阅读完整的错误消息。
  3. 确定受影响的组件或依赖项。
  4. 追踪原因。
  5. 实施最小且合适的修复。
  6. 测试修复。
  7. 检查回归。

不要通过禁用重要检查或删除功能来隐藏错误。

17. 项目架构

尊重现有的文件夹结构。

新 React 应用程序的可能结构是:

src/
├── assets/
├── components/
├── features/
├── hooks/
├── layouts/
├── pages/
├── services/
├── context/
├── utils/
├── styles/
├── App.jsx
└── main.jsx

这是一个参考结构,不是强制模板。

对于较大的应用程序,当基于功能的组织可以提高可维护性时,请围绕功能组织代码。

对于小型应用程序,避免创建不必要的文件夹和文件。

18. 开发工作流程

针对 React 任务遵循此工作流程。

阶段 1:理解

  • 阅读任务要求。
  • 检查现有项目。
  • 确定受影响的组件。
  • 了解现有依赖项。
  • 识别潜在风险。

阶段 2:计划

  • 确定所需的更改。
  • 选择合适的实施方法。
  • 确定受影响的文件。
  • 考虑可访问性和安全性。
  • 确定所需的测试。

阶段 3:实施

  • 进行有针对性的更改。
  • 重用现有组件。
  • 遵循已建立的约定。
  • 避免不相关的修改。
  • 保持清晰的代码结构。

阶段 4:验证

  • 运行适当的测试。
  • 运行项目的构建命令。
  • 检查配置情况下的 linting 和类型错误。
  • 测试相关的用户交互。
  • 查看浏览器控制台错误。
  • 验证现有功能是否仍然有效。

在选择命令之前检查 package.json。不要假定脚本存在。

阶段 5:报告

解释:

  • 实现了什么。
  • 更改了哪些文件。
  • 重要的技术决策。
  • 执行的测试和命令。
  • 任何未解决的问题。
  • 任何需要完成的额外工作。

除非测试或构建实际执行并通过,否则永远不要声称其成功。

19. 禁止的做法

不要:

  • 为一个小功能重写整个应用程序。
  • 安装不必要的包。
  • 忽略现有架构。
  • 在没有正当理由的情况下使用过时的 React 模式。
  • 对每个操作都使用 effects。
  • 将所有应用程序逻辑放入一个组件中。
  • 在前端代码中暴露机密信息。
  • 信任前端授权。
  • 忽略可访问性。
  • 仅仅为了使构建通过而禁用 linting 或测试。
  • 在不理解错误的情况下抑制错误。
  • 声称未经验证的功能有效。
  • 在不解释影响的情况下进行重大迁移。

20. 完成定义

当满足以下条件时,React 任务即完成:

  • 请求的功能已实现。
  • 现有功能得以保留。
  • 组件遵循可维护的设计原则。
  • 状态和数据流易于理解。
  • API 交互能适当地处理失败。
  • 考虑了可访问性要求。
  • 遵循了安全要求。
  • 相关测试通过。
  • 在适用的情况下,生产构建成功。
  • 已知限制已记录。
  • 实施情况已清晰报告。

21. 相关技能

在可用的情况下,将此技能与以下技能结合使用:

  • frontend-engineering — 用于一般的前端架构和工程。
  • ui-ux-design — 用于用户体验和界面设计。
  • frontend-security — 用于前端特定的安全性。
  • frontend-testing — 用于前端测试实践。
  • backend-development — 用于后端集成。
  • api-engineering — 用于 API 设计和集成。

在相关情况下使用相关技能,而不要重复它们的职责。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能