millionco / react-doctor

查看原文 / View Original 编辑 / Edit

millionco / react-doctor

Your agent writes bad React, this catches it. One command scans your codebase and outputs a 0 to 100 health score with actionable diagnostics. Works with Next.js, Vite, and React Native. 如果你的 AI 编程助手写出的 React 代码质量不佳，这个工具可以帮你发现问题。只需一条命令即可扫描整个代码库，并输出 0 到 100 分的健康评分以及可执行的诊断建议。它支持 Next.js、Vite 和 React Native。

See it in action → Install Run this at your project root: npx -y react-doctor@latest. You’ll get a score (75+ Great, 50 to 74 Needs work, under 50 Critical) and a list of issues across state & effects, performance, architecture, security, accessibility, and dead code. Rules toggle automatically based on your framework and React version. 查看演示 → 安装：在项目根目录运行 npx -y react-doctor@latest。你将获得一个评分（75 分以上为优秀，50 到 74 分为需改进，50 分以下为严重），以及涵盖状态与副作用、性能、架构、安全、可访问性和死代码等方面的详细问题列表。规则会根据你的框架和 React 版本自动切换。

Install for your coding agent: Teach your coding agent React best practices so it stops writing the bad code in the first place. npx -y react-doctor@latest install. You’ll be prompted to pick which detected agents to install for. Pass --yes to skip prompts. Works with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents. 为你的编程助手安装：教会你的 AI 编程助手 React 最佳实践，从源头上杜绝糟糕代码的产生。运行 npx -y react-doctor@latest install。系统会提示你选择要安装的检测代理，添加 --yes 参数可跳过提示。它支持 Claude Code、Cursor、Codex、OpenCode 以及其他 50 多种编程助手。

GitHub Actions: A composite action ships with this repository. Drop it into .github/workflows/react-doctor.yml: GitHub Actions：本仓库提供了一个复合 Action。将其放入 .github/workflows/react-doctor.yml 即可使用：

name: React Doctor
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
  pull-requests: write # required to post PR comments
jobs:
  react-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0 # required for `diff`
      - uses: millionco/react-doctor@main
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

When github-token is set on pull_request events, findings are posted (and updated) as a PR comment. The action also exposes a score output (0–100) you can use in subsequent steps. Inputs: directory, verbose, project, diff, github-token, fail-on (error / warning / none), offline, node-version. See action.yml for full descriptions. Prefer not to add a marketplace action? The bare npx form works too: - run: npx -y react-doctor@latest --fail-on warning 当在 pull_request 事件中设置了 github-token 时，扫描结果会以 PR 评论的形式发布（并自动更新）。该 Action 还会输出一个评分（0–100），供后续步骤使用。输入参数包括：directory、verbose、project、diff、github-token、fail-on（error / warning / none）、offline、node-version。详细说明请参阅 action.yml。不想添加 Marketplace Action？直接使用 npx 命令也可以：- run: npx -y react-doctor@latest --fail-on warning。

Configuration: Create a react-doctor.config.json in your project root: 配置：在项目根目录创建 react-doctor.config.json：

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**"],
    "overrides": [
      {
        "files": ["components/modules/diff/**"],
        "rules": ["react-doctor/no-array-index-as-key", "react-doctor/no-render-in-render"]
      }
    ]
  }
}

Three nested keys, three layers of granularity — pick the narrowest one that fits: ignore.rules silences a rule across the whole codebase. ignore.files silences every rule on the matched files (use sparingly — it loses coverage for unrelated rules). ignore.overrides silences only the listed rules on the matched files, leaving every other rule active. This is what you want when a single file (or glob) legitimately needs an exemption from one or two rules but should still be scanned for everything else. 三个嵌套键，三个粒度层级——选择最适合的一个：ignore.rules 可在整个代码库中禁用某条规则。ignore.files 可在匹配的文件中禁用所有规则（请谨慎使用，因为这会丢失其他无关规则的覆盖）。ignore.overrides 仅在匹配的文件中禁用列出的规则，同时保留其他所有规则的活跃状态。当你需要对某个文件（或路径匹配）豁免一两条规则，但仍希望对其进行其他检查时，这是最佳选择。

You can also use the “reactDoctor” key in package.json. CLI flags always override config values. React Doctor respects .gitignore, .eslintignore, .oxlintignore, .prettierignore, and linguist-vendored / linguist-generated annotations in .gitattributes. Inline // eslint-disable* and // oxlint-disable* comments are honored too. If you have a JSON oxlint or eslint config (.oxlintrc.json or .eslintrc.json), its rules get merged into the scan automatically and count toward the score. Set adoptExistingLintConfig: false to opt out. 你也可以在 package.json 中使用 “reactDoctor” 键。CLI 参数总是会覆盖配置文件中的值。React Doctor 会遵循 .gitignore、.eslintignore、.oxlintignore、.prettierignore 以及 .gitattributes 中的 linguist-vendored / linguist-generated 注解。内联的 // eslint-disable* 和 // oxlint-disable* 注释也会被识别。如果你有 JSON 格式的 oxlint 或 eslint 配置（.oxlintrc.json 或 .eslintrc.json），其规则会自动合并到扫描中并计入评分。设置 adoptExistingLintConfig: false 可禁用此功能。

Optional companion plugins: When the following ESLint plugins are installed in the scanned project (or hoisted in your monorepo), React Doctor folds their rules into the same scan. Both are listed as optional peer dependencies — install only what you want. 可选的配套插件：当扫描的项目中安装了以下 ESLint 插件（或在 Monorepo 中被提升）时，React Doctor 会将它们的规则合并到同一扫描中。两者均作为可选的 peer dependencies 列出——按需安装即可。

PluginAdds Namespace
eslint-plugin-react-hooks (v6 or v7)The React Compiler frontend’s correctness rules — fired when a React Compiler is detected in the project.
eslint-plugin-react-you-might-not-need-an-effect (v0.10+)Complementary effects-as-anti-pattern rules (no-derived-state, no-chain-state-updates, no-event-handler, no-pass-data-to-parent, …) that run alongside React Doctor’s native State & Effects rules.
插件添加的命名空间
eslint-plugin-react-hooks (v6 或 v7)React Compiler 前端的正确性规则——当项目中检测到 React Compiler 时触发。
eslint-plugin-react-you-might-not-need-an-effect (v0.10+)补充性的“副作用即反模式”规则（如 no-derived-state, no-chain-state-updates 等），与 React Doctor 原生的状态与副作用规则协同运行。

Inline suppressions: 内联抑制：

// react-doctor-disable-next-line react-doctor/no-cascading-set-state
useEffect(() => {
  setA(value);
  setB(value);
}, [value]);

When two rules fire on the same line, you have two equivalent options. Comma-separate the rule ids on a single comment: // react-doctor-disable-next-line react-doctor/rerender-state-only-in-handlers, react-doctor/no-derived-useState. Or stack one comment per rule directly above the diagnostic. Stacked comments are honored as long as nothing but other react-doctor-disable-next-line comments sits between them and the target line. 当同一行触发两条规则时，你有两种等效的处理方式。可以在单行注释中用逗号分隔规则 ID：// react-doctor-disable-next-line rule1, rule2。或者在诊断代码上方为每条规则堆叠一行注释。只要目标代码行与注释之间没有其他非 react-doctor-disable-next-line 的内容，堆叠的注释就会生效。

Lint plugin (standalone): The same rule set ships as both an oxlint plugin and an ESLint plugin, so you can wire it into whichever lint engine your project already runs. Lint 插件（独立版）：同一套规则集既作为 oxlint 插件也作为 ESLint 插件发布，因此你可以将其集成到项目中现有的任何 Lint 引擎中。

← 返回新闻列表 / Back to news list