React DevTools Standalone

7.0.1 · active · verified Sun Apr 19

The `react-devtools` package provides a standalone desktop application for debugging React applications that operate outside of conventional browser environments, such as React Native mobile apps, embedded webviews, or when debugging within browsers like Safari that lack direct extension support. This tool allows developers to inspect component hierarchies, monitor prop and state changes, and analyze rendering performance for any React-based UI. The current stable version for the standalone DevTools is 7.0.1, although related React ecosystem packages like `eslint-plugin-react-hooks` and the core React library (v19.x) receive more frequent updates. Its key differentiator is offering a consistent, dedicated debugging experience across various non-browser platforms where traditional browser DevTools extensions are not applicable or insufficient, connecting to the target application via a local server.

Common errors

```
Could not connect to React DevTools.
```
cause This error typically indicates that the standalone `react-devtools` application is not running, the client-side connection script is missing or misconfigured, or there is a network connectivity issue (e.g., port blocked, `adb reverse` not applied).

fix First, verify that `react-devtools` is actively running in your terminal. For web apps, ensure `<script src="http://localhost:8097"></script>` is the very first script in `<head>` or `import 'react-devtools';` is the first line in your entry file. For React Native, confirm `adb reverse tcp:8097 tcp:8097` has been executed if debugging on a physical device or remote emulator.
```
Failed to load resource: net::ERR_CONNECTION_REFUSED
```
cause When debugging a web application, this browser error means the client-side connection script tried to reach the DevTools server at `http://localhost:8097` but was refused, usually because the `react-devtools` command was not started or crashed.

fix Start the `react-devtools` application in your terminal. If it's already running, ensure no other process is blocking port 8097 or that your browser isn't configured with proxies preventing localhost access.
```
Module not found: Can't resolve 'react-devtools'
```
cause This error occurs in a build process (e.g., Webpack, Vite) when your application code uses `import 'react-devtools';` but the `react-devtools` package is not listed as a dependency in your project's `package.json`.

fix Install `react-devtools` as a development dependency: `npm install --save-dev react-devtools` or `yarn add --dev react-devtools`. If you prefer a global install, you'll need to use `npx react-devtools` to launch the tool and not rely on the `import` statement in your app code for connection.

Warnings

breaking React DevTools has compatibility requirements with the major version of React it is debugging (e.g., DevTools 7.x is designed for React 18/19). Using a significantly mismatched version can lead to connection failures, incorrect component introspection, or missing features.
Fix: Ensure your `react-devtools` package version aligns with the major version of `react` and `react-dom` used in your application. Consult the official React documentation or release notes for specific compatibility information.
gotcha The DevTools client connection script (either the `<script>` tag or `import 'react-devtools';`) is for development purposes only and *must* be removed from production builds. Leaving it in will unnecessarily increase your bundle size, potentially impact performance, and expose internal debugging capabilities.
Fix: Utilize build-time environment variables, conditional compilation, or Webpack configurations to ensure the DevTools client code is completely excluded from your production assets.
gotcha The standalone DevTools app listens on port 8097 by default. If another application is already using this port, or if network configurations (like firewalls or VPNs) prevent access, the DevTools will fail to connect. For React Native on physical devices, port forwarding is crucial.
Fix: Ensure port 8097 is free and accessible. On React Native, use `adb reverse tcp:8097 tcp:8097` for Android devices. If necessary, explore options to configure the DevTools to use an alternative port (though this is less common for the standalone app).
gotcha When `react-devtools` is connected to a React Native application, the in-app Inspector will enter a special collapsed mode, deferring UI inspection to the standalone DevTools GUI. This alters the expected behavior of the native Inspector.
Fix: To exclusively use the React Native in-app Inspector, ensure the `react-devtools` standalone application is not running or disconnect your app from it. The 'Hide Inspector' option in the in-app developer menu can also be used.

Install

npm install react-devtools npm
yarn add react-devtools yarn
pnpm add react-devtools pnpm

Imports

Standalone CLI Tool
wrong:
```
import { DevTools } from 'react-devtools'
```
correct:
```
react-devtools
```
The primary interaction is running the `react-devtools` command directly in your terminal to launch the GUI application.
Client Connection Script (ESM)
wrong:
```
const DevToolsClient = require('react-devtools');
```
correct:
```
import 'react-devtools';
```
This is a side-effect import that should be the very first import in your application's entry point (e.g., `index.js`) to establish a connection to the running standalone DevTools. It does not export any symbols for programmatic use.
Client Connection Script (HTML)
wrong:
```
<script type="module">import 'react-devtools';</script>
```
correct:
```
<script src="http://localhost:8097"></script>
```
For HTML-based applications (e.g., Safari, IFrames), embed this script tag as the very first script in the `<head>` section of your page to enable connection. This script *must* be removed before deploying to production.

Quickstart

Demonstrates global installation, launching the standalone DevTools app, and setting up client connections for React Native and web-based applications.

npm install -g react-devtools
react-devtools

// For React Native (0.43+) debugging, if not using a local simulator, 
// ensure port forwarding from device to host:
adb reverse tcp:8097 tcp:8097

// For web/iframe debugging, add this as the very first script in your HTML <head>:
// <script src="http://localhost:8097"></script>
// (Remember to remove this line for production builds!)

// Alternatively, if react-devtools is a project dependency:
npm install --save-dev react-devtools
npx react-devtools &
// In your application's main entry file (e.g., src/index.js), add as the first line:
// import 'react-devtools';
// (Also remove this import for production builds!)

view raw JSON →