react-native-ai-devtools 1.4.20 → 1.4.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -107
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,35 +12,35 @@ Have an idea or found something that could be better? Head over to [GitHub Discu
|
|
|
12
12
|
|
|
13
13
|
### Runtime Interaction
|
|
14
14
|
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
15
|
+
- **Console Log Capture** - Capture `console.log`, `warn`, `error`, `info`, `debug` with filtering and search
|
|
16
|
+
- **Network Request Tracking** - Monitor HTTP requests/responses with headers, timing, and body content. Install the optional [SDK](https://www.npmjs.com/package/react-native-ai-devtools-sdk) for full capture from app startup including request/response bodies
|
|
17
|
+
- **JavaScript Execution** - Run code directly in your app (REPL-style) and inspect results
|
|
18
|
+
- **Global State Debugging** - Discover and inspect Apollo Client, Redux stores, Expo Router, and custom globals
|
|
19
|
+
- **Bundle Error Detection** - Get Metro bundler errors and compilation issues with file locations
|
|
20
20
|
|
|
21
21
|
### Device Control
|
|
22
22
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
23
|
+
- **iOS Simulator** - Screenshots, app management, URL handling, boot/terminate (via simctl)
|
|
24
|
+
- **Android Devices** - Screenshots, app install/launch, package management (via ADB)
|
|
25
|
+
- **Unified Tap** - Single `tap` tool with automatic fallback chain: fiber tree → accessibility → OCR → coordinates. Auto-detects platform, accepts pixels from screenshots. Returns post-tap screenshot and verifies visual change by default
|
|
26
|
+
- **UI Automation** - Swipe, long press, text input, and key events on both platforms
|
|
27
|
+
- **Accessibility Inspection** - Query UI hierarchy to find elements by text, label, or resource ID
|
|
28
|
+
- **OCR Text Extraction** - Extract visible text with tap-ready coordinates via Google Cloud Vision (works on any screen content)
|
|
29
29
|
|
|
30
30
|
### Multi-Device Debugging
|
|
31
31
|
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
32
|
+
- **Connect All Devices** - `scan_metro` automatically discovers and connects to all Bridgeless targets on each Metro port
|
|
33
|
+
- **Device Targeting** - Every tool accepts an optional `device` parameter for targeting specific devices by name (case-insensitive substring match)
|
|
34
|
+
- **Per-Device Buffers** - Logs and network requests are captured separately per device for clean debugging
|
|
35
|
+
- **Cross-Platform Comparison** - Debug iOS and Android side-by-side, comparing logs, network traffic, and component trees
|
|
36
36
|
|
|
37
37
|
### Under the Hood
|
|
38
38
|
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
39
|
+
- **Auto-Discovery** - Scans Metro on ports 8081, 8082, 19000-19002 automatically
|
|
40
|
+
- **Multi-Device Support** - Connects to all Bridgeless targets simultaneously, with per-device log and network buffers
|
|
41
|
+
- **Auto-Reconnection** - Exponential backoff (up to 8 attempts) when connection drops
|
|
42
|
+
- **Efficient Buffering** - Circular buffers: 500 logs, 200 network requests
|
|
43
|
+
- **Platform Support** - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)
|
|
44
44
|
|
|
45
45
|
## Platform Setup
|
|
46
46
|
|
|
@@ -70,14 +70,14 @@ Add `env` to your MCP server configuration:
|
|
|
70
70
|
|
|
71
71
|
```json
|
|
72
72
|
{
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
}
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"rn-debugger": {
|
|
75
|
+
"type": "stdio",
|
|
76
|
+
"command": "npx",
|
|
77
|
+
"args": ["react-native-ai-devtools"],
|
|
78
|
+
"env": { "IOS_DRIVER": "axe" }
|
|
80
79
|
}
|
|
80
|
+
}
|
|
81
81
|
}
|
|
82
82
|
```
|
|
83
83
|
|
|
@@ -97,26 +97,26 @@ IDB is the default driver — no `IOS_DRIVER` env var needed.
|
|
|
97
97
|
|
|
98
98
|
**What works without a UI driver:**
|
|
99
99
|
|
|
100
|
-
| Capability
|
|
101
|
-
|
|
102
|
-
| Screenshots
|
|
103
|
-
| App install/launch/terminate
|
|
104
|
-
| URL opening
|
|
105
|
-
| Boot simulator
|
|
106
|
-
| **Tap / swipe / gestures**
|
|
107
|
-
| **Text input**
|
|
108
|
-
| **Accessibility tree queries**
|
|
109
|
-
| **Element finding / waiting**
|
|
110
|
-
| **Hardware buttons (Home, Lock)** | **No**
|
|
100
|
+
| Capability | Without IDB/AXe | With IDB/AXe |
|
|
101
|
+
| --------------------------------- | --------------- | ------------ |
|
|
102
|
+
| Screenshots | Yes (simctl) | Yes |
|
|
103
|
+
| App install/launch/terminate | Yes (simctl) | Yes |
|
|
104
|
+
| URL opening | Yes (simctl) | Yes |
|
|
105
|
+
| Boot simulator | Yes (simctl) | Yes |
|
|
106
|
+
| **Tap / swipe / gestures** | **No** | Yes |
|
|
107
|
+
| **Text input** | **No** | Yes |
|
|
108
|
+
| **Accessibility tree queries** | **No** | Yes |
|
|
109
|
+
| **Element finding / waiting** | **No** | Yes |
|
|
110
|
+
| **Hardware buttons (Home, Lock)** | **No** | Yes |
|
|
111
111
|
|
|
112
112
|
> **Troubleshooting**: If you see errors like `"IDB is not installed"` or `"AXe is not installed"` in tap results, install the appropriate driver with the commands above and retry.
|
|
113
113
|
|
|
114
114
|
## Requirements
|
|
115
115
|
|
|
116
|
-
-
|
|
117
|
-
-
|
|
118
|
-
-
|
|
119
|
-
-
|
|
116
|
+
- Node.js 18+
|
|
117
|
+
- React Native app running with Metro bundler
|
|
118
|
+
- **iOS UI automation**: [Facebook IDB](https://fbidb.io/) (`brew install idb-companion`) or [AXe CLI](https://github.com/cameroncooke/AXe) (`brew install cameroncooke/axe/axe`) — required for tap, swipe, text input, accessibility on iOS Simulator
|
|
119
|
+
- **Optional for offline OCR fallback**: Python 3.6+ (only needed when cloud OCR is unavailable, see [OCR Setup](#ocr-text-extraction))
|
|
120
120
|
|
|
121
121
|
## Claude Code Setup
|
|
122
122
|
|
|
@@ -140,13 +140,13 @@ Add to `~/.claude.json` (user scope) or `.mcp.json` (project scope):
|
|
|
140
140
|
|
|
141
141
|
```json
|
|
142
142
|
{
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
}
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"rn-debugger": {
|
|
145
|
+
"type": "stdio",
|
|
146
|
+
"command": "npx",
|
|
147
|
+
"args": ["react-native-ai-devtools"]
|
|
149
148
|
}
|
|
149
|
+
}
|
|
150
150
|
}
|
|
151
151
|
```
|
|
152
152
|
|
|
@@ -162,13 +162,13 @@ Requires VS Code 1.102+ with Copilot ([docs](https://code.visualstudio.com/docs/
|
|
|
162
162
|
|
|
163
163
|
```json
|
|
164
164
|
{
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
}
|
|
165
|
+
"servers": {
|
|
166
|
+
"rn-debugger": {
|
|
167
|
+
"type": "stdio",
|
|
168
|
+
"command": "npx",
|
|
169
|
+
"args": ["-y", "react-native-ai-devtools"]
|
|
171
170
|
}
|
|
171
|
+
}
|
|
172
172
|
}
|
|
173
173
|
```
|
|
174
174
|
|
|
@@ -182,12 +182,12 @@ Requires VS Code 1.102+ with Copilot ([docs](https://code.visualstudio.com/docs/
|
|
|
182
182
|
|
|
183
183
|
```json
|
|
184
184
|
{
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
}
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"rn-debugger": {
|
|
187
|
+
"command": "npx",
|
|
188
|
+
"args": ["-y", "react-native-ai-devtools"]
|
|
190
189
|
}
|
|
190
|
+
}
|
|
191
191
|
}
|
|
192
192
|
```
|
|
193
193
|
|
|
@@ -199,57 +199,59 @@ Pre-built skills for common debugging workflows — session setup, log inspectio
|
|
|
199
199
|
|
|
200
200
|
See the [full tool reference](docs/tools.md) for all tools with descriptions. Key tools:
|
|
201
201
|
|
|
202
|
-
| Tool
|
|
203
|
-
|
|
|
204
|
-
| `scan_metro`
|
|
205
|
-
| `get_logs` / `search_logs`
|
|
206
|
-
| `get_network_requests`
|
|
207
|
-
| `
|
|
208
|
-
| `
|
|
209
|
-
| `
|
|
202
|
+
| Tool | Description |
|
|
203
|
+
| --------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
204
|
+
| `scan_metro` | **Start here** — scan for Metro servers and auto-connect |
|
|
205
|
+
| `get_logs` / `search_logs` | Capture and search console logs with filtering and summaries |
|
|
206
|
+
| `get_network_requests` | Monitor HTTP requests with method/status filtering |
|
|
207
|
+
| `get_screen_layout` | Screen map of visible components with positions, sizes, and text content |
|
|
208
|
+
| `tap` | **Unified tap** — auto-detects platform, tries fiber → accessibility → OCR → coordinates |
|
|
209
|
+
| `execute_in_app` | Run JS expressions in the app runtime (REPL-style) |
|
|
210
|
+
| `ios_screenshot` / `android_screenshot` | Take device screenshots |
|
|
210
211
|
|
|
211
212
|
## Usage
|
|
212
213
|
|
|
213
214
|
1. Start your React Native app:
|
|
214
215
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
216
|
+
```bash
|
|
217
|
+
npm start
|
|
218
|
+
# or
|
|
219
|
+
expo start
|
|
220
|
+
```
|
|
220
221
|
|
|
221
222
|
2. In Claude Code, scan for Metro:
|
|
222
223
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
224
|
+
```
|
|
225
|
+
Use scan_metro to find and connect to Metro
|
|
226
|
+
```
|
|
226
227
|
|
|
227
228
|
3. Get logs:
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
229
|
+
```
|
|
230
|
+
Use get_logs to see recent console output
|
|
231
|
+
```
|
|
231
232
|
|
|
232
233
|
## Detailed Guides
|
|
233
234
|
|
|
234
|
-
| Guide
|
|
235
|
-
|
|
|
236
|
-
| [Console Logging](docs/logging.md)
|
|
237
|
-
| [Network Tracking](docs/network.md)
|
|
238
|
-
| [App Inspection](docs/app-inspection.md)
|
|
239
|
-
| [
|
|
240
|
-
| [
|
|
241
|
-
| [
|
|
242
|
-
| [
|
|
235
|
+
| Guide | Description |
|
|
236
|
+
| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
237
|
+
| [Console Logging](docs/logging.md) | `get_logs` parameters, filtering, summary mode, TONL format, token optimization |
|
|
238
|
+
| [Network Tracking](docs/network.md) | SDK setup for full capture, filtering, request details, statistics |
|
|
239
|
+
| [App Inspection](docs/app-inspection.md) | Debug globals (Apollo, Redux, Expo Router), `execute_in_app`, limitations |
|
|
240
|
+
| [Layout & Component Inspection](docs/layout-inspection.md) | `get_screen_layout`, component tree, `inspect_at_point`, `find_components` |
|
|
241
|
+
| [Device Interaction](docs/device-interaction.md) | Unified `tap`, platform-specific gestures, text input, key events |
|
|
242
|
+
| [OCR Text Extraction](docs/ocr.md) | Cloud Vision OCR, offline fallback, language config, workflows |
|
|
243
|
+
| [Claude Code Skills](docs/skills.md) | Pre-built skills for session setup, debugging, and automation |
|
|
244
|
+
| [Full Tool Reference](docs/tools.md) | Complete list of all 40+ tools with descriptions |
|
|
243
245
|
|
|
244
246
|
## Supported React Native Versions
|
|
245
247
|
|
|
246
|
-
| Version
|
|
247
|
-
|
|
|
248
|
-
| Expo SDK 54+
|
|
249
|
-
| RN 0.76+
|
|
250
|
-
| RN 0.73 - 0.75 | Bridge (Old Arch)
|
|
251
|
-
| RN 0.70 - 0.72 | Bridge (Old Arch)
|
|
252
|
-
| RN < 0.70
|
|
248
|
+
| Version | Architecture | Engine | Status |
|
|
249
|
+
| -------------- | --------------------- | ------------ | ------------------------------------------------ |
|
|
250
|
+
| Expo SDK 54+ | Bridgeless (New Arch) | Hermes | ✓ Fully supported |
|
|
251
|
+
| RN 0.76+ | Bridgeless (New Arch) | Hermes | ✓ Fully supported |
|
|
252
|
+
| RN 0.73 - 0.75 | Bridge (Old Arch) | Hermes | ✓ Fully supported (best network capture via CDP) |
|
|
253
|
+
| RN 0.70 - 0.72 | Bridge (Old Arch) | Hermes / JSC | ✓ Supported |
|
|
254
|
+
| RN < 0.70 | Bridge | JSC | Not tested |
|
|
253
255
|
|
|
254
256
|
## How It Works
|
|
255
257
|
|
|
@@ -307,8 +309,8 @@ Use `get_connection_status` to see detailed connection information:
|
|
|
307
309
|
|
|
308
310
|
### No devices found
|
|
309
311
|
|
|
310
|
-
-
|
|
311
|
-
-
|
|
312
|
+
- Make sure the app is running on a simulator/device
|
|
313
|
+
- Check that Metro bundler is running (`npm start`)
|
|
312
314
|
|
|
313
315
|
### Wrong device connected
|
|
314
316
|
|
|
@@ -320,9 +322,9 @@ The server prioritizes devices in this order:
|
|
|
320
322
|
|
|
321
323
|
### Logs not appearing
|
|
322
324
|
|
|
323
|
-
-
|
|
324
|
-
-
|
|
325
|
-
-
|
|
325
|
+
- Ensure the app is actively running (not just Metro)
|
|
326
|
+
- Try `clear_logs` then trigger some actions in the app
|
|
327
|
+
- Check `get_apps` to verify connection status
|
|
326
328
|
|
|
327
329
|
## Telemetry & Data Collection
|
|
328
330
|
|
|
@@ -330,14 +332,14 @@ This package collects anonymous usage telemetry to help improve the product. No
|
|
|
330
332
|
|
|
331
333
|
### What is collected
|
|
332
334
|
|
|
333
|
-
| Data
|
|
334
|
-
|
|
335
|
-
| Tool names
|
|
336
|
-
| Success/failure
|
|
337
|
-
| Duration (ms)
|
|
338
|
-
| Session start/end | Retention analysis
|
|
339
|
-
| Platform
|
|
340
|
-
| Server version
|
|
335
|
+
| Data | Purpose |
|
|
336
|
+
| ----------------- | ---------------------------------------- |
|
|
337
|
+
| Tool names | Which MCP tools are used most |
|
|
338
|
+
| Success/failure | Error rates for reliability improvements |
|
|
339
|
+
| Duration (ms) | Performance monitoring |
|
|
340
|
+
| Session start/end | Retention analysis |
|
|
341
|
+
| Platform | macOS/Linux/Windows distribution |
|
|
342
|
+
| Server version | Adoption of new versions |
|
|
341
343
|
|
|
342
344
|
**Not collected**: No file paths, code content, network data, or personally identifiable information.
|
|
343
345
|
|