react

Sub-Skill: React Best Practices

Purpose: Prevents the React-specific mistakes LLMs make repeatedly — wrong state placement, stale closures, unnecessary re-renders, and broken async patterns. Concrete rules with code examples.

Rule classification

• MUST — load-bearing. Violating causes infinite loops, stale data, leaked subscriptions, or invisible UI bugs. Never break.
• SHOULD — default behavior. Deviation needs a documented reason in the code or PR.
• AVOID — usually wrong; documented exception inline where needed.

Where these rules don't strictly apply: test fixtures, Storybook stories, design-system primitives in isolation, and small in-tutorial demo components may legitimately differ. The rules below apply to production application code.

---

Component Design

1. SHOULD: Co-locate state with the component that owns it. Lift state only when two siblings genuinely share it. Lifting to a grandparent "just in case" causes unnecessary re-renders across the tree.

   // Avoid: form state lifted to page-level parent
   function Page() {
     const [email, setEmail] = useState('');
     return <Form email={email} setEmail={setEmail} />;
   }
   
   // Prefer: state lives in the component that uses it
   function Form() {
     const [email, setEmail] = useState('');
     return <input value={email} onChange={e => setEmail(e.target.value)} />;
   }
   

2. SHOULD: Split components at ~100 lines or when a section has its own data concern. One component = one responsibility. Extract <UserAvatar>, <OrderSummary> rather than one <ProfilePage> that does everything. Exception: pages that are mostly markup with little logic may exceed 100 lines.

3. SHOULD: Replace prop drilling beyond two levels with composition or context. Passing userId through four components to reach a button is a design smell.

   // Avoid: drilling through intermediaries
   <Layout userId={userId}><Sidebar userId={userId}><Nav userId={userId} /></Sidebar></Layout>
   
   // Prefer: context or render-prop composition
   <UserContext.Provider value={userId}><Layout /></UserContext.Provider>