Bulletproof React Components

健壮的React组件

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

以下9种模式可确保React组件在常规场景之外的真实环境中稳定运行——包括SSR、hydration、并发渲染、Portals等场景。

来源：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

编写或评审可复用React组件时，参考下方的快速规则
如需代码示例和深度解析，请阅读
```
./references/patterns.md
```
发布前对照检查清单逐一验证

Quick Rules

快速规则


localStorage
<script>
useId()
React.cache()
React.cloneElement()
ref.current?.ownerDocument.defaultView || window
startTransition()
useLayoutEffect
useState(() => value)

#	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.


localStorage
<script>
useId()
React.cache()
React.cloneElement()

startTransition()
useLayoutEffect
useState(() => value)

#	模式	规则
1	Server-Proof	渲染阶段切勿调用浏览器API（ `localStorage` 、 `window` 、 `document` ），请使用 `useEffect` 。
2	Hydration-Proof	注入同步内联 `<script>` ，在React hydration前设置客户端相关的值。
3	Instance-Proof	所有生成的ID均使用 `useId()` ，切勿在可复用组件中硬编码ID。
4	Concurrent-Proof	将服务端数据获取逻辑包裹在 `React.cache()` 中，以在每个请求中去重调用。
5	Composition-Proof	使用Context而非 `React.cloneElement()` ——cloneElement在Server Components、懒加载和memo场景下会失效。
6	Portal-Proof	事件监听使用`ref.current?.ownerDocument.defaultView
7	Transition-Proof	将状态更新包裹在 `startTransition()` 中，以启用View Transition API动画。
8	Activity-Proof	使用 `useLayoutEffect` 在组件被 `<Activity>` 隐藏时禁用DOM副作用（如 `<style>` 标签）。
9	Future-Proof	使用 `useState(() => value)` 来保证标识的稳定性。 `useMemo` 仅作为性能提示——React可能会丢弃它。

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)

构建可复用React组件时，请验证：

渲染阶段未调用浏览器API（Server-Proof）
客户端存储值未出现hydration闪烁（Hydration-Proof）
未硬编码ID；使用了
```
useId()
```
（Instance-Proof）
服务端数据获取已包裹在
```
cache()
```
中（Concurrent-Proof）
使用Context而非
```
cloneElement
```
（Composition-Proof）
事件监听使用
```
ownerDocument.defaultView
```
（Portal-Proof）
必要时将状态更新包裹在
```
startTransition()
```
中（Transition-Proof）
DOM副作用遵循
```
<Activity>
```
的可见性规则（Activity-Proof）
稳定值使用
```
useState
```
初始化器，而非
```
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. ...

评审组件是否符合这些模式时，请按以下格式输出：

**健壮性检查：`<ComponentName>`**

| 模式 | 状态 | 说明 |
|---------|--------|-------|
| Server-Proof | 通过/失败 | ... |
| ... | ... | ... |

**建议修复方案：**
1. ...

References

参考资料

```
./references/patterns.md
```
— Detailed code examples (bad/good) for all nine patterns

```
./references/patterns.md
```
— 包含所有9种模式的详细代码示例（错误/正确写法）

bulletproof-react-components

Original

Translation