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