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:
- No browser APIs called during render (server-proof)
- No hydration flash for client-storage values (hydration-proof)
- No hardcoded IDs; uses
useId()(instance-proof) - Server data fetches wrapped in
cache()(concurrent-proof) - Uses Context instead of
cloneElement(composition-proof) - Event listeners use
ownerDocument.defaultView(portal-proof) - State updates wrapped in
startTransition()where needed (transition-proof) - DOM side effects respect
<Activity>visibility (activity-proof) - Stable values use
useStateinitializer, notuseMemo(future-proof)
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