ahonn React Best Practices
Performance patterns and guidelines from react.dev and Vercel Engineering.
Quick Reference (Priority Order)
CRITICAL - Must Follow
| Rule | Impact | Reference |
|---|---|---|
| Avoid unnecessary effects | Render cycles, bugs | effect-pitfalls.md |
| Eliminate waterfalls | First paint, TTI | async-waterfall-elimination.md |
| Parallel data fetching | Load time | async-parallel-requests.md |
| Avoid barrel imports | Bundle size | bundle-barrel-imports.md |
HIGH - Strongly Recommended
| Rule | Impact | Reference |
|---|---|---|
| React Compiler (19+) | Auto memoization | react-compiler.md |
| Dynamic imports | Code splitting | bundle-dynamic-import.md |
| Preload on user intent | Perceived latency | bundle-preload.md |
| Strategic memo() | Render perf | rerender-memo-strategy.md |
| Server caching | Server response | server-cache-patterns.md |
MEDIUM - Recommended
| Rule | Impact | Reference |
|---|---|---|
| State structure | Maintainability | state-structure.md |
| Immutable updates | Avoid mutation bugs | immutable-updates.md |
| Context splitting | Avoid rerenders | rerender-context-splitting.md |
| startTransition | UI responsiveness | rerender-transitions.md |
| Set/Map lookups | O(1) vs O(n) | js-set-map-lookups.md |
| Key patterns | List rendering | rendering-key-patterns.md |
LOW - Nice to Have
| Rule | Impact | Reference |
|---|---|---|
| content-visibility | Long list render | rendering-content-visibility.md |
| Hydration flicker | SSR stability | rendering-hydration-flicker.md |
| Hoist static JSX | Avoid re-creation | rendering-hoist-static-jsx.md |
Quick Decision Tree
React Issue?
├── Writing useEffect?
│ └── Check if needed → effect-pitfalls.md (CRITICAL)
├── Designing state?
│ └── Follow 5 principles → state-structure.md
├── Updating state?
│ └── Use immutable patterns → immutable-updates.md
├── Using React 19+?
│ └── Enable React Compiler → react-compiler.md
├── Slow initial load?
│ ├── Check for waterfalls → async-waterfall-elimination.md
│ ├── Check bundle size → bundle-barrel-imports.md
│ └── Preload on intent → bundle-preload.md
├── Slow interactions?
│ ├── Check re-renders → rerender-memo-strategy.md
│ ├── Check Context usage → rerender-context-splitting.md
│ └── Use transitions → rerender-transitions.md
├── Long list jank?
│ └── Use content-visibility → rendering-content-visibility.md
├── SSR flicker?
│ └── Inline script pattern → rendering-hydration-flicker.md
└── Slow server?
└── Check caching → server-cache-patterns.md
Reference Files
| File | Content |
|---|---|
| hooks-guide.md | Hook patterns, decision guides, pitfalls |
| effect-pitfalls.md | When NOT to use useEffect |
| react-compiler.md | React 19+ auto memoization |
| state-structure.md | 5 principles for state design |
| immutable-updates.md | Array/object update patterns |
| references/ | All reference files (19 total) |
Search rules: grep -l "keyword" references/