| name | bulletproof-react-components |
| description | Build bulletproof React components that survive SSR, hydration, concurrent rendering, portals, transitions, and future React changes. Nine essential patterns from Shu Ding's guide. Use when writing reusable React components, fixing hydration mismatches, handling SSR edge cases, or building component libraries. |
Bulletproof React Components
Nine patterns that ensure React components survive real-world conditions beyond the happy path — SSR, hydration, concurrent rendering, portals, and more.
Source: shud.in/thoughts/build-bulletproof-react-components
How It Works
- When writing or reviewing a reusable React component, consult the Quick Rules below
- For code examples and deeper explanation, read
./references/patterns.md
- Run through the Checklist before shipping
Quick Rules
| # | Pattern | Rule |
|---|
| 1 | Server-Proof | Never call browser APIs (localStorage, window, document) during render. Use useEffect. |
| 2 | Hydration-Proof | Inject a synchronous inline <script> to set client-dependent values before React hydration. |
| 3 | Instance-Proof | Use useId() for all generated IDs. Never hardcode IDs in reusable components. |
| 4 | Concurrent-Proof | Wrap server data-fetching in React.cache() to deduplicate calls per request. |
| 5 | Composition-Proof | Use Context instead of React.cloneElement() — cloneElement breaks with Server Components, lazy, and memo. |
| 6 | Portal-Proof | Use ref.current?.ownerDocument.defaultView || window for event listeners, not the global window. |
| 7 | Transition-Proof | Wrap state updates in startTransition() to enable View Transition API animations. |
| 8 | Activity-Proof | Use useLayoutEffect to disable DOM side effects (e.g., <style> tags) when hidden by <Activity>. |
| 9 | Future-Proof | Use useState(() => value) for stable identity. useMemo is only a performance hint — React may discard it. |
Checklist
When building a reusable React component, verify:
Present Results to User
When reviewing a component against these patterns, format as:
**Bulletproof Check: `<ComponentName>`**
| Pattern | Status | Notes |
|---------|--------|-------|
| Server-Proof | PASS/FAIL | ... |
| ... | ... | ... |
**Suggested fixes:**
1. ...
References
./references/patterns.md — Detailed code examples (bad/good) for all nine patterns