主题

React app

React app 标记 React 是主要用户界面、管理台、控制台或嵌入式操作面 runtime。这里关心的是 route、component tree、client state、表单流、dashboard 交互和前端构建后的真实运行边界,而不是“项目依赖里有 React”。 这个 Topic 用来回答“用户实际操作的是不是一个 React runtime,以及它在系统里承担什么职责”。

  • 前端

目录

Definition

React app 标记 React 是主要用户界面、管理台、控制台或嵌入式操作面 runtime。这里关心的是 route、component tree、client state、表单流、dashboard 交互和前端构建后的真实运行边界,而不是“项目依赖里有 React”。

这个 Topic 用来回答“用户实际操作的是不是一个 React runtime,以及它在系统里承担什么职责”。它不替代 shadcn/ui、Storybook component QA、embedded admin UI 或 TypeScript web;这些 Topic 分别解释组件系统、QA surface、随服务交付的形态和底层 tooling。很多样本都不是“纯 React 产品”,而是 Rust service、Cloudflare Worker、Astro public site 或 firmware 系统里的一个操作面,所以必须把 React 的责任边界单独讲清楚(projects/kaisoumail.md、projects/loadlynx.md、projects/proxy-broker.md)。

When to use

当 web/、apps/web/、apps/admin/ 或 web/src/main.tsx 等入口证明 React/Vite/SPA 是产品界面时使用。纯文档站或只含 React 依赖的脚本不应自动命中。

如果改动会影响 React route、component state、form、dashboard、operator workflow、控制台 auth、SSE/polling 消费、theme、embedded UI build 或版本显示,就应使用本 Topic。若 React 只出现在示例、测试 fixture、历史依赖或由 Astro/MDX 间接使用,必须先核对当前入口、运行脚本和 project snapshot 再决定(projects/blog-26.md、projects/codex-vibe-monitor.md)。

Habits / defaults

  • Rust-backed services常把 React app embed 到同一 binary;要同时验证 web build 和 backend build。
  • React app 的项目标题不应显示 npm package name;用产品/系统名作为 H1。
  • 当 React app 采用 shadcn/ui,组件系统由 shadcn/ui Topic 说明,不要把所有 UI 规则塞进 React app。
  • 设备/ops UI 应保留 Storybook/Playwright/visual evidence 的项目记忆。
  • React app 的验证默认至少包含 typecheck/build;对 owner-facing UI 还应结合 Storybook、Playwright 或浏览器截图证据,尤其是表单、表格、Dialog、长文本和空态(projects/proxy-broker.md、projects/kaisoumail.md)。
  • 命中本 Topic 的 React 任务默认采用项目锁定版本的 React Doctor;目标项目未接入时,执行该任务的 Agent 应在当前 React 任务中补齐锁定依赖、版本化配置和现有 hook 接入,Playbook 本身不自动改写目标项目(https://github.com/millionco/react-doctor)。
  • React Doctor 的 pre-commit 以 staged React 文件为输入,CI 以 changed React 文件为输入;先成功计算下述文件集合,Git diff、base 解析或范围计算失败必须 fail-closed,不能当作空集合。集合为空时跳过并通过,不要求 React Doctor、依赖、锁文件或配置可执行;集合非空时才检查项目锁定工具及依赖、锁文件和配置,任一无法执行均阻断。执行成功后,error 阻断提交或 merge,warning 保持可见但不阻断。
  • CI 的 React Doctor 结果必须由 required check 承载;承载 job、失败传播、空集合状态和实际分支规则核验遵循 skills/style-playbook/references/topics/quality-gates/TOPIC.md。完整项目检查仍由 typecheck、build、测试和其他交付面 gate 负责。
  • 复用目标项目已有的 hook 管理器,不覆盖现有 hook;monorepo 只检查受影响的 React package,多交付面项目只把 React UI 纳入本默认契约,后端、固件和其他 UI 由相邻 Topic 覆盖。
  • 使用项目现有 package manager 和锁定版本,不在 hook 中使用 npx react-doctor@latest 或临时联网安装;规则例外通过下述版本化配置与审计注释表达,不通过本地命令参数静默绕过(https://react.doctor/docs/getting-started/install-for-coding-agents)。
  • 当前适用范围是 Web React;React Native 和 Expo 不继承本默认契约。
  • 对嵌入后端 binary 的 React UI,要同时检查前端 build 输出和后端静态资源服务路径;只跑其中一侧会漏掉版本注入、asset path 或 cache 问题(projects/codex-vibe-monitor.md)。
  • 先回答 React UI 是“主产品面”还是“辅助操作面”。projects/kaisoumail.md 的 control plane、projects/loadlynx.md 的设备 UI、projects/proxy-broker.md 的 operator console,风险和验证重点都不同,不能沿用同一套默认话术。
  • 对控制台类 React app,auth 和数据流通常和页面本身一样重要。Forward Auth、owner API key、Cloudflare identity/passkeys、SSE/polling 这些都属于 React surface 的真实边界,因为用户在 UI 上看到的行为取决于它们(projects/proxy-broker.md、projects/kaisoumail.md、projects/codex-vibe-monitor.md)。
  • 若 React app 只是 hybrid repo 的一个面,回答问题时默认把相邻 runtime 一起纳入检查清单。像 projects/blog-26.md 需要同时考虑 Astro/Next/gateway,不能只修 React 页面就宣称主题已覆盖。

React Doctor 文件选择

  • pre-commit 的 staged 集合来自 HEAD 到 Git index 的差异;首次提交没有 HEAD 时使用空树到 index 的差异。PR CI 的 changed 集合来自 merge-base(base SHA, head SHA) 到候选 head 的差异,base/head 取 PR 事件元数据;其他 CI 入口必须显式提供比较 base/head,不假定 main、master 或 origin/main。所需 ref、历史或 merge-base 不可解析时阻断。
  • Git 文件列表使用 NUL 分隔,以正确处理空格等路径字符;选择 ACMRT 的目标路径,即新增、复制、修改、重命名和类型变化。纯删除不进入扫描集合,重命名使用新路径;参与扫描的路径必须在对应 index 或候选 head 中存在。
  • 根据目标项目版本化的 workspace/package 声明、构建配置和 React 入口确定 Web React 源码根,纳入其中的 .js、.jsx、.ts、.tsx,包括相关 hooks/helpers。排除依赖目录、构建产物和版本化配置明确标记的生成目录;不能只按 .tsx 后缀或 React import 过滤,也不能把全仓所有 TypeScript 文件都视为 React 文件。
  • 按源码归属分组到受影响的 React package,传给该 package 使用的项目锁定 React Doctor 与配置;不扫描未受影响的 package,也不把后端、固件等相邻交付面混入输入。路径归属或排除范围无法确定属于范围计算失败,不能静默跳过。
  • 将筛选后的文件路径作为显式输入,报告这些文件的全部诊断;执行时不得让配置中的 partial scope 把结果收窄为仅新增问题或 changed lines。--scope changed 只报告相对 base 新引入的问题,不等于“选中文件中的全部诊断”,不能代替本契约。输入与诊断归属收敛到所选文件不表示内部分析绝不读取项目上下文;例如 maintainability 分析可能读取完整源码语料(https://www.react.doctor/docs/reference/cli-reference)。

React Doctor 规则例外

规则例外必须进入版本化 doctor.config.*。优先使用 doctor.config.ts,已有 .jsonc 可继续使用;在对应的 rules 或 ignore.overrides 配置旁以注释记录准确规则 ID、理由、影响路径/package 和复核日期。机器配置对象只使用 React Doctor 支持的字段,不添加 reason、reviewDate 等未知审计属性(https://www.react.doctor/docs/configuration/config-files)。

下面按两条 TypeScript 语句示范 doctor.config.ts 的合法审计格式;只有目标项目已验证理由成立时才采用该例外,其他文件仍执行同一规则:

  1. import { defineConfig } from "react-doctor/api";
  2. export default defineConfig({ ignore: { overrides: [{ /* 规则:react-doctor/no-danger;理由:此组件只消费经统一 HTML 净化入口处理且已验证的内容;影响范围:当前 React package 的 src/components/SanitizedHtml.tsx;复核日期:2027-01-14。 */ files: ["src/components/SanitizedHtml.tsx"], rules: ["react-doctor/no-danger"] }] } });

Reference implementations

  • projects/proxy-broker.md:Rust service + embedded shadcn/ui operator console。
  • projects/kaisoumail.md:Cloudflare control plane 的 React UI。
  • projects/blog-26.md:admin SPA 与 Astro/Next runtime 共存。
  • projects/loadlynx.md:设备 Web UI 作为双 MCU 系统的辅助控制面。
  • projects/codex-vibe-monitor.md:React dashboard 通过 REST API 与 SSE 消费 Rust service 数据,适合检查 UI runtime 与后端事件流如何共同形成产品。
  • projects/flux-purr.md:设备控制台把 React UI 放在 hardware/firmware mono-repo 内,提醒维护者 UI 变化可能牵动真实设备语义。

Failure modes

  • 把 React app 当成项目整体,会掩盖后端、固件或文档站边界。
  • 只跑 backend tests 不跑 web build/e2e,会漏掉 embedded UI 失败。
  • 把组件库选择写成 React Topic,会让 shadcn/ui / Storybook 规则失焦。
  • 只根据 package.json 依赖打标签会误伤文档站或历史包;应核对 src/main.tsx、route entry、build scripts 和项目快照中对 UI surface 的描述(projects/blog-26.md)。
  • React UI 预览通过不等于真实系统通过。对设备、ops 或 proxy dashboard,API、auth、SSE/polling、硬件状态和部署路径仍要在相邻 Topic 中记录验证边界(projects/loadlynx.md、projects/proxy-broker.md)。
  • 把 React surface 当作纯视觉层处理,会漏掉控制台的权限和数据契约。很多维护事故不是按钮样式错,而是 UI 连到了错误的 API、错误的 auth 上下文或错误的事件流(projects/kaisoumail.md、projects/codex-vibe-monitor.md)。
  • 混淆“公开站点的 React 岛”和“真正的 React app runtime”也很常见。修正方式是回看项目快照里是否存在独立 web/ / apps/admin/、独立 dev/build/preview 脚本,以及 UI 是否承担持续的用户任务。
  • 将 React Doctor 的 error 结果作为非阻断建议,会使默认质量契约失去阻断价值;应保留 error 阻断、warning 仅报告的结果语义。
  • 在 hook 中使用 @latest、临时联网安装或未锁定依赖,会让本地提交结果随时间漂移;应使用项目现有 package manager 和锁定版本。
  • 让 pre-commit 扫描整个仓库或把无关交付面混入 React Doctor,会拖慢本地反馈并扩大责任边界;应按 staged/changed React 文件和受影响 package 收敛范围。
  • 文件集合非空时,React Doctor 或其依赖、锁文件、配置无法执行却继续放行,会把“未检查”误报为“通过”;工具执行失败必须 fail-closed。成功确认空集合时应直接跳过,不先检查工具;Git diff、base 解析和范围计算失败也不得伪装成空集合。
  • 使用工具自行猜测的 base、只按 .tsx 过滤、忽略重命名目标或使用 --scope changed 只拦新增问题,会偏离 staged/changed 文件契约;应使用明确的 Git 比较范围、package 归属和显式文件输入,报告选中文件的全部诊断。
  • 通过临时命令参数绕过规则而不留下版本化记录,会使例外不可审计;在配置对象里臆造审计字段也不合法。例外应使用受支持的配置字段,并通过相邻注释记录规则、理由、影响范围和复核日期。
  • 把 React Doctor 当成 typecheck、build、测试、Storybook、Playwright、后端、固件或其他交付面检查的替代品,会留下未覆盖的系统风险。

Evidence index

  • projects/proxy-broker.md
  • projects/blog-26.md
  • projects/kaisoumail.md
  • projects/loadlynx.md
  • skills/style-playbook/references/topics/shadcn-ui/TOPIC.md
  • skills/style-playbook/references/topics/quality-gates/TOPIC.md
  • https://github.com/millionco/react-doctor
  • https://react.doctor/docs/getting-started/install-for-coding-agents
  • https://www.react.doctor/docs/reference/cli-reference
  • https://www.react.doctor/docs/configuration/config-files
  • https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches