React Native

Start with one JavaScript file. For local simulator/emulator inspection, you do not need Tracebeam native modules, CocoaPods, Bonjour configuration, an access key, or a certificate.

Quick start

1. Open Tracebeam on your Mac. Leave Settings → Connections in Basic mode.
2. Copy standalone/tracebeam.js from tracebeam-react-native into your app as src/devtools/tracebeam.js.
3. Add this to your root entry file, before AppRegistry.registerComponent:

import { connectDevTools } from './src/devtools/tracebeam';

if (__DEV__) {
  connectDevTools({ metadata: { appName: 'My App' } });
}

Reload your app in iOS Simulator or Android Emulator, then select its connection in Tracebeam’s center toolbar. Open Network or Console and use your app to generate activity.

That’s enough for requests and logs. The connector connects directly to 127.0.0.1:49152 on iOS Simulator or 10.0.2.2:49152 on Android Emulator. It does not browse Bonjour. If your app blocks the connection, see troubleshooting below.

Everything below is for a specific need—not additional steps required to finish the quick start.

Physical device (only if needed)

Android over USB (optional)

For a USB-connected Android phone, enable USB debugging and approve your Mac on the phone. With adb from Android SDK Platform-Tools available, run:

adb devices
adb reverse tcp:49152 tcp:49152

Replace the quick start’s connection call with these Android development options, then reload the app:

if (__DEV__) {
  connectDevTools({ host: '127.0.0.1', port: 49152 });
}

This works with either the copied JavaScript connector or the installed package. Keep Tracebeam in Basic and leave Connect devices over Wi-Fi or Ethernet off: the USB forwarding reaches the Mac’s local listener. No Bonjour setup, access key, or certificate is needed. Basic still requires your app’s debug networking policy to permit cleartext WebSockets; see troubleshooting.

Android Emulator does not need this: its default 10.0.2.2 address already reaches the Mac. Use the USB option only when you need it. For custom ports, multiple devices, or removing forwarding, see Android USB forwarding.

Over Wi-Fi or Ethernet

On the Mac, enable Settings → Connections → Connect devices over Wi-Fi or Ethernet. Put both devices on a trusted local network and pass your Mac’s LAN address:

if (__DEV__) {
  connectDevTools({ host: '192.168.1.20', port: 49152 }); // Replace with your Mac's LAN IP.
}

This still uses the JavaScript connector—no Tracebeam native linking or Bonjour service entry. Basic traffic is unencrypted. Use the same port as Settings → Connections.

iPhone local-network permission

A real iPhone needs permission to contact your Mac on the local network, even with a JavaScript connection. If your app already declares this permission, keep its existing description; otherwise add it to the development app’s Info.plist and rebuild:

<key>NSLocalNetworkUsageDescription</key>
<string>Connect to Tracebeam during development.</string>

Allow the iOS local-network prompt. Do not add NSBonjourServices for this direct connection. This permission step does not apply to the iOS Simulator quick start.

Native features (optional)

Skip this section unless you want automatic discovery, remembered installation identity, screen capture, or on-device recording. Requests and logs already work with the JavaScript quick start.

Install the full package

Build the SDK, then link it into your app:

cd /absolute/path/to/tracebeam/tracebeam-react-native
pnpm install
pnpm build

cd /absolute/path/to/your-react-native-app
pnpm add -D /absolute/path/to/tracebeam/tracebeam-react-native

Use the package import instead of the copied connector:

import { connectDevTools } from '@tracebeam/react-native';

if (__DEV__) {
  connectDevTools({ host: '127.0.0.1' }); // Use 10.0.2.2 for Android Emulator.
}

Call it once near app startup, not in every screen. The package supports native discovery; a host override bypasses discovery. A port override changes the discovered/fallback port.

Perform a full native rebuild after adding or updating the package. Run pod install for iOS. Fast Refresh cannot install native changes. Expo needs a development build; Expo Go cannot load the package’s native modules.

Automatic discovery (optional)

Only if you want the installed package to find the Mac automatically, omit the host option. Add the local-network description above and this Bonjour entry to the development app’s Info.plist, then rebuild:

<key>NSBonjourServices</key>
<array><string>_tracebeam._tcp</string></array>

Allow the local-network prompt on a real iPhone. In Basic mode, the Mac’s network-access setting must be on for Bonjour advertising. To skip discovery, supply host explicitly; then no Bonjour entry is needed.

Troubleshooting

• No connection: check Tracebeam is listening in Basic mode, reload the app, and ensure the port matches. Over Wi-Fi, a physical phone needs your Mac’s LAN address. For Android USB forwarding, use 127.0.0.1 and reapply adb reverse if the mapping was lost after reconnecting.
• Connection blocked by networking policy: your debug build must permit local cleartext WebSockets. If needed, use NSAllowsLocalNetworking under NSAppTransportSecurity on iOS, or android:usesCleartextTraffic="true" on the application in android/app/src/debug/AndroidManifest.xml. Custom Android network-security rules must also permit the debug host. Do not relax release networking policy for this debugger.
• Changed the copied connector: perform a full JavaScript reload. You do not need a native rebuild just to replace that file.
• Added native modules or changed Info.plist: rebuild the native app; Fast Refresh cannot apply these changes.

Advanced options

Secure connection setup

Optional. Use this for authenticated, encrypted connections. It is not needed for the Basic quick start or ordinary requests and logs.

Select Secure in Settings → Connections, copy the access key, and export the Device CA Certificate. For the installed package, supply the exported DER certificate as base64:

openssl base64 -A -in Tracebeam-Device-CA.cer

Store that output and the key in your own git-ignored, debug-only configuration. In this example, localDebugConfig is that application-owned configuration object:

if (__DEV__) {
  connectDevTools({
    host: 'YOUR-MAC.local',
    accessKey: localDebugConfig.tracebeamAccessKey,
    deviceCACertificate: localDebugConfig.tracebeamDeviceCABase64,
  });
}

Pass the base64 contents, not a filename or PEM headers. The native transport trusts this CA only for the debugger connection, verifies the certificate chain and hostname, and bypasses HTTP proxies without changing the app’s HTTP clients.

The copied connector only supports platform certificate trust. Install the Device CA on the development device and pass accessKey, without deviceCACertificate. On iOS, explicitly enable full certificate trust; Android debug builds must opt in to user-installed CAs through a debug-only network security configuration. The copied connector cannot bypass the system proxy. Never substitute the Proxy CA or disable certificate verification.

Supplying a key or certificate selects Secure, including retries. To return to Basic, change the Mac mode and remove both SDK options. Connection troubleshooting.

Capture, state, and reconnects

Both connectors capture supported fetch, XHR, and console activity. Pass your app-owned Redux, Zustand, MMKV, TanStack Query, or React Navigation instances for their inspectors. Tracebeam does not own your app state.

Capture starts after the Mac accepts the connection. The installed native package remembers an app installation across reconnects and restarts; uninstalling or clearing app data resets it. This is not authentication and does not merge separate sessions. The copied connector has no native identity storage.

Capture queues and native batches are bounded. Fetch response-body capture requires a readable stream; without one, metadata is retained and the body is marked incomplete instead of being read without a limit. XHR capture still uses its existing response text. getCaptureDiagnostics() exposes local drop-reason counters; the copied connector exposes connection.diagnostics. These counters are not yet forwarded to the Mac’s Capture Health panel. Unconfirmed in-flight writes are not proof of delivery or loss.

Screen capture and on-device recording are always explicit. To include the recorder in a distributed QA/production app, use the installed package as a regular dependency rather than a dev-only dependency, and expose an explicit user-controlled recording flow. Recording guide.