0
# Standalone Server
1

2
Server and UI management functions for hosting DevTools in custom environments with full control over the interface, WebSocket connections, and rendering.
3

4
## Capabilities
5

6
### DevTools UI Object
7

8
Main API object for managing standalone DevTools server and UI.
9

10
```javascript { .api }
11
const DevtoolsUI: {
12
  startServer: (port?: number, host?: string, httpsOptions?: ServerOptions, loggerOptions?: LoggerOptions) => ServerControl;
13
  connectToSocket: (socket: WebSocket) => ConnectionControl;
14
  setContentDOMNode: (node: HTMLElement) => typeof DevtoolsUI;
15
  setProjectRoots: (roots: string[]) => void;
16
  setStatusListener: (listener: StatusListener) => typeof DevtoolsUI;
17
  setDisconnectedCallback: (callback: OnDisconnectedCallback) => typeof DevtoolsUI;
18
  openProfiler: () => void;
19
};
20

21
interface ServerControl {
22
  close(): void;
23
}
24

25
interface ConnectionControl {
26
  close(): void;
27
}
28
```
29

30
### Start DevTools Server
31

32
Creates and starts a WebSocket server for DevTools connections.
33

34
```javascript { .api }
35
/**
36
 * Starts a WebSocket server for DevTools connections
37
 * @param port - Server port (default: 8097)
38
 * @param host - Server host (default: 'localhost')
39
 * @param httpsOptions - HTTPS configuration for secure connections
40
 * @param loggerOptions - Logging configuration
41
 * @returns Server control object with close method
42
 */
43
function startServer(
44
  port?: number,
45
  host?: string,
46
  httpsOptions?: ServerOptions,
47
  loggerOptions?: LoggerOptions
48
): { close(): void };
49

50
interface ServerOptions {
51
  /** HTTPS private key */
52
  key?: string;
53
  /** HTTPS certificate */
54
  cert?: string;
55
}
56

57
interface LoggerOptions {
58
  /** Logging surface identifier */
59
  surface?: string;
60
}
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
import DevtoolsUI from "react-devtools-core/standalone";
67

68
// Basic server startup
69
const server = DevtoolsUI.startServer();
70

71
// Custom port and host
72
const server = DevtoolsUI.startServer(9090, '0.0.0.0');
73

74
// HTTPS server
75
const server = DevtoolsUI.startServer(8097, 'localhost', {
76
  key: fs.readFileSync('path/to/private-key.pem'),
77
  cert: fs.readFileSync('path/to/certificate.pem')
78
});
79

80
// With logging configuration
81
const server = DevtoolsUI.startServer(8097, 'localhost', null, {
82
  surface: 'custom-integration'
83
});
84

85
// Shutdown server
86
server.close();
87
```
88

89
### Connect to WebSocket
90

91
Connects DevTools UI to an existing WebSocket connection.
92

93
```javascript { .api }
94
/**
95
 * Connects DevTools UI to an existing WebSocket
96
 * @param socket - WebSocket connection to use
97
 * @returns Connection control object with close method
98
 */
99
function connectToSocket(socket: WebSocket): { close(): void };
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
import DevtoolsUI from "react-devtools-core/standalone";
106

107
// Connect to existing WebSocket
108
const ws = new WebSocket('ws://localhost:8097');
109
const connection = DevtoolsUI.connectToSocket(ws);
110

111
// Handle connection events
112
ws.onopen = () => console.log('Connected to DevTools');
113
ws.onerror = (error) => console.error('Connection error:', error);
114

115
// Close connection
116
connection.close();
117
```
118

119
### Set Content DOM Node
120

121
Sets the DOM element where DevTools UI will be rendered.
122

123
```javascript { .api }
124
/**
125
 * Sets the DOM node where DevTools UI will be rendered
126
 * @param node - HTML element to render DevTools into
127
 * @returns DevtoolsUI object for method chaining
128
 */
129
function setContentDOMNode(node: HTMLElement): typeof DevtoolsUI;
130
```
131

132
**Usage Examples:**
133

134
```javascript
135
import DevtoolsUI from "react-devtools-core/standalone";
136

137
// Set render target
138
const container = document.getElementById('devtools-container');
139
DevtoolsUI.setContentDOMNode(container);
140

141
// Method chaining
142
DevtoolsUI
143
  .setContentDOMNode(document.getElementById('devtools'))
144
  .setStatusListener((message, status) => {
145
    console.log(`Status: ${message} (${status})`);
146
  });
147
```
148

149
### Set Project Roots
150

151
Configures project root directories for editor integration.
152

153
```javascript { .api }
154
/**
155
 * Sets project root paths for editor integration
156
 * @param roots - Array of absolute directory paths
157
 */
158
function setProjectRoots(roots: string[]): void;
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
import DevtoolsUI from "react-devtools-core/standalone";
165

166
// Single project root
167
DevtoolsUI.setProjectRoots(['/path/to/project']);
168

169
// Multiple project roots for monorepos
170
DevtoolsUI.setProjectRoots([
171
  '/path/to/frontend',
172
  '/path/to/backend',
173
  '/path/to/shared'
174
]);
175

176
// Empty array to disable editor integration
177
DevtoolsUI.setProjectRoots([]);
178
```
179

180
### Set Status Listener
181

182
Sets a callback for DevTools status updates and connection events.
183

184
```javascript { .api }
185
/**
186
 * Sets a callback for DevTools status updates
187
 * @param listener - Status update callback function
188
 * @returns DevtoolsUI object for method chaining
189
 */
190
function setStatusListener(listener: StatusListener): typeof DevtoolsUI;
191

192
type StatusListener = (message: string, status: StatusTypes) => void;
193
type StatusTypes = "server-connected" | "devtools-connected" | "error";
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
import DevtoolsUI from "react-devtools-core/standalone";
200

201
// Basic status logging
202
DevtoolsUI.setStatusListener((message, status) => {
203
  console.log(`DevTools: ${message} (${status})`);
204
});
205

206
// Advanced status handling
207
DevtoolsUI.setStatusListener((message, status) => {
208
  switch (status) {
209
    case 'server-connected':
210
      document.getElementById('status').textContent = 'Server Ready';
211
      document.getElementById('status').className = 'status-success';
212
      break;
213
    case 'devtools-connected':
214
      document.getElementById('status').textContent = 'DevTools Connected';
215
      document.getElementById('status').className = 'status-connected';
216
      break;
217
    case 'error':
218
      document.getElementById('status').textContent = `Error: ${message}`;
219
      document.getElementById('status').className = 'status-error';
220
      break;
221
  }
222
});
223
```
224

225
### Set Disconnected Callback
226

227
Sets a callback for when DevTools disconnects from the target application.
228

229
```javascript { .api }
230
/**
231
 * Sets a callback for when DevTools disconnects
232
 * @param callback - Disconnection callback function
233
 * @returns DevtoolsUI object for method chaining
234
 */
235
function setDisconnectedCallback(callback: OnDisconnectedCallback): typeof DevtoolsUI;
236

237
type OnDisconnectedCallback = () => void;
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
import DevtoolsUI from "react-devtools-core/standalone";
244

245
// Handle disconnection
246
DevtoolsUI.setDisconnectedCallback(() => {
247
  console.log('DevTools disconnected from target app');
248
  document.getElementById('connection-status').textContent = 'Disconnected';
249
  
250
  // Show reconnection UI
251
  document.getElementById('reconnect-btn').style.display = 'block';
252
});
253
```
254

255
### Open Profiler
256

257
Opens DevTools in Profiler mode without requiring a connection to a target application.
258

259
```javascript { .api }
260
/**
261
 * Opens DevTools in Profiler mode without a connection
262
 */
263
function openProfiler(): void;
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
import DevtoolsUI from "react-devtools-core/standalone";
270

271
// Setup DOM container first
272
DevtoolsUI.setContentDOMNode(document.getElementById('profiler-container'));
273

274
// Open profiler for offline analysis
275
DevtoolsUI.openProfiler();
276
```
277

278
## Complete Integration Example
279

280
### Custom DevTools Host
281

282
```javascript
283
import DevtoolsUI from "react-devtools-core/standalone";
284

285
class DevToolsHost {
286
  constructor(containerId) {
287
    this.container = document.getElementById(containerId);
288
    this.server = null;
289
    this.setupUI();
290
  }
291

292
  setupUI() {
293
    // Configure DevTools UI
294
    DevtoolsUI
295
      .setContentDOMNode(this.container)
296
      .setProjectRoots([process.cwd()])
297
      .setStatusListener(this.handleStatus.bind(this))
298
      .setDisconnectedCallback(this.handleDisconnection.bind(this));
299
  }
300

301
  startServer(port = 8097, host = 'localhost') {
302
    this.server = DevtoolsUI.startServer(port, host, null, {
303
      surface: 'custom-host'
304
    });
305
    
306
    console.log(`DevTools server started at ws://${host}:${port}`);
307
    return this.server;
308
  }
309

310
  handleStatus(message, status) {
311
    console.log(`DevTools Status: ${message} (${status})`);
312
    
313
    // Update UI based on status
314
    const statusEl = this.container.querySelector('.status');
315
    if (statusEl) {
316
      statusEl.textContent = message;
317
      statusEl.className = `status status-${status}`;
318
    }
319
  }
320

321
  handleDisconnection() {
322
    console.log('Target application disconnected');
323
    
324
    // Show waiting message
325
    const statusEl = this.container.querySelector('.status');
326
    if (statusEl) {
327
      statusEl.textContent = 'Waiting for connection...';
328
      statusEl.className = 'status status-waiting';
329
    }
330
  }
331

332
  shutdown() {
333
    if (this.server) {
334
      this.server.close();
335
      this.server = null;
336
    }
337
  }
338
}
339

340
// Usage
341
const devtools = new DevToolsHost('devtools-container');
342
devtools.startServer(8097, '0.0.0.0');
343
```
344

345
### Electron Integration
346

347
```javascript
348
import DevtoolsUI from "react-devtools-core/standalone";
349
import { app, BrowserWindow } from "electron";
350

351
class ElectronDevTools {
352
  constructor() {
353
    this.window = null;
354
    this.server = null;
355
  }
356

357
  createWindow() {
358
    this.window = new BrowserWindow({
359
      width: 1200,
360
      height: 800,
361
      webPreferences: {
362
        nodeIntegration: true,
363
        contextIsolation: false
364
      }
365
    });
366

367
    // Load DevTools HTML
368
    this.window.loadFile('devtools.html');
369

370
    // Setup DevTools when ready
371
    this.window.webContents.once('dom-ready', () => {
372
      this.setupDevTools();
373
    });
374
  }
375

376
  setupDevTools() {
377
    this.window.webContents.executeJavaScript(`
378
      const DevtoolsUI = require("react-devtools-core/standalone");
379
      
380
      DevtoolsUI
381
        .setContentDOMNode(document.getElementById('devtools'))
382
        .setStatusListener((message, status) => {
383
          console.log('DevTools:', message, status);
384
        });
385
      
386
      // Start server
387
      const server = DevtoolsUI.startServer(8097);
388
      window.devtoolsServer = server;
389
    `);
390
  }
391

392
  shutdown() {
393
    if (this.window) {
394
      this.window.webContents.executeJavaScript(`
395
        if (window.devtoolsServer) {
396
          window.devtoolsServer.close();
397
        }
398
      `);
399
    }
400
  }
401
}
402
```
403

404
## Error Handling
405

406
### Server Errors
407

408
Common server error codes and handling:
409

410
```javascript
411
DevtoolsUI.setStatusListener((message, status) => {
412
  if (status === 'error') {
413
    if (message.includes('EADDRINUSE')) {
414
      console.error('Port already in use. Try a different port or close other DevTools instances.');
415
    } else if (message.includes('EACCES')) {
416
      console.error('Permission denied. Try using a port > 1024 or run with elevated privileges.');
417
    } else {
418
      console.error('DevTools server error:', message);
419
    }
420
  }
421
});
422
```
423

424
### Connection Issues
425

426
Handle WebSocket connection problems:
427

428
```javascript
429
const ws = new WebSocket('ws://localhost:8097');
430

431
ws.onerror = (error) => {
432
  console.error('WebSocket error:', error);
433
  // Implement reconnection logic
434
  setTimeout(() => {
435
    const newWs = new WebSocket('ws://localhost:8097');
436
    DevtoolsUI.connectToSocket(newWs);
437
  }, 2000);
438
};
439

440
ws.onclose = (event) => {
441
  console.log('WebSocket closed:', event.code, event.reason);
442
  if (!event.wasClean) {
443
    // Unexpected closure - attempt reconnection
444
    setTimeout(() => {
445
      const newWs = new WebSocket('ws://localhost:8097');
446
      DevtoolsUI.connectToSocket(newWs);
447
    }, 1000);
448
  }
449
};
450
```