Onboarding: jhen0409/react-native-debugger

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jhen0409/react-native-debugger shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jhen0409/react-native-debugger repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jhen0409/react-native-debugger.

What it runs against: a local clone of jhen0409/react-native-debugger — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jhen0409/react-native-debugger | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 959 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>jhen0409/react-native-debugger</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jhen0409/react-native-debugger. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jhen0409/react-native-debugger.git
#   cd react-native-debugger
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jhen0409/react-native-debugger and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jhen0409/react-native-debugger(\\.git)?\\b" \\
  && ok "origin remote is jhen0409/react-native-debugger" \\
  || miss "origin remote is not jhen0409/react-native-debugger (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "electron/main.js" \\
  && ok "electron/main.js" \\
  || miss "missing critical file: electron/main.js"
test -f "app/store/configureStore.js" \\
  && ok "app/store/configureStore.js" \\
  || miss "missing critical file: app/store/configureStore.js"
test -f "app/worker/index.js" \\
  && ok "app/worker/index.js" \\
  || miss "missing critical file: app/worker/index.js"
test -f "app/middlewares/debuggerAPI.js" \\
  && ok "app/middlewares/debuggerAPI.js" \\
  || miss "missing critical file: app/middlewares/debuggerAPI.js"
test -f "app/containers/App.js" \\
  && ok "app/containers/App.js" \\
  || miss "missing critical file: app/containers/App.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 959 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~929d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jhen0409/react-native-debugger"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

React Native Debugger is a standalone Electron desktop application that extends React Native's official Remote Debugger with integrated React Inspector (from react-devtools-core), Redux DevTools, and Apollo Client DevTools. It allows developers to inspect component hierarchies, time-travel debug Redux state, and debug GraphQL queries without switching between multiple browser tabs or tools. Single-package Electron application with Redux state management. Core structure: app/containers hold React components (App.js, ReactInspector.js, redux/DevTools.js), app/actions and app/reducers manage state (debugger.js, setting.js), app/middlewares handle API communication (debuggerAPI.js, reduxAPI.js), and app/worker runs background tasks for Apollo/asyncStorage. DevTools integration lives in app/containers/redux/, while UI utilities and platform integrations (ADB, devMenu) live in app/utils/. E2E tests in e2e/ test against mock fixtures (redux.js, apollo.js, remotedev.js).

Who it's for

React Native developers who need a unified debugging experience for inspecting component trees, Redux state changes, and Apollo Client queries. DevTools extension creators and React Native framework maintainers who want to understand how to integrate inspector and devtools protocols into a standalone app.

Maturity & risk

Actively maintained but with a critical caveat: the project explicitly states it only supports the old Remote Debugger protocol and is not compatible with newer React Native debuggers (Hermes, JSI, New Architecture). Version 0.14.0 is the current release. CI/CD is configured (main.yml, release.yml workflows present), but community discussion #774 indicates the maintainer is seeking help to modernize it. Production-ready for React Native ≤0.61, deprecated for newer versions.

Single maintainer (jhen0409) with no visible active collaborators. Dependency on deprecated React Native Remote Debugger protocol means incompatibility with React Native >=0.62 and all newer Hermes/JSI debuggers. The codebase includes ADB integration (utils/adb.js) and complex worker processes (app/worker/) that could introduce platform-specific bugs. No visible unit tests in main codebase, only E2E fixtures.

Active areas of work

Based on repository structure, the project is in maintenance mode for v0.11 (React Native >=0.62 support). Discussion #774 is open for modernizing to support new debuggers. GitHub workflows show CI/CD is active (main.yml runs on PRs, release.yml handles builds), but no specific PRs or milestones are listed in the provided data. The lack of unit tests and single-maintainer status suggests focus is on stability rather than new features.

Get running

git clone https://github.com/jhen0409/react-native-debugger.git
cd react-native-debugger
npm install
npm start

Note: You'll need Xcode (macOS), Visual Studio Build Tools (Windows), or build-essential (Linux) for native module compilation, and Docker/an Android emulator for E2E testing with ADB.

Daily commands:

npm start  # Runs electron with hot reload for development
npm run build  # Builds production bundle
npm run test:e2e  # Runs E2E tests against test fixtures

Check package.json for exact scripts; build output likely goes to a dist/ or build/ folder (not visible in provided structure).

Map of the codebase

• electron/main.js — Electron entry point that bootstraps the entire debugger app—all contributors must understand how the window and IPC channels initialize
• app/store/configureStore.js — Redux store configuration—essential for understanding how app state is managed across debugger and devtools integration
• app/worker/index.js — Worker bridge that connects the React Native app to the debugger via WebSocket and message passing—core communication layer
• app/middlewares/debuggerAPI.js — Middleware handling debugger protocol messages and state synchronization—critical for understanding how breakpoints and stepping work
• app/containers/App.js — Root React container managing layout and connection state—entry point for all UI rendering
• app/reducers/debugger.js — Redux reducer managing debugger state (breakpoints, call stack, variables)—models the core debugging context
• electron/extensions.js — Loads React DevTools and Redux DevTools extensions—critical for integrating third-party devtools

How to make changes

Add a new Redux DevTools integration handler

1. Create a new protocol handler in app/worker/ directory (e.g., app/worker/newDevTools.js) that exports a setup function accepting a message emitter (app/worker/apollo.js)
2. Register the handler in app/worker/index.js by importing it and calling setup() in the messageHandler function (app/worker/index.js)
3. Add corresponding action creator in app/actions/debugger.js to dispatch state updates from the new devtools (app/actions/debugger.js)
4. Create a new Redux container in app/containers/redux/ to display the devtools UI and connect it to the store (app/containers/redux/DevTools.js)

Add a new debugger command (step, pause, resume)

1. Add the action creator function in app/actions/debugger.js following the pattern of existing actions (e.g., pauseApp, resumeApp) (app/actions/debugger.js)
2. Update app/reducers/debugger.js to handle the new action and update the debugger state accordingly (app/reducers/debugger.js)
3. Add message handling in app/middlewares/debuggerAPI.js to send the command over WebSocket to the React Native debugger (app/middlewares/debuggerAPI.js)
4. Add UI button/control in the relevant container (e.g., app/containers/App.js or Redux DevTools header) that dispatches the new action (app/containers/App.js)

Add support for a new React Native device inspection feature

1. Implement protocol handler in app/worker/ directory following the pattern in app/worker/reactDevTools.js (app/worker/reactDevTools.js)
2. Register message handlers in app/worker/index.js messageHandler() to route incoming messages from the device (app/worker/index.js)
3. Create or update Redux reducer in app/reducers/ to store the inspection data (app/reducers/debugger.js)
4. Create a new React container in app/containers/ to display the inspection UI connected to the Redux store (app/containers/ReactInspector.js)

Why these technologies

• Electron — Provides cross-platform (macOS, Windows, Linux) desktop app shell with native OS integration (menus, file dialogs, window management) and Chrome DevTools integration
• React + Redux — Manages complex debugger state (breakpoints, call stack, variables, paused state) with predictable updates and middleware for side-effects; Redux DevTools integration allows introspection
• WebSocket + Web Workers — WebSocket maintains persistent connection to React Native debug server; Web Workers handle protocol parsing off main thread without blocking UI
• adbkit — Provides Android Debug Bridge interface to trigger dev menu and communicate with React Native on physical Android devices
• React DevTools Core + Apollo DevTools — Official integration modules providing component inspection and GraphQL debugging without needing separate browser extensions

Trade-offs already made

• Web Workers instead of native threads

  • Why: Simplifies message passing and avoids C++ binding complexity while keeping protocol handling off main React rendering thread
  • Consequence: Slight overhead from Worker serialization but negligible for typical message volumes; bounded complexity

• WebSocket-based debugging instead of WebDriver protocol

  • Why: Leverages existing React Native remote debugger protocol, enabling fast iteration and compatibility with legacy RN versions
  • Consequence: Does NOT support new debugging infrastructure (Hermes, JSI, New Architecture per README#774); app is effectively maintenance-mode for old Remote Debugger

• electron-store for persistence instead of IndexedDB/LevelDB

  • Why: Simple key-value persistence for user settings; avoids database complexity
  • Consequence: Settings are electron-process-only, not sync'd across instances; adequate for single-window use case

Traps & gotchas

Version lock: React Native Debugger v0.11+ only works with react-native >=0.62; v0.10.x required for older versions—npm will not warn about this. Remote Debugger protocol: the entire app assumes the old WebSocket-based Remote Debugger is running on localhost:8081 (hardcoded in debuggerAPI.js likely); newer React Native versions don't support this. ADB discovery: app/utils/adb.js requires adbkit and a live Android Debug Bridge connection; macOS/Windows may need manual SDK setup. Electron IPC: main.js (not in top 60) must be running; if it crashes, the app freezes without obvious error messages. No environment config file: app/utils/config.js likely has hardcoded defaults—check if custom debugger ports are configurable. Worker thread restrictions: app/worker/ runs in a separate context; DOM/browser APIs are not available there.

Architecture

Concepts to learn

• Remote Debugger Protocol (WebSocket + CDP subset) — The entire app exists to implement this protocol—understanding how the app sends/receives JSON messages over WebSocket to the React Native runtime is essential to knowing why newer versions break compatibility
• Redux DevTools Time-Travel Debugging — Core feature of the app; you need to understand action replaying, state snapshots, and diff-based communication to extend or fix Redux integration
• Electron IPC (Inter-Process Communication) — The Electron main process (main.js) communicates with the React renderer process (app/) via IPC; debugging crashes or state sync issues requires understanding this message passing
• React DevTools Protocol (CDP for React) — React Inspector feature (app/containers/ReactInspector.js) uses this to send component tree, props, and hooks data; understanding it is necessary to fix inspector bugs or add new inspection features
• Android Debug Bridge (ADB) Port Forwarding — app/utils/adb.js uses adbkit to forward ports from physical/emulated Android devices to the debugger; this is how the app discovers and connects to React Native apps on Android
• Web Worker Threading in Electron Context — app/worker/ runs background tasks (Apollo introspection, AsyncStorage mocking) in isolated threads; understanding worker constraints (no DOM, limited globals) is critical when adding new background features
• GraphQL Introspection for Apollo DevTools — app/worker/apollo.js fetches and caches GraphQL schema introspection to enable Apollo DevTools; understanding how Apollo client devtools discovers and validates queries requires knowledge of introspection format

Related repos

• facebook/react-native — Official React Native repository; contains the Remote Debugger implementation this app wraps, and discussions about new debugger architecture affecting compatibility
• facebook/react — Home of react-devtools-core package that React Native Debugger depends on for the React Inspector feature
• reduxjs/redux-devtools — Redux DevTools project that defines the extension API React Native Debugger reimplements for time-travel debugging
• apollographql/apollo-client-devtools — Apollo Client DevTools source code; React Native Debugger bundles this as an integrated extension
• electron/electron — Electron framework underlying the entire desktop app; knowledge of IPC, app lifecycle, and packaging is required to modify the app shell (main.js)

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E tests for Redux DevTools and React Inspector workflows

The e2e directory exists with test infrastructure (app.spec.js, mockRNServer.js) and fixtures for redux.js, apollo.js, and mobx.js, but test coverage appears incomplete. The main warning in README about legacy Remote Debugger support means the existing tested workflows should be well-validated. Add comprehensive E2E tests that verify Redux time-travel debugging, state inspection, and React Inspector component tree navigation work correctly.

• [ ] Expand e2e/app.spec.js with test cases for Redux DevTools state inspection and time-travel actions using e2e/fixture/redux.js
• [ ] Add E2E test cases for React Inspector tree navigation in app/containers/ReactInspector.js workflows
• [ ] Add E2E test case for network inspection using e2e/fixture/xhr-test.js to validate app/worker/networkInspect.js
• [ ] Document E2E test execution in README.md for new contributors

Add unit tests for worker middleware and debugging logic

The app/worker directory contains critical debugging logic (reactDevTools.js, reduxAPI.js, remotedev.js, networkInspect.js) and app/middlewares contains debuggerAPI.js and reduxAPI.js, but no unit tests are present in the file structure. This is risky for a debugging tool where correctness is essential. Add unit tests to validate message passing, Redux action interception, and DevTools protocol handling.

• [ ] Create tests/worker/reduxAPI.test.js to test Redux action serialization and state snapshots from app/worker/reduxAPI.js
• [ ] Create tests/middlewares/debuggerAPI.test.js to test debugger message routing and protocol handling from app/middlewares/debuggerAPI.js
• [ ] Create tests/worker/networkInspect.test.js to test XHR/fetch interception logic from app/worker/networkInspect.js
• [ ] Create tests/worker/reactDevTools.test.js to validate React DevTools protocol integration from app/worker/reactDevTools.js

Add missing settings validation and documentation for app/utils/config.js

The codebase has app/utils/config.js and electron-store dependency for persistent settings, with app/reducers/setting.js managing state, but there's no visible input validation for user settings (like in app/components/FormInput.js) or documentation of available configuration options. Add schema validation and update README with configuration options to reduce user errors and improve maintainability.

• [ ] Add JSON schema validation to app/utils/config.js using a lightweight validator to validate all settings before storage (hostname, port, custom device list, etc.)
• [ ] Create tests/utils/config.test.js with tests for valid/invalid configuration edge cases
• [ ] Add 'Configuration' section to README.md documenting all available settings, defaults, and constraints that users and contributors should know
• [ ] Update app/components/FormInput.js to use validation from config.js with user-friendly error messages

Good first issues

• Add unit tests for app/reducers/debugger.js and app/reducers/setting.js (currently no tests visible in the file list)—this would catch state mutation bugs and give the maintainer confidence for future changes.
• Document the Remote Debugger protocol handshake in a PROTOCOL.md file with concrete examples from debuggerAPI.js, so new contributors understand the communication format without reverse-engineering it.
• Add a Configuration UI in app/containers (similar to redux/Settings.js) to allow users to customize debugger host, port, and ADB path without editing config files—currently hidden in app/utils/config.js with no UI.

Top contributors

• @jhen0409 — 64 commits
• @dependabot[bot] — 27 commits
• @crloz — 1 commits
• @rafauke — 1 commits
• @hbiede — 1 commits

Recent commits

• bd3435a — v0.14.0 (jhen0409)
• f1786b0 — Update docs/react-devtools-integration.md (jhen0409)
• d5da0e7 — Package: Use ditto for zip macOS app (jhen0409)
• 3e02f15 — Update about dialog content (jhen0409)
• 729a11b — CD: Trigger only for published (jhen0409)
• 988fae8 — Revert patch of apollo-client-devtools in dist/ (jhen0409)
• 729f866 — Package: Move apollo-client-devtools to dev-deps & use --prune (jhen0409)
• f6333cd — Update README.md (Add Build from source section) (jhen0409)
• cd051b5 — Update docs/contributing.md (jhen0409)
• 7a01a43 — Fix host of adb client on electron 25 (node 18) (jhen0409)

Security observations

• High · Outdated Electron DevTools Core Dependency — package.json - dependencies. The package uses 'react-devtools-core': '^4.28.0' which may contain known vulnerabilities. React DevTools Core handles sensitive debugging information and should be kept up to date with the latest security patches. Fix: Update react-devtools-core to the latest stable version and regularly monitor for security updates. Consider implementing automated dependency scanning with tools like npm audit or dependabot.
• High · Potential Remote Code Execution via Network Communication — app/worker/networkInspect.js, app/worker/remotedev.js, app/middlewares/debuggerAPI.js. The app includes network inspection capabilities and remote debugging features (app/worker/networkInspect.js, app/worker/remotedev.js) that handle data from React Native apps. Improper validation of incoming debugger messages could lead to RCE or XSS attacks. Fix: Implement strict input validation for all incoming debugger protocol messages. Sanitize and validate data before processing. Use Content Security Policy (CSP) headers. Consider implementing message signature verification.
• High · ADB Command Injection Risk — app/utils/adb.js. The app includes ADB integration (app/utils/adb.js) for Android device communication. Improper sanitization of device names or ADB commands could allow command injection attacks. Fix: Use parameterized command execution instead of string concatenation. Never pass user input directly to shell commands. Use libraries that safely handle process execution with proper escaping.
• Medium · Insecure Electron Store Configuration — package.json - dependencies (electron-store). The app uses 'electron-store': '^1.2.0' for persistent storage. This version is outdated and may have security vulnerabilities. Sensitive debugging data could be stored without proper encryption. Fix: Update electron-store to the latest version. Consider enabling encryption for sensitive data. Review what data is being persisted and implement appropriate access controls.
• Medium · Missing Content Security Policy — dist/app.html, app/index.js. No evidence of CSP headers or meta tags to prevent XSS attacks. The debugger UI (app/components, app/containers) could be vulnerable to script injection through malicious Redux state or network inspection data. Fix: Implement a strict Content Security Policy. Use dangerouslySetInnerHTML sparingly and validate all user input. Consider using React's built-in XSS protection by avoiding innerHTML.
• Medium · Unvalidated Redux State Display — app/containers/redux/DevTools.js, app/worker/reduxAPI.js. Redux DevTools functionality (app/containers/redux/DevTools.js) displays application state which could contain sensitive information. No apparent filtering or redaction of sensitive data before display. Fix: Implement data sanitization/filtering for sensitive information in Redux state. Add user warnings about security implications. Consider implementing a list of fields to redact (API tokens, passwords, PII).
• Medium · Unsafe Local File Access — app/utils/config.js, app/worker/asyncStorage.js. The app uses Electron which has direct filesystem access. Configuration files (app/utils/config.js) and AsyncStorage worker (app/worker/asyncStorage.js) access local data without apparent encryption. Fix: Implement file-level access controls. Use encryption for sensitive configuration data. Validate file paths to prevent directory traversal attacks. Use Electron's sandbox features.
• Medium · Missing HTTPS/WSS Requirement for Remote Debugging — app/worker/remotedev.js, app/middlewares/debuggerAPI.js. Remote debugging connections (remotedev.js, debuggerAPI.js) may communicate over unencrypted channels. Sensitive debugging data could be intercepted. Fix: Enforce HTTPS/WSS for all remote communications. Implement certificate pinning if applicable. Add warning messages when using unencrypted connections in development.
• Low · Missing Security Headers in HTML Distribution — undefined. The dist/app.html file likely lacks security headers like X-Frame-Options, X-Content-Type-Options, etc Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.