agent-react-devtools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-react-devtools

Skill by ara.so — Devtools Skills collection.

agent-react-devtools

is a command-line interface to React DevTools that lets AI agents inspect running React applications. It provides programmatic access to component trees, props, state, hooks, and rendering performance data through a persistent background daemon.

由ara.so开发的Skill——Devtools Skills合集。

agent-react-devtools

是React DevTools的命令行界面，可让AI Agent检查运行中的React应用。它通过持久化后台守护进程提供对组件树、props、state、hooks以及渲染性能数据的程序化访问。

Installation

安装

Install globally:

bash

npm install -g agent-react-devtools

Or use directly with npx:

bash

npx agent-react-devtools start

全局安装：

bash

npm install -g agent-react-devtools

或直接使用npx：

bash

npx agent-react-devtools start

Core Concepts

核心概念

Daemon: A persistent background process (default port 8097) that maintains connection state
Component IDs: Components are labeled
```
@c1
```
,
```
@c2
```
, etc. for easy reference
Host Filtering: HTML elements (
```
<div>
```
,
```
<span>
```
) are filtered by default to keep output compact
LLM-Optimized: Output is token-efficient and structured for AI consumption

守护进程（Daemon）：持久化后台进程（默认端口8097），用于维护连接状态
组件ID（Component IDs）：组件标记为
```
@c1
```
、
```
@c2
```
等，便于引用
宿主过滤（Host Filtering）：默认过滤HTML元素（
```
<div>
```
、
```
<span>
```
），保持输出简洁
LLM优化：输出兼顾token效率，且结构适配AI读取

Connecting Your React App

连接你的React应用

Quick Setup (Recommended)

快速设置（推荐）

Auto-configure your project:

bash

npx agent-react-devtools init

This detects your framework (Vite, Next.js, CRA) and patches the config automatically.

To undo:

bash

npx agent-react-devtools uninit

自动配置项目：

bash

npx agent-react-devtools init

此命令会检测你的框架（Vite、Next.js、CRA）并自动修改配置。

撤销配置：

bash

npx agent-react-devtools uninit

Manual Setup - One-Line Import

手动设置——单行导入

Add to your entry point (e.g.,

src/main.tsx

typescript

import "agent-react-devtools/connect";

Place this as the first import in your app entry point.

添加到入口文件（如

src/main.tsx

）：

typescript

import "agent-react-devtools/connect";

请将此导入放在应用入口文件的第一行。

Manual Setup - Vite Plugin

手动设置——Vite插件

For Vite projects, use the plugin (no app code changes needed):

typescript

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { reactDevtools } from "agent-react-devtools/vite";

export default defineConfig({
  plugins: [
    reactDevtools(), // Must come before react()
    react()
  ],
});

With custom port:

typescript

reactDevtools({ port: 8097, host: "localhost" })

对于Vite项目，使用插件（无需修改应用代码）：

typescript

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { reactDevtools } from "agent-react-devtools/vite";

export default defineConfig({
  plugins: [
    reactDevtools(), // 必须在react()之前
    react()
  ],
});

自定义端口：

typescript

reactDevtools({ port: 8097, host: "localhost" })

React Native Setup

React Native设置

React Native connects automatically:

bash

agent-react-devtools start
npx react-native start

For physical devices, forward the port:

bash

adb reverse tcp:8097 tcp:8097

React Native可自动连接：

bash

agent-react-devtools start
npx react-native start

对于物理设备，需转发端口：

bash

adb reverse tcp:8097 tcp:8097

Key Commands

核心命令

Daemon Management

守护进程管理

Start the daemon (required first step):

bash

agent-react-devtools start

With custom port:

bash

agent-react-devtools start --port 8097

Check status:

bash

agent-react-devtools status

Stop daemon:

bash

agent-react-devtools stop

启动守护进程（第一步必需）：

bash

agent-react-devtools start

自定义端口：

bash

agent-react-devtools start --port 8097

检查状态：

bash

agent-react-devtools status

停止守护进程：

bash

agent-react-devtools stop

Component Inspection

组件检查

Get full component tree:

bash

agent-react-devtools get tree

Limit tree depth:

bash

agent-react-devtools get tree --depth 3

Include host components (div, span, etc.):

bash

agent-react-devtools get tree --all

Get subtree from specific component:

bash

agent-react-devtools get tree @c5

Inspect component details:

bash

agent-react-devtools get component @c6

Output shows props, state, and hooks:

@c6 [fn] TodoItem key=1
props:
  id: 1
  text: "Buy groceries"
  done: false
  onToggle: ƒ
hooks:
  State: false
  Callback: ƒ

Search for components by name:

bash

agent-react-devtools find TodoItem

Exact name match:

bash

agent-react-devtools find App --exact

Count components by type:

bash

agent-react-devtools count

List components with errors/warnings:

bash

agent-react-devtools errors

获取完整组件树：

bash

agent-react-devtools get tree

限制树深度：

bash

agent-react-devtools get tree --depth 3

包含宿主组件（div、span等）：

bash

agent-react-devtools get tree --all

获取指定组件的子树：

bash

agent-react-devtools get tree @c5

检查组件详情：

bash

agent-react-devtools get component @c6

输出包含props、state和hooks：

@c6 [fn] TodoItem key=1
props:
  id: 1
  text: "Buy groceries"
  done: false
  onToggle: ƒ
hooks:
  State: false
  Callback: ƒ

按名称搜索组件：

bash

agent-react-devtools find TodoItem

精确匹配名称：

bash

agent-react-devtools find App --exact

按类型统计组件数量：

bash

agent-react-devtools count

列出带有错误/警告的组件：

bash

agent-react-devtools errors

Wait Commands (Useful in Scripts)

等待命令（脚本中实用）

Wait for app connection:

bash

agent-react-devtools wait --connected --timeout 30

Wait for specific component:

bash

agent-react-devtools wait --component App --timeout 30

These exit with code 0 on success, code 1 on timeout.

等待应用连接：

bash

agent-react-devtools wait --connected --timeout 30

等待指定组件：

bash

agent-react-devtools wait --component App --timeout 30

成功时退出码为0，超时则为1。

Performance Profiling

性能分析

Start profiling session:

bash

agent-react-devtools profile start

With named session:

bash

agent-react-devtools profile start "user-interaction-test"

Stop profiling:

bash

agent-react-devtools profile stop

Find slowest components:

bash

agent-react-devtools profile slow

Limit results:

bash

agent-react-devtools profile slow --limit 5

Find components that re-render most:

bash

agent-react-devtools profile rerenders

View commit timeline:

bash

agent-react-devtools profile timeline

Inspect specific commit:

bash

agent-react-devtools profile commit 3

Or use commit label:

bash

agent-react-devtools profile commit #3

Get render report for specific component:

bash

agent-react-devtools profile report @c5

Export profiling data:

bash

agent-react-devtools profile export results.json

Compare two profile exports:

bash

agent-react-devtools profile diff before.json after.json

With threshold filter:

bash

agent-react-devtools profile diff before.json after.json --threshold 2.0

启动分析会话：

bash

agent-react-devtools profile start

命名会话：

bash

agent-react-devtools profile start "user-interaction-test"

停止分析：

bash

agent-react-devtools profile stop

查找最慢组件：

bash

agent-react-devtools profile slow

限制结果数量：

bash

agent-react-devtools profile slow --limit 5

查找重渲染最频繁的组件：

bash

agent-react-devtools profile rerenders

查看提交时间线：

bash

agent-react-devtools profile timeline

检查指定提交：

bash

agent-react-devtools profile commit 3

或使用提交标签：

bash

agent-react-devtools profile commit #3

获取指定组件的渲染报告：

bash

agent-react-devtools profile report @c5

导出分析数据：

bash

agent-react-devtools profile export results.json

对比两份分析导出文件：

bash

agent-react-devtools profile diff before.json after.json

设置阈值过滤：

bash

agent-react-devtools profile diff before.json after.json --threshold 2.0

Common Workflows

常见工作流

Debugging Component Issues

调试组件问题

Start daemon and connect app:

bash

agent-react-devtools start

启动守护进程并连接应用：

bash

agent-react-devtools start

Run your app (it should auto-connect)

运行你的应用（会自动连接）

agent-react-devtools status


2. Find the problematic component:

```bash
agent-react-devtools find UserProfile

Inspect its state and props:

bash

agent-react-devtools get component @c12

Check surrounding context:

bash

agent-react-devtools get tree @c12 --depth 2

agent-react-devtools status


2. 找到有问题的组件：

```bash
agent-react-devtools find UserProfile

检查其state和props：

bash

agent-react-devtools get component @c12

查看周边上下文：

bash

agent-react-devtools get tree @c12 --depth 2

Performance Investigation

性能排查

Start profiling before interaction:

bash

agent-react-devtools profile start "search-performance"

Perform the interaction in your app
Stop and analyze:

bash

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

Investigate specific component:

bash

agent-react-devtools profile report @c8

在交互前启动分析：

bash

agent-react-devtools profile start "search-performance"

在应用中执行交互操作
停止并分析：

bash

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

排查特定组件：

bash

agent-react-devtools profile report @c8

Automated Testing/Monitoring

自动化测试/监控

Script example for CI or monitoring:

bash

#!/bin/bash
agent-react-devtools start
agent-react-devtools wait --connected --timeout 30 || exit 1

适用于CI或监控的脚本示例：

bash

#!/bin/bash
agent-react-devtools start
agent-react-devtools wait --connected --timeout 30 || exit 1

Check for components with errors

检查是否有组件存在错误

if agent-react-devtools errors | grep -q "@c"; then echo "Components have errors!" agent-react-devtools errors exit 1 fi

if agent-react-devtools errors | grep -q "@c"; then echo "组件存在错误！" agent-react-devtools errors exit 1 fi

Profile a workflow

分析工作流

agent-react-devtools profile start "ci-test"

... trigger app interactions ...

... 触发应用交互 ...

agent-react-devtools profile stop agent-react-devtools profile export ci-results.json

Check for slow components

检查是否有慢组件

SLOW_COUNT=$(agent-react-devtools profile slow --limit 5 | grep -c "avg:") if [ "$SLOW_COUNT" -gt 3 ]; then echo "Too many slow components detected" agent-react-devtools profile slow exit 1 fi

undefined

SLOW_COUNT=$(agent-react-devtools profile slow --limit 5 | grep -c "avg:") if [ "$SLOW_COUNT" -gt 3 ]; then echo "检测到过多慢组件" agent-react-devtools profile slow exit 1 fi

undefined

Using with agent-browser

与agent-browser结合使用

When combining with

agent-browser

for automated interactions:

bash

undefined

与

agent-browser

结合实现自动化交互时：

bash

undefined

IMPORTANT: Must use --headed mode

重要提示：必须使用--headed模式

agent-browser --session devtools --headed open http://localhost:5173/ agent-react-devtools status # Verify connection agent-react-devtools profile start

agent-browser --session devtools --headed open http://localhost:5173/ agent-react-devtools status # 验证连接 agent-react-devtools profile start

... agent-browser interactions ...

... agent-browser交互操作 ...

agent-react-devtools profile stop agent-react-devtools profile slow


**Note**: Headless mode does NOT work - the DevTools connection requires a headed browser.

agent-react-devtools profile stop agent-react-devtools profile slow


**注意**：无头模式无法工作——DevTools连接需要有头浏览器。

Configuration

配置

Environment Variables

环境变量

```
REACT_DEVTOOLS_PORT
```
- Custom port for React Native apps

```
REACT_DEVTOOLS_PORT
```
- React Native应用的自定义端口

Default Port

默认端口

The daemon uses port 8097 by default. Override with:

bash

agent-react-devtools start --port 9000

Then configure your app connection to match.

守护进程默认使用8097端口。可通过以下命令覆盖：

bash

agent-react-devtools start --port 9000

然后配置应用连接以匹配该端口。

Troubleshooting

故障排除

App Not Connecting

应用无法连接

Check daemon status:

bash

agent-react-devtools status

Verify app is in development mode:

The connection only works in dev builds, not production

Check console for connection errors:

Look for WebSocket connection messages in browser console

Restart daemon:

bash

agent-react-devtools stop
agent-react-devtools start

检查守护进程状态：

bash

agent-react-devtools status

验证应用处于开发模式：

仅开发构建支持连接，生产构建不支持

检查控制台的连接错误：

在浏览器控制台中查找WebSocket连接相关消息

重启守护进程：

bash

agent-react-devtools stop
agent-react-devtools start

"No apps connected" After Init

执行Init后显示“No apps connected”

Verify import order:

The connect import must be the first import in your entry file

Check Vite plugin order:

```
reactDevtools()
```
must come before
```
react()
```
in plugins array

Verify dev server is running:

The app must be actively running, not just built

验证导入顺序：

connect导入必须放在入口文件的第一行

检查Vite插件顺序：

```
reactDevtools()
```
必须在plugins数组中
```
react()
```
之前

验证开发服务器正在运行：

应用必须处于活跃运行状态，不能仅完成构建

Empty Component Tree

组件树为空

Remove host component filtering:

bash

agent-react-devtools get tree --all

Check if app rendered:

bash

agent-react-devtools count

取消宿主组件过滤：

bash

agent-react-devtools get tree --all

检查应用是否已渲染：

bash

agent-react-devtools count

Profile Commands Return No Data

分析命令无返回数据

Ensure you stopped profiling:

bash

agent-react-devtools profile stop

Data is only collected after stopping the profile session.

确保已停止分析：

bash

agent-react-devtools profile stop

只有停止分析会话后才会收集数据。

Timeout Waiting for Connection

等待连接超时

Increase timeout:

bash

agent-react-devtools wait --connected --timeout 60

Check if port is blocked:

bash

lsof -i :8097

增加超时时间：

bash

agent-react-devtools wait --connected --timeout 60

检查端口是否被占用：

bash

lsof -i :8097

Output Format Notes

输出格式说明

Component IDs (
```
@c1
```
,
```
@c2
```
) are persistent within a daemon session
Error annotations:
```
⚠
```
for warnings,
```
✗
```
for errors
Function indicators:
```
ƒ
```
marks function props/callbacks
Tree symbols:
```
├─
```
for middle children,
```
└─
```
for last child
Collapsed indicators:
```
... +N more
```
when output is truncated

组件ID（
```
@c1
```
、
```
@c2
```
）在守护进程会话中保持持久
错误标注：
```
⚠
```
表示警告，
```
✗
```
表示错误
函数标识：
```
ƒ
```
标记函数类型的props/回调
树状符号：
```
├─
```
表示中间子节点，
```
└─
```
表示最后一个子节点
折叠标识：输出被截断时显示
```
... +N more
```

Integration with AI Assistants

与AI助手集成

Add to your project's

AGENTS.md

.cursorrules

markdown

undefined

添加到项目的

AGENTS.md

或

.cursorrules

中：

markdown

undefined

React Component Inspection

React组件检查

Use

agent-react-devtools

to inspect the running React app:

Start daemon:
```
agent-react-devtools start
```
Check connection:
```
agent-react-devtools status
```
Browse tree:
```
agent-react-devtools get tree --depth 3
```
Inspect component:
```
agent-react-devtools get component @cN
```

Profile performance:

agent-react-devtools profile start

→ interact →

profile stop

→

profile slow

Always check

status

before other commands to ensure app is connected.

undefined

使用

agent-react-devtools

检查运行中的React应用：

启动守护进程：
```
agent-react-devtools start
```
检查连接状态：
```
agent-react-devtools status
```
浏览组件树：
```
agent-react-devtools get tree --depth 3
```
检查组件详情：
```
agent-react-devtools get component @cN
```

性能分析：

agent-react-devtools profile start

→ 执行交互 →

profile stop

→

profile slow

执行其他命令前，请务必先检查

status

确保应用已连接。

undefined

License

许可证

MIT