react-patterns

Files (1)

• SKILL.md

SKILL.md (first lines)

## Git Delegation Rule

**HARD RULE**: NEVER run git commands. Delegate ALL git operations to `git-wrangler`.



# React Patterns

## Component Composition

### Compound Components
```tsx
// Parent manages shared state implicitly via React.Children
<Select>
  <Select.Option value="a">Option A</Select.Option>
  <Select.Option value="b">Option B</Select.Option>
</Select>
```
Use `React.Children.map` + `cloneElement` or Context to pass shared state.

### Render Props
```tsx
<MouseTracker render={(pos) => <Dot x={pos.x} y={pos.y} />} />
```

### Controlled vs Uncontrolled
- **Uncontrolled**: DOM manages its own state, use `ref` to read values.
- **Controlled**: React state is the single source of truth. Prefer this for form validation or conditional UI.
- **Mixed**: Pass `value` + `onChange` but allow internal default state — use `useControlledState` pattern.

## Hooks Patterns

### Custom Hook Naming
- `use` prefix, PascalCase after (e.g., `useLocalStorage`, `useDebounce`).
- Return a tuple for 2 values (`[value, setter]`), an object for 3+.

### Custom Hook Structure
```tsx
function useDebounce<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);

  return debounced;
}
```

### Effect Cleanup
Every `useEffect` that subscribes, polls, or sets intervals **must** return a cleanup function. Missing cleanup is the #1 React memory leak.

## State Management Decision Tree

```
Simple useState → enough for 90% of cases
Prop drilling pain → lift state or compose children
Sibling/remote shared state → Context (for low-frequency updates)
Frequent updates (auth, theme) → Context is fine
Complex global state → Zustand or Jotai (NOT Redux by default)
Heavy server state → TanStack Query (React Query)
Form state → React Hook Form or Formik
```

### Avoid Over-Engineering
❌ Don't add Redux for a boolean toggle.
❌ Don't wrap every value in Context — it causes unnecessary re-renders.
✅ Default to `useState`. Extract to `useReducer` when state logic is complex (3+ related values with interdependent updates).

## Performance

### Memoization — Only When Needed
```tsx
// Profile first. Then memoize.
const sorted = useMemo(() => expensiveSort(items), [items]);
const handleClick = useCallback(() => doThing(id), [id]);
```

Rules:
- `useMemo` for **computed values** from arrays/objects that trigger downstream effects.
- `useCallback` when passing callbacks to memoized children.
- `React.memo` on components that re-render with the same props frequently.
- **Don't** wrap everything — the overhead of comparison can exceed the render cost.

### List Rendering
```tsx
// Always use a stable, unique key
{items.map((item) => <ListItem key={item.id} item={item} />)}

// For static lists, key=index is acceptable. For dynamic lists, never.
// Extract list item into a memoized component if re-renders are expensive.
```

## Error Boundaries
Class component only (React <19). Catch render-phase errors. Cannot catch:
- Event handlers (use try/catch)
- Async code (use try/catch)
- SSR errors
- Errors in the boundary itself

```tsx
class ErrorBoundary extends React.Component<{ fallback: ReactNode }, { error: Error | null }> {
  state = { error: null };
  static getDerivedStateFromError(error: Error) { return { error }; }

  render() {
    if (this.state.error) return this.props.fallback;
    return this.props.children;
  }
}
```

React 19 introduces `useError` hook as an alternative.

## Directory Structure Convention

```
components/        → shared/reusable UI
  ui/              → primitive atoms (Button, Input, Modal)

From UgochukwuChidera/Opencode-Agents, GPL-3.0.

More from UgochukwuChidera/Opencode-Agents