typescript-react-nextjs-patterns

TypeScript for React & Next.js — Agent 技能

面向 AI 编码 Agent 的结构化参考，帮助前端工程师在生产环境中使用 TypeScript、React 和 Next.js。

---

Agent 行为规则

回答前，始终确认：

1. 服务端还是客户端？ Server Components、Server Actions 和 Route Handlers 的类型约束与 "use client" 组件不同。
2. 是否需要运行时验证？ 静态类型不会验证 API 响应、URL 参数、表单数据或 localStorage。跨越信任边界的数据需要使用 Zod 或同等方案验证。
3. 使用 App Router 还是 Pages Router？ 两者的模式有显著差异。如果不明确，请询问。
4. TypeScript 版本是什么？ satisfies 需要 5.0+，NoInfer 需要 5.4+，推导出的类型谓词需要 5.5+。TS 6.0 是基于 JavaScript 的最后一个编译器版本；TS 7 是使用 Go 原生实现的重写版本——速度约快 10 倍，语言相同，但使用旧编译器 API 的工具可能更新滞后。
5. Next.js 版本是什么？ 在 15+ 中，params 是一个 Promise。16+ 更改了缓存模型（"use cache"），并将 16 中的 middleware.ts 重命名为 proxy.ts（Node 运行时）。
6. React 版本是什么？ React 19 将 ref 变为普通属性（forwardRef 已弃用），支持直接渲染 <Context>，并用 useActionState 替换 useFormState。useEffectEvent 和 <Activity> 需要 19.2+。

Agent 不得作出以下假设：

• 假设 API 响应在运行时符合其 TypeScript 类型
• 假设 searchParams 的值是预期类型（它们始终是 string | string[] | undefined）
• 假设现有代码中的 any 是有意为之
• 未检查上下文就假设类型断言（as）合理
• 假设仅服务端导入在客户端组件中安全
• 假设现有代码中的 useEffect 依赖项正确

不确定时：

• 明确说明权衡，而不是默默选择一种方案
• 将不稳定或依赖版本的模式标注为此类模式
• 区分：[硬性规则]（违反会导致 Bug）／[默认做法]（有理由时可调整）／[视情况而定]（取决于上下文）

上下文压缩后：

如果本次会话经过压缩，且规则内容只在摘要中保留：

1. 不要根据摘要作答——摘要会遗漏推理过程、示例和边界情况。
2. 继续之前，先从下方的决策指南中重新阅读相关文件。阅读一个文件即可；此索引刻意保持精简，以便快速恢复。
3. 如果任务进行到一半且不确定该看哪个文件，请先重新阅读 HARD-RULES.md——其中以压缩形式列出了所有不可妥协的规则。

---

决策指南

快速参考：我应该使用哪种模式？

情况	从这里开始
为组件 Props、children、事件、refs 添加类型	→ react-typescript-patterns.md
缩窄联合类型、unknown、类型守卫、工具类型	→ typescript-core.md
Next.js 的 params、searchParams、Server Actions、RSC 边界	→ nextjs-typescript.md
可辨识联合、条件属性、复合组件	→ component-patterns.md
API 响应、fetch 类型、TanStack Query、缓存	→ data-fetching-and-api-types.md
表单状态、验证、受控与非受控	→ forms-and-validation.md
本地状态与 context、服务端状态、Zustand 的选择	→ state-management.md
重新渲染、记忆化、无障碍性	→ performance-and-accessibility.md
类型错误、hydration、过期状态、effect Bug	→ debugging-checklists.md（索引）+ playbooks/
PR 审查、风险与偏好、架构异味	→ code-review-rules.md
常见错误、盲目照搬的模式	→ anti-patterns.md

流程图：这些数据可以安全使用吗？

Data comes from...
├─ Inside the app (useState, useReducer, computed)
│  → Static typing is sufficient. No runtime validation needed.
│
├─ Outside the app (API, URL, FormData, localStorage, postMessage)
│  → [HARD RULE] Validate at runtime. Use Zod or equivalent.
│  │
│  ├─ API response    → schema.parse(await res.json())
│  ├─ URL params      → schema.parse(searchParams)
│  ├─ FormData        → schema.safeParse({ field: formData.get('field') })
│  ├─ localStorage    → schema.safeParse(JSON.parse(stored))
│  └─ postMessage     → schema.safeParse(event.data)
│
└─ Third-party library callback
   → Check library types. Add runtime guard if types seem wrong.

流程图：状态应该放在哪里？

Is this data from a server/API?
├─ Yes → TanStack Query (NOT useState). See data-fetching-and-api-types.md
│
└─ No → Is it shareable via URL? (filters, page, sort)
   ├─ Yes → searchParams or nuqs. See state-management.md
   │
   └─ No → How many components need it?
      ├─ 1 component → useState or useReducer
      ├─ 2-3 in same tree → Lift state up (props)
      └─ Many across trees → How often does it change?
         ├─ Rarely (theme, locale, auth) → Context
         └─ Often (cart, notifications) → Zustand with selectors

流程图：我应该对这个进行记忆化吗？

Is there a measured performance problem?
├─ No → Don't memoize. Stop here.
│
└─ Yes → Can you restructure instead?
   ├─ Yes → Move state down, extract components. See performance-and-accessibility.md
   │
   └─ No → What needs memoizing?
      ├─ Expensive computation → useMemo (verify it's truly expensive)
      ├─ Callback to memoized child → useCallback
      └─ Component in a long list → React.memo (verify props are stable)

快速指南：硬性规则、默认做法与视情况而定

标签	含义	示例
[HARD RULE]	违反会导致错误或安全问题。没有例外。	“在运行时验证 API 响应”
[DEFAULT]	建议遵循，除非有记录在案的理由偏离。	“Props 使用 interface”
[SITUATIONAL]	取决于具体情境。两种选择都有效。请说明你的选择。	“多态组件——仅用于设计系统基础组件”

偏离 [DEFAULT] 时，请将原因写在后续会话能够找到的地方——在偏离处添加一行注释，或写入提交消息——因为上下文压缩和新会话不会记得这些原因。

---

代码生成检查清单

生成 TypeScript/React/Next.js 代码之前：

上下文

• 已确认：服务端代码还是客户端代码？
• 已确认：App Router 还是 Pages Router？
• 已确认：是否启用了 TypeScript 严格模式？

类型安全

• 不使用 any——使用 unknown 并进行验证，或使用适当的类型
• 不使用 as，除非有记录在案的理由
• 在运行时验证外部数据（API、URL、表单、存储）
• Props 使用 interface，只有真正可选的字段才使用 ?

React

• 将 children 类型标注为 React.ReactNode
• 事件处理器 Props 暴露值，而非事件对象
• Effect 具有稳定的依赖项和清理函数
• 仅在必要的地方使用 "use client"，并尽可能深入组件树
• 不将服务端数据重复存储到 useState

Next.js (15+)

• 对 params 和 searchParams 使用 await
• Server Actions 使用 Zod 验证 FormData
• 使用 import 'server-only' 保护敏感代码
• 跨边界 Props 可由 RSC 序列化（不使用普通回调或类实例；Date/Map/Set/Promise 可以）

无障碍

• 表单输入框具有关联的标签
• 错误消息使用 role="alert"
• 交互元素可通过键盘访问

---

代码审查检查清单

标记为风险（可能导致错误或维护问题）

• any 没有记录在案的理由
• 对外部数据使用 as，但没有进行验证
• ! 非空断言之前没有守卫条件
• useEffect 使用对象/数组作为依赖项（可能不稳定）
• 缺少 useEffect 清理函数
• 将服务端数据复制到 useState
• 在页面/布局级别使用 "use client"
• 在服务端/客户端边界传递非 Server Function 回调或类实例
• params/searchParams 未使用 await（Next.js 15+）
• Server Action 未验证 FormData

标记为偏好（提及，但不阻止）

• 对象结构使用 type 还是 interface
• 处理器命名约定
• 文件/文件夹组织风格
• 导入顺序

---

文件索引

文件	范围
HARD-RULES.md	所有 [HARD RULE] 汇总于一页 — 压缩恢复、嵌入 CLAUDE.md、钩子注入
typescript-core.md	类型收窄、联合类型、泛型、工具类型、类型推断、unknown 与 any、as const、satisfies
react-typescript-patterns.md	Props、children、事件、refs（19 个 ref-as-prop / 18 个 forwardRef）、钩子、上下文
nextjs-typescript.md	App Router 类型、params、searchParams、Server Actions、RSC 边界、Cache Components（16）、proxy.ts、元数据
component-patterns.md	可辨识联合 Props、复合组件、受控/非受控、多态
data-fetching-and-api-types.md	Fetch 类型、Zod 验证、TanStack Query、安全的响应处理
forms-and-validation.md	表单状态、Zod、react-hook-form、Server Actions、渐进增强
state-management.md	本地状态、Context、Zustand、TanStack Query、URL 状态、决策矩阵
performance-and-accessibility.md	记忆化的权衡、Effect 稳定性、语义化 HTML、ARIA 模式
debugging-checklists.md	快速诊断路由、序列化问题、空值访问、重新渲染错误
code-review-rules.md	风险与偏好、架构异味、评审评论模板
anti-patterns.md	13 个常见错误及其根本原因和修复方法

playbooks/ — 分步调试指南（诊断特定错误时查阅）

文件	范围
type-error-debugging.md	系统化解决类型错误，包括 React/Next.js 特有错误
hydration-issues.md	SSR/CSR 不匹配诊断流程图及修复模式
effect-dependency-bugs.md	无限循环、过期闭包、缺失清理，以及实际的防抖示例