bulletproof-react-components

Bulletproof React Components

九种模式，确保 React 组件在超出理想情况的真实环境中依然可靠——SSR、水合、并发渲染、门户等。

来源：shud.in/thoughts/build-bulletproof-react-components

工作原理

1. 编写或审查可复用的 React 组件时，请参阅下方的快速规则
2. 查看 ./references/patterns.md，了解代码示例和详细说明
3. 发布前逐项检查检查清单

快速规则

#	模式	规则
1	服务端安全	渲染期间绝不调用浏览器 API（localStorage、window、document）。请使用 useEffect。
2	水合安全	注入同步的内联 <script>，在 React 水合前设置依赖客户端的值。
3	实例安全	所有生成的 ID 都使用 useId()。可复用组件中绝不硬编码 ID。
4	并发安全	使用 React.cache() 包装服务端数据获取，以便在每个请求内去重调用。
5	组合安全	使用 Context 替代 React.cloneElement()——cloneElement 与 Server Components、lazy 和 memo 不兼容。
6	门户安全	使用 ref.current?.ownerDocument.defaultView || window 添加事件监听器，而不是全局 window。
7	过渡安全	使用 startTransition() 包装状态更新，以启用 View Transition API 动画。
8	Activity 安全	当 <Activity> 将 DOM 隐藏时，使用 useLayoutEffect 禁用 DOM 副作用（例如 <style> 标签）。
9	面向未来	使用 useState(() => value) 保持标识稳定。useMemo 只是性能提示——React 可能会丢弃它。

检查清单

构建可复用的 React 组件时，请确认：

• 渲染期间不调用浏览器 API（服务端安全）
• 客户端存储值不会出现水合闪烁（水合安全）
• 不硬编码 ID；使用 useId()（实例安全）
• 服务端数据获取使用 cache() 包装（并发安全）
• 使用 Context 替代 cloneElement（组合安全）
• 事件监听器使用 ownerDocument.defaultView（门户安全）
• 在需要时使用 startTransition() 包装状态更新（过渡安全）
• DOM 副作用遵循 <Activity> 的可见性（Activity 安全）
• 稳定值使用 useState 初始化函数，而非 useMemo（面向未来）

向用户展示结果

根据这些模式审查组件时，按以下格式输出：

**Bulletproof Check: `<ComponentName>`**

| Pattern | Status | Notes |
|---------|--------|-------|
| Server-Proof | PASS/FAIL | ... |
| ... | ... | ... |

**Suggested fixes:**
1. ...

参考资料

• ./references/patterns.md — 九种模式的详细代码示例（错误/正确）