סקיל Composition Patterns

פקודת התקנה

הסקיל הוא קובץ Markdown פתוח עם רישיון MIT. אפשר להוריד אותו ולהריץ בדיקת קוד לפני התקנה דרך הכפתורים שבראש העמוד.

מה הסקיל כולל?

הסקיל מתעד את הדפוסים המרכזיים לקומפוזיציה ב-React, עם דוגמאות קוד נכון ושגוי לכל אחד. הוא מאורגן לפי שכיחות הבעיה שהדפוס פותר, מה שמאפשר לקלוד לזהות את המתאים לכל מצב.

קוד הסקיל המלא

---
name: vercel-composition-patterns
description:
  React composition patterns that scale. Use when refactoring components with
  boolean prop proliferation, building flexible component libraries, or
  designing reusable APIs. Triggers on tasks involving compound components,
  render props, context providers, or component architecture. Includes React 19
  API changes.
license: MIT
metadata:
  author: vercel
  version: '1.0.0'
---

# React Composition Patterns

Composition patterns for building flexible, maintainable React components. Avoid
boolean prop proliferation by using compound components, lifting state, and
composing internals. These patterns make codebases easier for both humans and AI
agents to work with as they scale.

## When to Apply

Reference these guidelines when:

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

## 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-`      |

## Quick Reference

### 1. Component Architecture (HIGH)

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

### 2. State Management (MEDIUM)

- `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

### 3. Implementation Patterns (MEDIUM)

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

### 4. React 19 APIs (MEDIUM)

> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.

- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `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:

- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

מה הם Composition Patterns ולמה הסקיל הזה שונה?

Composition Patterns זה השם הכללי לאוסף של דפוסי עבודה שמאפשרים לחבר קומפוננטים ב-React באופן גמיש, בלי לכתוב ירושה או prop drilling עמוק. הסקיל מתעד את הדפוסים שצוות Vercel מיישם על Next.js עצמה, ומסביר מתי כל דפוס מתאים.

הבעיה שהוא פותר מוכרת. אפליקציה שגדלה מצטברים בה props שמועברות 5 רמות עומק רק כדי להגיע לעלה אחד. הקוד הופך לשביר, כל refactor שובר משהו. הסקיל הזה מציע מבנה נקי של קומפוזיציה דרך children, slots, ו-compound components, שמבטל את הצורך ב-prop drilling רוב הזמן.

בעולם שבו סקיל React Best Practices עוסק בביצועים, הסקיל הזה משלים אותו ועוסק במבנה. שניהם נכתבים לאותה ספרייה, אפשר להפעיל ביחד. בפרויקטי לקוחות שאני בונה על Next.js, השילוב הזה הוא מה שמאפשר לי למסור קוד שצוות פנימי יכול לתחזק לבד אחר כך.

מה Composition Patterns נותן לקלוד קוד?

הסקיל מוסיף לקלוד קוד מילון של דפוסים מאומתים, כל אחד עם הקשר ברור מתי לבחור בו. בלעדיו, הסוכן ייטה לחזור על אותו דפוס פשוט (props from parent) גם במצבים שדורשים ארכיטקטורה גמישה יותר.

התוצאה: ארכיטקטורה גמישה שמאפשרת הוספת פיצ׳רים בלי לשבור קוד קיים. בפרויקט בינוני, הסקיל חוסך לי כ-30 שעות refactoring על פני שלושה חודשים.

למי הסקיל הזה מתאים?

צוותי React שעובדים על אפליקציות בגודל בינוני: כשהבסיס הוא 50 ועד 200 קומפוננטים, התחזוקה הופכת לבעייתית בלי דפוסי קומפוזיציה ברורים. הסקיל מעניק להם את אותו סטנדרט שצוות Vercel מיישם פנימית.

מפתחים שמעבירים פרויקט מ-create-react-app ל-Next.js 15: המעבר ל-RSC מצריך הבנה איך לחלק קומפוננטים. הסקיל מספק מודל ברור לחלוקה הזאת, ומונע מלכודות נפוצות כמו «client component שצריך לעטוף server component».

מובילי טכנולוגיה שמגדירים סטנדרטים פנימיים: הסקיל הוא נקודת התחלה מצוינת לכתיבת מסמך guidelines פנימי. אפשר להוסיף אליו דפוסים ספציפיים לארגון, ולהפיץ לכל הצוות.

פרילנסרים שמוסרים קוד ללקוחות: לקוחות מצפים לקבל קוד שצוות פנימי יוכל לתחזק. ארכיטקטורה עם דפוסי קומפוזיציה סטנדרטיים מקלה על המעבר. אצלי בעבודות פיתוח, זה אחד הסקילים שאני מתקין בכל פרויקט.

מפתחים שעוברים ל-React 19: השינויים ב-React 19, כמו useFormStatus ו-Activity, דורשים הבנה חדשה של איך לחבר קומפוננטים. הסקיל כולל את הדפוסים החדשים, נדבך שלא קל למצוא במקומות אחרים.

מי שלא מתאים: אפליקציות עם מתחת ל-20 קומפוננטים בסך הכל. במקרים האלה, prop drilling פשוט עובד ולא יוצר בעיה. הסקיל מתחיל להחזיר ערך מ-30 קומפוננטים ומעלה.

איך Composition Patterns עזר לי בפרויקטים אמיתיים

ארבעת המקרים האלה מראים שהסקיל לא חוקים תיאורטיים, הוא ערכת כלים מעשית. בשילוב עם React Best Practices מקבלים זוג שמכסה גם ארכיטקטורה וגם ביצועים. אם יש לכם codebase שזקוק לארגון מחדש, אפשר לדבר על איך להתחיל.

סיכום

סקיל Composition Patterns הוא הסקיל שאני ממליץ עליו לכל מי שעובד על React בבינוני ומעלה. הוא לא מציע מהפכה, רק את אותם דפוסים מאומתים שצוות Vercel מיישם, מתועדים בצורה שקלוד קוד יכול ליישם אוטומטית.

אם אתם מתחילים, התקינו את הסקיל, פתחו פרויקט קיים, ובקשו «סקור את הקומפוננטים האלה לפי composition-patterns». התשובה תכלול רשימה של refactor עם סדר עדיפויות. אפשר לקבל החלטה מהירה על מה כדאי לעבוד.

הסקיל משלים יפה את סקיל react-best-practices ואת סקיל agent-browser, שלושתם מ-Vercel Labs. שילוב מועיל נוסף הוא עם סקיל frontend-design שמטפל ברובד החזותי, ועם web-design-guidelines שמסדר את הסטנדרטים.

בעבודות פיתוח תוכנה ו-בניית אוטומציות AI שאני מבצע ללקוחות, הסקילים האלה הם הבסיס לכל פרויקט React. ארכיטקטורת קומפוננטים נכונה משפיעה על קצב הפיתוח חודשים קדימה, וזאת ההזדמנות לקבע אותה נכון.

למידע נוסף על המתודולוגיה ועל לקוחות שאני מלווה במעבר לפיתוח עם AI, באתר של דביר נעמן תוכלו לקרוא על הגישה. אם אתם מעוניינים בליווי אישי לארכיטקטורת React, צרו קשר ונבדוק יחד מאיפה להתחיל.