composition-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Composition Patterns

React 组合模式

Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. Upstream:

composition-patterns

in vercel-labs/agent-skills.

用于构建灵活、易维护的 React 组件的组合模式。通过使用 compound components、状态提升和内部组合，避免布尔 prop 泛滥。上游：

composition-patterns

，位于 vercel-labs/agent-skills。

Scope

范围

Applies to: reusable component APIs, compound components, explicit variants, React 19 ref/
```
use()
```
changes
Does NOT cover: visual direction (frontend-design); Next.js caching or RSC data fetching (next-v16, vercel-react)

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

Assumptions

假设

React 19+ in typical Basilic apps; skip the React 19 rule section on React 18
Server/client boundaries already exist; composition must not move server data into client-only providers

典型的 Basilic 应用使用 React 19+；在 React 18 中跳过 React 19 规则章节
Server/client 边界已经存在；组合不得将服务端数据移入仅限客户端的 provider

Principles

原则

Prefer composition over boolean configuration for reused components
Lift client UI state only when siblings need it; keep server data on the server
Extract shared primitives after a second call site, not for one-off route UI

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

Constraints

约束

MUST

必须

Extract compound components only for a shared UI package or 2+ call sites, not a single route leaf
Keep React Server Components fetching their own data; pass server-rendered children into client leaves instead of lifting that data into a client provider
Leave URL-shareable state, async server state, and grouped local UI state on the libraries the project already uses (query-string parsers, TanStack Query, grouped-state hooks)—do not replace them with a generic context DI layer

仅针对共享 UI 包或存在 2 个及以上调用点时提取 compound components，而不是针对单个路由叶子节点
让 React Server Components 自行获取数据；将服务端渲染的 children 传入客户端叶子组件，而不是把这些数据提升到客户端 provider 中
让可通过 URL 共享的状态、异步服务端状态和分组的本地 UI 状态继续使用项目已有的库（query-string 解析器、TanStack Query、分组状态 hooks）——不要用通用 context DI 层替换它们

SHOULD

应该

Skip
```
forwardRef
```
unless a parent must attach a ref
Use explicit variant components instead of
```
isX
```
boolean modes on reused APIs
Prefer
```
children
```
over
```
renderX
```
props

除非父组件必须附加 ref，否则不要使用
```
forwardRef
```
在可复用 API 中使用显式 variant 组件，而不是
```
isX
```
布尔模式
优先使用
```
children
```
，而不是
```
renderX
```
props

AVOID

避免

Premature abstractions around a one-off screen
Client providers whose only job is to re-export RSC-fetched props
Breaking existing
```
'use client'
```
placement to “compose” everything

围绕一次性屏幕进行过早抽象
创建仅负责重新导出 RSC 所获 props 的客户端 provider
不要为了“组合”所有内容而破坏现有
```
'use client'
```
的放置位置

Interactions

交互

App Router / RSC: next-v16
React performance: vercel-react
shadcn primitives: shadcn-v3
URL state: nuqs-v2
Client async: tanstack-query-v5
Grouped local state: ahooks-v3

App Router / RSC：next-v16
React 性能：vercel-react
shadcn primitives：shadcn-v3
URL 状态：nuqs-v2
客户端异步：tanstack-query-v5
分组的本地状态：ahooks-v3

When to apply

何时应用

Refactoring components with many boolean props
Building reusable component libraries
Designing flexible component APIs
Reviewing component architecture
Working with compound components or context providers

重构包含许多布尔 props 的组件
构建可复用组件库
设计灵活的组件 API
审查组件架构
使用 compound components 或 context provider 时

Rule categories by priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Component Architecture	HIGH	`architecture-`
2	State Management	MEDIUM	`state-`
3	Implementation Patterns	MEDIUM	`patterns-`
4	React 19 APIs	MEDIUM	`react19-`

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

Quick reference

快速参考

1. Component Architecture (HIGH)

1. 组件架构（高）

```
architecture-avoid-boolean-props
```
— Don't add boolean props to customize behavior; use composition
```
architecture-compound-components
```
— Structure complex components with shared context

```
architecture-avoid-boolean-props
```
——不要添加用于自定义行为的布尔 props；使用组合
```
architecture-compound-components
```
——使用共享 context 构建复杂组件

2. State Management (MEDIUM)

2. 状态管理（中）

```
state-decouple-implementation
```
— Provider is the only place that knows how state is managed
```
state-context-interface
```
— Define generic interface with state, actions, meta for dependency injection
```
state-lift-state
```
— Move state into provider components for sibling access

Apply these only where the Constraints above allow. Do not lift server-owned data.

```
state-decouple-implementation
```
——Provider 是唯一了解状态管理方式的位置
```
state-context-interface
```
——定义包含 state、actions 和 meta 的通用 interface，用于依赖注入
```
state-lift-state
```
——将状态移入 provider 组件，以便同级组件访问

仅在上述约束允许的范围内应用这些规则。不要提升服务端拥有的数据。

3. Implementation Patterns (MEDIUM)

3. 实现模式（中）

```
patterns-explicit-variants
```
— Create explicit variant components instead of boolean modes
```
patterns-children-over-render-props
```
— Use children for composition instead of renderX props

```
patterns-explicit-variants
```
——创建显式 variant 组件，而不是布尔模式
```
patterns-children-over-render-props
```
——使用 children 进行组合，而不是 renderX props

4. React 19 APIs (MEDIUM)

4. React 19 API（中）

React 19+ only. Skip this section on React 18 or earlier.

```
react19-no-forwardref
```
— Don't use
```
forwardRef
```
for new components.
```
use()
```
is optional for conditional context reads;
```
useContext()
```
remains supported.

仅适用于 React 19+。在 React 18 或更早版本中跳过本节。

```
react19-no-forwardref
```
——不要在新组件中使用
```
forwardRef
```
。
```
use()
```
可选，用于按条件读取 context；
```
useContext()
```
仍然受支持。

How to use

如何使用

Read individual rule files for detailed explanations and code examples:

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

Each rule file contains why it matters, incorrect and correct examples, and extra context.

Full compiled guide (do not name this

AGENTS.md

; Cursor always-loads that filename): references/compiled.md

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

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

每个规则文件都包含该规则为何重要、错误与正确示例，以及补充上下文。

完整编译版指南（不要将其命名为

AGENTS.md

；Cursor 始终会加载该文件名）：references/compiled.md