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 useState initializer, not useMemo (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