vercel-composition-patterns

name	vercel-composition-patterns
description	React 组合模式，构建可扩展的组件架构。适用于重构充斥布尔属性的组件、构建灵活的组件库、设计可复用 API。触发词包括复合组件、render props、Context Provider、组件架构等。包含 React 19 API 变更。
license	MIT
metadata	{"author":"vercel","version":"1.0.0"}

React 组合模式

构建灵活、可维护 React 组件的组合模式指南。通过复合组件、状态提升和内部组合等方式，避免布尔属性泛滥。这些模式能让代码库在规模增长时，更易于人类和 AI Agent 理解和维护。

适用场景

参考这些指南的时机：

• 重构充斥大量布尔属性的组件
• 构建可复用的组件库
• 设计灵活的组件 API
• 审查组件架构
• 使用复合组件或 Context Provider

规则分类（按优先级）

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

快速参考

1. 组件架构（高优先级）

• architecture-avoid-boolean-props — 不要用布尔属性来定制行为，应使用组合模式
• architecture-compound-components — 通过共享 Context 组织复杂组件结构

2. 状态管理（中优先级）

• state-decouple-implementation — Provider 是唯一了解状态管理方式的组件
• state-context-interface — 定义包含 state、actions、meta 的泛型接口，实现依赖注入
• state-lift-state — 将状态提升到 Provider 组件，供兄弟组件共享访问

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