react-rerender-mental-models

# React Re-render Mental Models A practical guide to understanding how React re-renders actually work, debunking common misconceptions, and knowing when optimization is truly needed. ## Core Philosophy > "Trust React to be fast. Write simple code. Measure when something actually feels slow. Optimize based on data, not fear." ## When to Apply Reference these guidelines when: - Writing new React components - Reviewing code for performance issues - Deciding whether to add React.memo, useCallback, or useMemo - Debugging perceived "slowness" in React apps - Refactoring component architecture ## Rule Categories | Category | Prefix | Description | |----------|--------|-------------| | Mental Models | `mental-model-` | Correct understanding of how React works | | Anti-Patterns | `anti-pattern-` | Common mistakes to avoid | | When to Memoize | `when-to-memo-` | Profile-driven optimization guidance | | Architecture | `architecture-` | Component structure patterns | ## Quick Reference ### Mental Models (Foundational) - `mental-model-parent-triggers` - Props don't trigger re-renders; parent re-renders do - `mental-model-render-vs-commit` - Render ≠ Commit; renders are cheap, commits touch DOM ### Anti-Patterns (Avoid These) - `anti-pattern-premature-memo` - Don't memoize without profiling first - `anti-pattern-memoization-trap` - Real bottlenecks are often not re-renders ### When to Memoize (Use Sparingly) - `when-to-memo-context-values` - Stabilize context object references - `when-to-usecallback` - Only needed when child is already memoized ### Architecture (Prefer These) - `architecture-local-state` - Keep state close to where it's used - `architecture-composition` - Component structure prevents re-renders naturally ## What Actually Triggers Re-renders 1. **Component's own state changes** (useState, useReducer) 2. **Parent component re-renders** (cascades to all children) 3. **Context value changes** (for consumers of that context) **Props are NOT on this list.** Props are inputs to a render that's already happening—they don't schedule one. ## The Performance Debugging Flow ``` 1. Something feels slow 2. Open React DevTools Profiler 3. Record the interaction 4. Look for components with 50ms+ render times 5. If found → consider memoization 6. If not found → the problem is elsewhere: - API calls firing too often - Unoptimized images - Too many DOM nodes - CSS animations triggering layout ``` ## React 19 Compiler This project runs React 19. The **React Compiler** (formerly React Forget) is an opt-in build-time tool that statically analyzes components and automatically inserts the equivalent of `useMemo`, `useCallback`, and `React.memo`. It is **not enabled by default** — it requires `babel-plugin-react-compiler` (or the SWC equivalent) to be installed and configured. - If the compiler is **enabled in this project**: skip manual memoization. The compiler tracks data flow within each component and caches results at a more granular level than hand-written hooks. If the compiler opts out a specific component (e.g. due to side effects during render), fix the component rather than adding manual memo. - If the compiler is **not enabled** (current default): follow the rules below, but prefer architecture fixes (local state, composition) over adding memo/useCallback. Regardless of compiler status, the mental models and architecture rules in this skill still apply — composition and local state are always better than relying on memoization (auto or manual). Re-render triggers remain the same either way. ## How to Use Read individual rule files for detailed explanations and code examples: ``` rules/mental-model-parent-triggers.md rules/anti-pattern-premature-memo.md rules/architecture-local-state.md ``` Each rule file contains: - Brief explanation of why it matters - Incorrect code example with explanation - Correct code example with explanation