react-devtools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-react-devtools

CLI that connects to a running React or React Native app via the React DevTools protocol and exposes the component tree, props, state, hooks, and profiling data in a token-efficient format.

一款通过React DevTools协议连接运行中的React或React Native应用的CLI工具，以高效的格式展示组件树、props、state、hooks以及性能分析数据。

Core Workflow

核心工作流程

Ensure connection — check
```
agent-react-devtools status
```
. If the daemon is not running, start it with
```
agent-react-devtools start
```
. Use
```
agent-react-devtools wait --connected
```
to block until a React app connects.
Inspect — get the component tree, search for components, inspect props/state/hooks.
Profile — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results.
Act — use the data to fix the bug, optimize performance, or explain what's happening.

确保连接 —— 执行
```
agent-react-devtools status
```
查看状态。如果守护进程未运行，使用
```
agent-react-devtools start
```
启动它。使用
```
agent-react-devtools wait --connected
```
等待，直到React应用连接成功。
检查组件 —— 获取组件树、搜索组件、查看props/state/hooks。
性能分析 —— 开始性能录制、触发交互（或让用户执行）、停止录制、分析结果。
问题修复 —— 利用获取的数据修复bug、优化性能，或解释问题原因。

Essential Commands

关键命令

Daemon

守护进程相关

bash

agent-react-devtools start              # Start daemon (auto-starts on first command)
agent-react-devtools stop               # Stop daemon
agent-react-devtools status             # Check connection, component count, last event
agent-react-devtools wait --connected   # Block until a React app connects
agent-react-devtools wait --component App # Block until a component appears

bash

agent-react-devtools start              # 启动守护进程（首次执行命令时会自动启动）
agent-react-devtools stop               # 停止守护进程
agent-react-devtools status             # 检查连接状态、组件数量、最后事件
agent-react-devtools wait --connected   # 等待直到React应用连接
agent-react-devtools wait --component App # 等待直到指定组件出现

Component Inspection

组件检查

bash

agent-react-devtools get tree           # Full component hierarchy (labels: @c1, @c2, ...)
agent-react-devtools get tree --depth 3 # Limit depth
agent-react-devtools get component @c5  # Props, state, hooks for a specific component
agent-react-devtools find Button        # Search by display name (fuzzy)
agent-react-devtools find Button --exact # Exact match
agent-react-devtools count              # Count by type: fn, cls, host, memo, ...

bash

agent-react-devtools get tree           # 获取完整组件层级（标签格式：@c1, @c2, ...）
agent-react-devtools get tree --depth 3 # 限制组件树深度
agent-react-devtools get component @c5  # 查看指定组件的props、state、hooks
agent-react-devtools find Button        # 按显示名称模糊搜索组件
agent-react-devtools find Button --exact # 按显示名称精确匹配
agent-react-devtools count              # 按组件类型统计数量：fn、cls、host、memo等

Performance Profiling

性能分析

bash

agent-react-devtools profile start              # Start recording
agent-react-devtools profile stop               # Stop and collect data
agent-react-devtools profile slow               # Slowest components by avg render time
agent-react-devtools profile slow --limit 10    # Top 10
agent-react-devtools profile rerenders          # Most re-rendered components
agent-react-devtools profile report @c5         # Detailed report for one component
agent-react-devtools profile timeline           # Chronological commit list
agent-react-devtools profile commit 3           # Detail for commit #3

bash

agent-react-devtools profile start              # 开始性能录制
agent-react-devtools profile stop               # 停止录制并收集数据
agent-react-devtools profile slow               # 按平均渲染时间排序，展示最慢的组件
agent-react-devtools profile slow --limit 10    # 展示前10个最慢组件
agent-react-devtools profile rerenders          # 展示重渲染次数最多的组件
agent-react-devtools profile report @c5         # 查看指定组件的详细性能报告
agent-react-devtools profile timeline           # 按时间顺序展示提交记录
agent-react-devtools profile commit 3           # 查看第3次提交的详细信息

Understanding the Output

输出内容说明

Component Labels

组件标签

Every component gets a stable label like

@c1

@c2

. Use these to reference components in follow-up commands:

@c1 [fn] App
├─ @c2 [fn] Header
├─ @c3 [fn] TodoList
│  ├─ @c4 [fn] TodoItem key=1
│  └─ @c5 [fn] TodoItem key=2
└─ @c6 [host] div

Type abbreviations:

fn

= function,

cls

= class,

host

= DOM element,

memo

= React.memo,

fRef

= forwardRef,

susp

= Suspense,

ctx

= context.

每个组件会分配一个稳定的标签，例如

@c1

、

@c2

。后续命令中可通过这些标签引用组件：

@c1 [fn] App
├─ @c2 [fn] Header
├─ @c3 [fn] TodoList
│  ├─ @c4 [fn] TodoItem key=1
│  └─ @c5 [fn] TodoItem key=2
└─ @c6 [host] div

类型缩写说明：

fn

= 函数组件，

cls

= 类组件，

host

= DOM元素，

memo

= React.memo，

fRef

= forwardRef，

susp

= Suspense，

ctx

= context。

Inspected Component

组件详情

@c3 [fn] TodoList
props:
  items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
  onDelete: ƒ
state:
  filter: "all"
hooks:
  useState: "all"
  useMemo: [...]
  useCallback: ƒ

ƒ

= function value. Values over 60 chars are truncated.

@c3 [fn] TodoList
props:
  items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
  onDelete: ƒ
state:
  filter: "all"
hooks:
  useState: "all"
  useMemo: [...]
  useCallback: ƒ

ƒ

代表函数类型。超过60字符的值会被截断。

Profiling Output

性能分析输出

Slowest (by avg render time):
  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed
  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed

Render causes:

props-changed

state-changed

hooks-changed

parent-rendered

force-update

first-mount

最慢组件（按平均渲染时间排序）：
  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed
  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed

重渲染原因：

props-changed

（props变更）、

state-changed

（state变更）、

hooks-changed

（hooks变更）、

parent-rendered

（父组件渲染）、

force-update

（强制更新）、

first-mount

（首次挂载）。

Common Patterns

常见使用场景

Wait for the app to connect after a reload

页面刷新后等待应用连接

bash

agent-react-devtools wait --connected --timeout 10
agent-react-devtools get tree

Use this after triggering a page reload or HMR update to avoid querying empty state.

bash

agent-react-devtools wait --connected --timeout 10
agent-react-devtools get tree

触发页面刷新或HMR更新后，可使用该命令避免查询空状态。

Diagnose slow interactions

诊断交互卡顿问题

bash

agent-react-devtools profile start

bash

agent-react-devtools profile start

User interacts with the app (or use agent-browser to drive the UI)

用户操作应用（或使用agent-browser驱动UI）

agent-react-devtools profile stop agent-react-devtools profile slow --limit 5 agent-react-devtools profile rerenders --limit 5


Then inspect the worst offenders with `get component @cN` and `profile report @cN`.

agent-react-devtools profile stop agent-react-devtools profile slow --limit 5 agent-react-devtools profile rerenders --limit 5


之后使用`get component @cN`和`profile report @cN`查看问题组件的详情。

Find a component and check its state

查找组件并检查状态

bash

agent-react-devtools find SearchBar
agent-react-devtools get component @c12

bash

agent-react-devtools find SearchBar
agent-react-devtools get component @c12

Verify a fix worked

验证修复效果

bash

agent-react-devtools profile start

bash

agent-react-devtools profile start

Repeat the interaction

重复之前的交互操作

agent-react-devtools profile stop agent-react-devtools profile slow --limit 5

Compare render counts and durations to the previous run

对比本次与之前的渲染次数和耗时

undefined

undefined

Using with agent-browser

与agent-browser配合使用

When using

agent-browser

to drive the app while profiling or debugging, you must use headed mode (

--headed

). Headless Chromium does not execute ES module scripts the same way as a real browser, which prevents the devtools connect script from running properly.

bash

agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # Should show 1 connected app

当使用

agent-browser

驱动应用进行性能分析或调试时，必须使用有头模式（

--headed

）。无头Chromium的ES模块脚本执行逻辑与真实浏览器不同，会导致调试工具连接脚本无法正常运行。

bash

agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # 应显示已连接1个应用

Important Rules

重要注意事项

Labels reset when the app reloads or components unmount/remount. After a reload, use
```
wait --connected
```
then re-check with
```
get tree
```
or
```
find
```
.
status
first — if status shows 0 connected apps, the React app is not connected. The user may need to run
```
npx agent-react-devtools init
```
in their project first.
Headed browser required — if using
```
agent-browser
```
, always use
```
--headed
```
mode. Headless Chromium does not properly load the devtools connect script.
Profile while interacting — profiling only captures renders that happen between
```
profile start
```
and
```
profile stop
```
. Make sure the relevant interaction happens during that window.
Use
--depth
on large trees — a deep tree can produce a lot of output. Start with
```
--depth 3
```
or
```
--depth 4
```
and go deeper only on the subtree you care about.

标签会重置：当应用刷新或组件卸载/重新挂载时，组件标签会重置。刷新后请先使用
```
wait --connected
```
，再通过
```
get tree
```
或
```
find
```
重新获取组件标签。
先查状态：如果
```
status
```
显示0个已连接应用，说明React应用未连接。用户可能需要先在项目中执行
```
npx agent-react-devtools init
```
。
必须使用有头浏览器：配合
```
agent-browser
```
使用时，务必开启
```
--headed
```
模式。无头Chromium无法正确加载调试工具连接脚本。
录制期间触发交互：性能分析仅捕获
```
profile start
```
和
```
profile stop
```
之间的渲染操作。请确保相关交互在该时间段内执行。
限制组件树深度：大型组件树会产生大量输出。建议先使用
```
--depth 3
```
或
```
--depth 4
```
，再按需查看子树详情。

References

参考文档

File	When to read
commands.md	Full command reference with all flags and edge cases
profiling-guide.md	Step-by-step profiling workflows and interpreting results
setup.md	How to connect different frameworks (Vite, Next.js, Expo, CRA)

文件	适用场景
commands.md	完整命令参考，包含所有参数和边缘情况
profiling-guide.md	分步性能分析流程及结果解读
setup.md	不同框架的连接方法（Vite、Next.js、Expo、CRA）