AgentSkillsCN

bulletproof-react-components

打造经得起考验的 React 组件，使其能够从容应对 SSR、水合渲染、并发渲染、Portal、过渡动画，以及未来 React 的各项更新。借鉴 Shu Ding 的指南，掌握九大必备模式。在编写可复用的 React 组件、修复水合不匹配、处理 SSR 边缘场景，或构建组件库时，应运用此技能。

SKILL.md
--- frontmatter
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

  1. •When writing or reviewing a reusable React component, consult the Quick Rules below
  2. •For code examples and deeper explanation, read ./references/patterns.md
  3. •Run through the Checklist before shipping

Quick Rules

#PatternRule
1Server-ProofNever call browser APIs (localStorage, window, document) during render. Use useEffect.
2Hydration-ProofInject a synchronous inline <script> to set client-dependent values before React hydration.
3Instance-ProofUse useId() for all generated IDs. Never hardcode IDs in reusable components.
4Concurrent-ProofWrap server data-fetching in React.cache() to deduplicate calls per request.
5Composition-ProofUse Context instead of React.cloneElement() — cloneElement breaks with Server Components, lazy, and memo.
6Portal-ProofUse ref.current?.ownerDocument.defaultView || window for event listeners, not the global window.
7Transition-ProofWrap state updates in startTransition() to enable View Transition API animations.
8Activity-ProofUse useLayoutEffect to disable DOM side effects (e.g., <style> tags) when hidden by <Activity>.
9Future-ProofUse 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:

code
**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