0
# Metro Inspector Proxy
1

2
Metro Inspector Proxy is a JavaScript library that provides an inspector proxy service for React Native debugging and development tools integration. It acts as a bridge between React Native applications and Chrome DevTools or other debugging clients, enabling WebSocket connections for remote debugging, inspector protocol communication, and real-time debugging capabilities.
3

4
## Package Information
5

6
- **Package Name**: metro-inspector-proxy
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install metro-inspector-proxy`
10

11
## Core Imports
12

13
```javascript
14
const { InspectorProxy, runInspectorProxy } = require("metro-inspector-proxy");
15
```
16

17
For ES modules:
18

19
```javascript
20
import { InspectorProxy, runInspectorProxy } from "metro-inspector-proxy";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { runInspectorProxy } = require("metro-inspector-proxy");
27

28
// Start inspector proxy server on port 8081
29
runInspectorProxy(8081, "/path/to/project/root");
30
```
31

32
For more control, use the InspectorProxy class directly:
33

34
```javascript
35
const { InspectorProxy } = require("metro-inspector-proxy");
36
const http = require("http");
37
const connect = require("connect");
38

39
// Create proxy instance
40
const inspectorProxy = new InspectorProxy("/path/to/project/root");
41

42
// Set up HTTP server with middleware
43
const app = connect();
44
app.use(inspectorProxy.processRequest.bind(inspectorProxy));
45

46
const httpServer = http.createServer(app);
47
httpServer.listen(8081, "127.0.0.1", () => {
48
  // Set up WebSocket endpoints
49
  const websocketEndpoints = inspectorProxy.createWebSocketListeners(httpServer);
50
  
51
  httpServer.on("upgrade", (request, socket, head) => {
52
    const { pathname } = require("url").parse(request.url);
53
    if (pathname && websocketEndpoints[pathname]) {
54
      websocketEndpoints[pathname].handleUpgrade(request, socket, head, (ws) => {
55
        websocketEndpoints[pathname].emit("connection", ws, request);
56
      });
57
    } else {
58
      socket.destroy();
59
    }
60
  });
61
});
62
```
63

64
## Architecture
65

66
Metro Inspector Proxy is built around several key components:
67

68
- **InspectorProxy**: Main class that manages device connections and debugger sessions
69
- **Device Management**: Handles individual device connections and page discovery
70
- **WebSocket Communication**: Manages real-time communication between devices and debuggers
71
- **HTTP Endpoints**: Provides JSON API for device discovery and Chrome DevTools integration
72
- **Message Processing**: Handles Chrome DevTools Protocol message forwarding and transformation
73

74
## Capabilities
75

76
### Inspector Proxy Server
77

78
Core proxy functionality for managing inspector connections and HTTP/WebSocket servers. Use this for creating a complete debugging server that handles device registration and debugger connections.
79

80
```javascript { .api }
81
function runInspectorProxy(port: number, projectRoot: string): void;
82

83
class InspectorProxy {
84
  constructor(projectRoot: string);
85
  
86
  processRequest(
87
    request: IncomingMessage,
88
    response: ServerResponse,
89
    next: (?Error) => mixed
90
  ): void;
91
  
92
  createWebSocketListeners(
93
    serverOrBaseUrl: HttpServer | HttpsServer | string
94
  ): { [path: string]: WS.Server };
95
}
96
```
97

98
[Inspector Proxy](./inspector-proxy.md)
99

100
### Device Connection Management
101

102
Device connection handling for React Native apps that connect to the proxy. Each device can have multiple inspectable pages and handles debugger session management.
103

104
```javascript { .api }
105
class Device {
106
  constructor(
107
    id: string,
108
    name: string,
109
    app: string,
110
    socket: WS,
111
    projectRoot: string
112
  );
113
  
114
  getName(): string;
115
  getApp(): string;
116
  getPagesList(): Array<Page>;
117
  handleDebuggerConnection(socket: WS, pageId: string): void;
118
  handleDuplicateDeviceConnection(newDevice: Device): void;
119
}
120
```
121

122
[Device Management](./device-management.md)
123

124
### Command Line Interface
125

126
Command line tool for quickly starting an inspector proxy server with configurable options.
127

128
```javascript { .api }
129
// CLI options
130
interface CLIOptions {
131
  port: number;    // -p, --port (default: 8081)
132
  root: string;    // -r, --root (default: '')
133
}
134
```
135

136
[CLI Interface](./cli-interface.md)
137

138
## Core Types
139

140
```javascript { .api }
141
// Page information from device
142
interface Page {
143
  id: string;
144
  title: string;
145
  vm: string;
146
  app: string;
147
}
148

149
// Page description for debugger
150
interface PageDescription {
151
  id: string;
152
  description: string;
153
  title: string;
154
  faviconUrl: string;
155
  devtoolsFrontendUrl: string;
156
  type: string;
157
  webSocketDebuggerUrl: string;
158
  vm: string;
159
  deviceName: string;
160
}
161

162
// HTTP JSON responses
163
type JsonPagesListResponse = Array<PageDescription>;
164

165
interface JsonVersionResponse {
166
  Browser: string;
167
  'Protocol-Version': string;
168
}
169
```
170

171
## Message Types
172

173
```javascript { .api }
174
// Messages from Inspector Proxy to Device
175
interface ConnectRequest {
176
  event: 'connect';
177
  payload: { pageId: string };
178
}
179

180
interface DisconnectRequest {
181
  event: 'disconnect';
182
  payload: { pageId: string };
183
}
184

185
interface GetPagesRequest {
186
  event: 'getPages';
187
}
188

189
interface WrappedEvent {
190
  event: 'wrappedEvent';
191
  payload: {
192
    pageId: string;
193
    wrappedEvent: string;
194
  };
195
}
196

197
type MessageToDevice = 
198
  | GetPagesRequest 
199
  | WrappedEvent 
200
  | ConnectRequest 
201
  | DisconnectRequest;
202

203
// Messages from Device to Inspector Proxy
204
interface GetPagesResponse {
205
  event: 'getPages';
206
  payload: Array<Page>;
207
}
208

209
type MessageFromDevice = 
210
  | GetPagesResponse 
211
  | WrappedEvent 
212
  | DisconnectRequest;
213
```
214

215
## Chrome DevTools Protocol Types
216

217
```javascript { .api }
218
// Debugger request types
219
interface SetBreakpointByUrlRequest {
220
  id: number;
221
  method: 'Debugger.setBreakpointByUrl';
222
  params: {
223
    lineNumber: number;
224
    url?: string;
225
    urlRegex?: string;
226
    scriptHash?: string;
227
    columnNumber?: number;
228
    condition?: string;
229
  };
230
}
231

232
interface GetScriptSourceRequest {
233
  id: number;
234
  method: 'Debugger.getScriptSource';
235
  params: {
236
    scriptId: string;
237
  };
238
}
239

240
interface GetScriptSourceResponse {
241
  scriptSource: string;
242
  bytecode?: string;
243
}
244

245
interface ErrorResponse {
246
  error: {
247
    message: string;
248
  };
249
}
250

251
type DebuggerRequest = SetBreakpointByUrlRequest | GetScriptSourceRequest;
252

253
// Internal debugger connection information
254
interface DebuggerInfo {
255
  socket: WS;
256
  originalSourceURLAddress?: string;
257
  prependedFilePrefix: boolean;
258
  pageId: string;
259
}
260
```