0
# React DevTools
1

2
React DevTools is a standalone development tool that enables debugging of React applications outside of browser environments, particularly for React Native, mobile browsers, embedded webviews, and Safari. It provides a comprehensive debugging interface for inspecting React component hierarchies, props, state, and hooks, with features including component tree visualization, state modification capabilities, performance profiling, and integration with React Native Inspector.
3

4
## Package Information
5

6
- **Package Name**: react-devtools
7
- **Package Type**: npm
8
- **Language**: JavaScript (Flow typed)
9
- **Installation**: `npm install -g react-devtools` or `npx react-devtools`
10

11
## Core Imports
12

13
For programmatic usage via react-devtools-core:
14

15
```javascript
16
import { connectToDevTools, initialize } from "react-devtools-core/backend";
17
import DevtoolsUI from "react-devtools-core/standalone";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { connectToDevTools, initialize } = require("react-devtools-core/backend");
24
const DevtoolsUI = require("react-devtools-core/standalone");
25
```
26

27
## Basic Usage
28

29
### CLI Tool
30

31
```bash
32
# Launch standalone DevTools
33
react-devtools
34

35
# With project roots for editor integration
36
react-devtools /path/to/project
37

38
# React Native port forwarding
39
adb reverse tcp:8097 tcp:8097
40
```
41

42
### Programmatic Backend Integration
43

44
```javascript
45
import { connectToDevTools } from "react-devtools-core/backend";
46

47
// Basic connection
48
connectToDevTools();
49

50
// With custom options
51
connectToDevTools({
52
  host: "localhost",
53
  port: 8097,
54
  useHttps: false,
55
  retryConnectionDelay: 2000
56
});
57
```
58

59
### Standalone Server Setup
60

61
```javascript
62
import DevtoolsUI from "react-devtools-core/standalone";
63

64
// Start DevTools server
65
const server = DevtoolsUI.startServer(8097, "localhost");
66

67
// Setup UI rendering
68
DevtoolsUI
69
  .setContentDOMNode(document.getElementById("devtools"))
70
  .setStatusListener((message, status) => {
71
    console.log(`DevTools: ${message} (${status})`);
72
  });
73
```
74

75
## Architecture
76

77
React DevTools consists of several key components:
78

79
- **CLI Tool**: Electron-based desktop application providing the DevTools interface
80
- **Backend API**: Connection and initialization functions for React applications
81
- **Standalone Server**: WebSocket server and UI management for custom integrations
82
- **Editor Integration**: Source code navigation and "click to open in editor" functionality
83
- **Bridge System**: Communication layer between DevTools frontend and React applications
84
- **Component Inspection**: Deep inspection of React component trees, props, and state
85

86
## Capabilities
87

88
### CLI Tool
89

90
Command-line interface for launching the standalone DevTools application with Electron-based desktop interface.
91

92
```bash
93
react-devtools [project-roots...]
94
```
95

96
[CLI Tool](./cli-tool.md)
97

98
### Backend Integration
99

100
Functions for connecting React applications to the DevTools backend, enabling component inspection and debugging.
101

102
```javascript { .api }
103
function connectToDevTools(options?: ConnectOptions): void;
104
function initialize(
105
  settings?: DevToolsHookSettings | Promise<DevToolsHookSettings>,
106
  shouldStartProfilingNow?: boolean,
107
  profilingSettings?: ProfilingSettings
108
): void;
109

110
interface ConnectOptions {
111
  host?: string;
112
  port?: number;
113
  useHttps?: boolean;
114
  websocket?: WebSocket;
115
  retryConnectionDelay?: number;
116
  isAppActive?: () => boolean;
117
  nativeStyleEditorValidAttributes?: string[];
118
  resolveRNStyle?: (style: any) => any;
119
  onSettingsUpdated?: (settings: DevToolsHookSettings) => void;
120
  isReloadAndProfileSupported?: boolean;
121
  isProfiling?: boolean;
122
  onReloadAndProfile?: (recordChangeDescriptions: boolean) => void;
123
  onReloadAndProfileFlagsReset?: () => void;
124
}
125
```
126

127
[Backend Integration](./backend-integration.md)
128

129
### Standalone Server
130

131
Server and UI management functions for hosting DevTools in custom environments with full control over the interface.
132

133
```javascript { .api }
134
const DevtoolsUI: {
135
  startServer(
136
    port?: number,
137
    host?: string, 
138
    httpsOptions?: ServerOptions,
139
    loggerOptions?: LoggerOptions
140
  ): { close(): void };
141
  connectToSocket(socket: WebSocket): { close(): void };
142
  setContentDOMNode(node: HTMLElement): typeof DevtoolsUI;
143
  setProjectRoots(roots: string[]): void;
144
  setStatusListener(listener: StatusListener): typeof DevtoolsUI;
145
  setDisconnectedCallback(callback: () => void): typeof DevtoolsUI;
146
  openProfiler(): void;
147
};
148

149
type StatusTypes = "server-connected" | "devtools-connected" | "error";
150
type StatusListener = (message: string, status: StatusTypes) => void;
151

152
interface ServerOptions {
153
  key?: string;
154
  cert?: string;
155
}
156

157
interface LoggerOptions {
158
  surface?: string;
159
}
160
```
161

162
[Standalone Server](./standalone-server.md)
163

164
### Editor Integration
165

166
Utilities for integrating with code editors to enable "click to open in editor" functionality from DevTools.
167

168
```javascript { .api }
169
function doesFilePathExist(maybeRelativePath: string, absoluteProjectRoots: string[]): boolean;
170
function launchEditor(
171
  maybeRelativePath: string, 
172
  lineNumber: number, 
173
  absoluteProjectRoots: string[]
174
): void;
175
```
176

177
[Editor Integration](./editor-integration.md)
178

179
## Environment Variables
180

181
### REACT_DEVTOOLS_PORT
182

183
Overrides the default port (8097) for the DevTools server.
184

185
```bash
186
REACT_DEVTOOLS_PORT=9090 react-devtools
187
```
188

189
## Integration Patterns
190

191
### React Native Integration
192

193
React DevTools automatically connects to React Native applications when the server is running:
194

195
1. Start DevTools: `react-devtools`
196
2. Forward ports: `adb reverse tcp:8097 tcp:8097`
197
3. Launch React Native app - connection happens automatically
198

199
### React DOM Integration
200

201
For web applications, inject the DevTools script:
202

203
```html
204
<!-- Development only - remove before production -->
205
<script src="http://localhost:8097"></script>
206
```
207

208
Or programmatically:
209

210
```javascript
211
// Development only
212
import 'react-devtools';
213
```
214

215
### Custom Environment Integration
216

217
Use the standalone API for embedding DevTools in custom environments:
218

219
```javascript
220
import DevtoolsUI from "react-devtools-core/standalone";
221

222
// Setup custom DevTools hosting
223
const server = DevtoolsUI.startServer(8097);
224
DevtoolsUI.setContentDOMNode(customContainer);
225
```