mcpField
C
composition-patterns

composition-patterns

github.com/blockmatic开发1214 次安装5 周前更新
代码仓库

关于 composition-patterns

composition-patterns 是一组面向 React 组件架构的规则，指导开发者用组合、复合组件和显式变体构建可复用 API。内容还涵盖状态放置及 React 19 的 ref 和 use() 规则，并明确区分服务端与客户端数据。

主要功能

  1. 01以组合替代布尔属性堆叠
  2. 02为复杂组件使用复合组件结构
  3. 03仅在兄弟组件需要时提升客户端状态
  4. 04使用显式变体和 children 进行组合
  5. 05提供 React 19 ref 与 use() 指引

适用场景

  1. 01重构含有大量布尔属性的组件
  2. 02设计可复用组件库 API
  3. 03评审组件架构和状态管理
  4. 04实现复合组件或上下文提供者

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/blockmatic/basilic-skills --skill composition-patterns

安装后在 Claude Code 中输入/composition-patterns确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
README.md
references/
compiled.md
rules/
_sections.md
_template.md
architecture-avoid-boolean-props.md
architecture-compound-components.md
patterns-children-over-render-props.md
patterns-explicit-variants.md
react19-no-forwardref.md
state-context-interface.md
state-decouple-implementation.md
state-lift-state.md

详细介绍

React 组合模式

用于构建灵活、易维护的 React 组件的组合模式。通过使用复合组件、提升状态和组合内部实现，避免布尔属性泛滥。上游来源： vercel-labs/agent-skills 中的 composition-patterns。

范围

  • 适用于：可复用组件 API、复合组件、显式变体、React 19 ref/use() 变更
  • 不适用于：视觉设计方向（frontend-design）；Next.js 缓存或 RSC 数据获取（next-v16、vercel-react）

假设

  • 典型的 Basilic 应用使用 React 19+；在 React 18 上跳过 React 19 规则部分
  • 服务端/客户端边界已存在；组合不得将服务端数据移入仅限客户端的提供程序

原则

  • 对于复用组件，优先采用组合，而非布尔配置
  • 仅当同级组件需要客户端 UI 状态时才提升状态；服务端数据留在服务端
  • 在第二个调用点出现后再提取共享基元，不要为一次性的路由 UI 提取

约束

必须
  • 仅当用于共享 UI 包或至少 2 个调用点时才提取复合组件；不要为单个路由叶节点提取
  • 让 React Server Components 自行获取数据；将服务端渲染的子项传递给客户端叶组件，而不是将这些数据提升到客户端提供程序中
  • 将可通过 URL 分享的状态、异步服务端状态和分组本地 UI 状态留给项目已有的库管理（查询字符串解析器、TanStack Query、分组状态钩子）——不要用通用上下文依赖注入层替代它们
应该
  • 除非父组件必须附加 ref，否则不要使用 forwardRef
  • 对复用 API 使用显式变体组件，而不是 isX 布尔模式
  • 优先使用 children，而不是 renderX 属性
避免
  • 为一次性页面过早抽象
  • 仅用于重新导出 RSC 获取的 props 的客户端提供程序
  • 为了“组合”所有内容而更改现有的 'use client' 位置

交互

适用场景

  • 重构包含许多布尔属性的组件
  • 构建可复用组件库
  • 设计灵活的组件 API
  • 审查组件架构
  • 使用复合组件或上下文提供程序

按优先级划分的规则类别

优先级类别影响前缀
1组件架构高architecture-
2状态管理中state-
3实现模式中patterns-
4React 19 API中react19-

快速参考

1. 组件架构（高）
  • architecture-avoid-boolean-props — 不要添加布尔属性来定制行为；使用组合
  • architecture-compound-components — 使用共享上下文组织复杂组件
2. 状态管理（中）
  • state-decouple-implementation — 提供程序是唯一了解状态管理方式的地方
  • state-context-interface — 定义包含状态、操作和元信息的通用接口，以用于依赖注入
  • state-lift-state — 将状态移入提供程序组件，以便同级组件访问

仅在上述约束允许的情况下应用这些规则。不要提升由服务端管理的数据。

3. 实现模式（中）
  • patterns-explicit-variants — 创建显式变体组件，而不是使用布尔模式
  • patterns-children-over-render-props — 使用 children 进行组合，而不是使用 renderX 属性
4. React 19 API（中等）

仅适用于 React 19 及更高版本。React 18 或更早版本请跳过本节。

  • react19-no-forwardref — 新建组件时不要使用 forwardRef。条件读取上下文时可以选择使用 use()；useContext() 仍受支持。

使用方法

阅读各规则文件，了解详细说明和代码示例：

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md

每个规则文件都包含其重要性说明、错误和正确示例，以及补充背景信息。

完整的编译版指南（请勿将其命名为 AGENTS.md；Cursor 始终会加载该文件名）：references/compiled.md

评论

支持 Markdown