DOCSEARCHbyAlgolia
Submit Docs

agent-react-devtools

repository·main·Indexed 42 days ago

https://github.com/callstackincubator/agent-react-devtools

A developer tool and CLI that provides AI agents with the ability to inspect React component trees, read props and state, and profile rendering performance. It supports web applications (via Vite, Next.js, or CRA) and React Native/Expo projects. Key features include component tree navigation, searching for components by name, performance profiling to identify slow components and excessive re-renders, and integration skills for AI coding assistants like Claude Code, Cursor, and GitHub Copilot.

Tokens
18.1K
Snippets
68
Records
81
Agent score
52%

What's inside agent-react-devtools

  1. Understand Component Labels and Output Formats

    main

    The CLI uses specific notation to represent the React tree and component metadata.

    Component Labels

    Every component is assigned a stable label (e.g., @c1, @c2). Use these labels to target components in subsequent commands.

    Type Abbreviations

    In the tree output, component types are indicated by:

    • fn: Function component
    • cls: Class component
    • host: DOM element (e.g., div)
    • memo: React.memo component
    • fRef: forwardRef component
    • susp: Suspense component
    • ctx: Context provider

    Error Annotations

    • ⚠<N>: Indicates <N> warnings.
    • ✗<N>: Indicates <N> errors.

    Inspected Component Data

    When running get component <Label>, the output includes:

    • props: Current properties passed to the component.
    • state: Current component state.
    • hooks: Current values of hooks (e.g., useState, useMemo).
    • ƒ: Represents a function value.

    Profiling Render Causes

    Profiling output identifies why a component re-rendered using these causes:

    • props-changed: A prop value changed.
    • state-changed: Local state changed.
    • hooks-changed: A hook value changed.
    • parent-rendered: The parent component re-rendered.
    • force-update: A manual force update was triggered.
    • first-mount: The component was mounted for the first time.

  2. Profile React rendering performance

    main

    The profiling suite allows you to identify slow components and excessive re-renders.

    1. Start a session: profile start [name]
    2. Perform actions: Interact with your app.
    3. Stop session: profile stop to collect data.
    4. Analyze results:
      • profile slow: Shows slowest components by average render time.
      • profile rerenders: Shows components with the most re-renders.
      • profile timeline: Shows the commit timeline.
      • profile report <id>: Shows a detailed render report for a specific component.
      • profile export <file>: Exports data as a React DevTools Profiler JSON.
      • profile diff <file1> <file2>: Compares two exported JSON files.
    agent-react-devtools profile start
# ... interact with the app ...
agent-react-devtools profile stop
agent-react-devtools profile slow

  3. Initialize agent-react-devtools in a project

    main

    The init command automates the setup for supported frameworks including Vite, Next.js, CRA, and standard Expo/React Native projects.

    For React Native, it patches Metro configs and adds the necessary native bootstrap import to a reachable app module.

    Note: ESM, TypeScript, JSON, or package-field Metro configs, custom --config usage, and ambiguous targets require manual setup.

    Use --dry-run to see what changes would be made without actually writing to disk.

    # Preview changes for a React Native project
agent-react-devtools init --dry-run

# Apply configuration automatically
agent-react-devtools init

  4. Add agent-react-devtools skills to AI Coding Assistants

    main

    You can provide richer context to your AI coding assistant by adding the agent-react-devtools skill. This allows assistants like Claude Code, Cursor, or GitHub Copilot to use the tool's capabilities to inspect your React application.

    Use the following command to add the skill:

    npx skills add callstackincubator/agent-react-devtools

    Supported assistants include:

    • Claude Code
    • Codex
    • Cursor
    • Gemini CLI
    • GitHub Copilot
    • Goose
    • OpenCode
    • Windsurf

  5. Using agent-react-devtools with agent-browser

    main

    When automating a browser with agent-browser, you must use headed mode (--headed). Headless Chromium handles ES module script execution in a way that prevents the devtools connect script from installing the hook before React loads.

    # Headed mode is required for devtools to connect
agent-browser --session devtools --headed open http://localhost:5173/

# Verify connection
agent-react-devtools status

  6. Test the DevTools Connection in an Expo Project

    main

    To exercise a live connection in an Expo project, you must ensure two integration points are present:

    1. metro.config.js must apply withAgentReactDevTools to the Metro config.
    2. app/_layout.tsx (or your entry point) must import agent-react-devtools/react-native to include the bootstrap in the dependency graph.

    To run a full connection test, follow these steps in separate terminals:

    1. Start the daemon: Run the devtools daemon.
    2. Start the Expo server: Start the Expo dev server with a cleared cache.
    3. Inspect the app: Use the CLI to check status, wait for connection, and retrieve the component tree.
    # Terminal 1: Start the daemon
agent-react-devtools start

# Terminal 2: Start the Expo dev server
cd examples/expo-app
bun start --clear

# Terminal 3: Inspect the app
agent-react-devtools status
agent-react-devtools wait --connected --timeout 30
agent-react-devtools get tree

  7. Configure agent-react-devtools for React Native and Expo

    main

    React Native and Expo require two mandatory steps: wrapping the Metro configuration and importing the bootstrap module in the application entry graph.

    Note: withAgentReactDevTools must be the outermost wrapper around your final Metro config to ensure existing serializer hooks are retained.

    1. Install the package:
    npm install --save-dev agent-react-devtools
    1. Wrap Metro Config:

    For Bare React Native:

    // metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withAgentReactDevTools } = require('agent-react-devtools/metro');

const projectConfig = {};
const config = mergeConfig(getDefaultConfig(__dirname), projectConfig);

module.exports = withAgentReactDevTools(config);

    For Expo:

    // metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withAgentReactDevTools } = require('agent-react-devtools/metro');

const config = getDefaultConfig(__dirname);

module.exports = withAgentReactDevTools(config);
    1. Import Bootstrap in Entry Graph: Import the bootstrap module in your application entry point (e.g., index.js or Expo Router's root layout) to ensure it executes after React Native initialization but before application modules.
    import 'agent-react-devtools/react-native';

    Remember to restart Metro after changing metro.config.js.

  9. Identify slow components and frequent re-renders

    main

    Once a profiling session is stopped, use these commands to find performance bottlenecks:

    • Slowest components: Identifies components that take the most time per render.
    • Most re-rendered: Identifies components that render too frequently.

    Note that a component can be a problem in two ways: high total time due to slow individual renders, or high total time due to a high volume of fast renders.

    # Find slowest components
agent-react-devtools profile slow --limit 5

# Find most frequent re-renders
agent-react-devtools profile rerenders --limit 5

  11. Auto-configure agent-react-devtools with 'init'

    main

    The init command automatically configures supported web frameworks (Vite, Next.js, Create React App) and React Native/Expo projects. It detects your framework and applies the minimal configuration required to enable the devtools connection.

    To preview changes without modifying files, use the --dry-run flag.

    # Run auto-configuration
cd your-react-app
npx agent-react-devtools init

# Preview changes without applying them
npx agent-react-devtools init --dry-run