Running on device - React Native

While emulators are great for development, testing on physical devices is essential for accurate performance testing and device-specific features like camera, GPS, and sensors.

Make sure you’ve completed the environment setup and can run your app in simulators before deploying to devices.

iOS devices

Prerequisites

Mac with Xcode installed
Apple Developer account (free accounts can deploy to devices for 7 days)
Physical iOS device with USB cable
iOS 15.1 or newer on your device

Setup steps

Connect your device

Connect your iOS device to your Mac via USB cable. If prompted on your device, tap “Trust This Computer”.

Enable Developer Mode

On iOS 16+, go to Settings → Privacy & Security → Developer Mode and enable it. Your device will restart.

Open your project in Xcode

cd ios
open YourProjectName.xcworkspace

Always open the .xcworkspace file, not the .xcodeproj file, when using CocoaPods.

Select your device

In Xcode, click the device dropdown near the top-left and select your connected iPhone from the list.

Configure signing

Select your project in the navigator, then:

Select your app target
Go to Signing & Capabilities
Check “Automatically manage signing”
Select your Team (your Apple ID)

Xcode will automatically create a provisioning profile.

Build and run

Click the play button (▶️) in Xcode or press Cmd + R.Or from command line:

npx react-native run-ios --device

Trust the developer certificate

On first launch, you’ll see “Untrusted Developer”:

Open Settings on your device

Go to Settings → General → VPN & Device Management

Trust your Apple ID

Tap your Apple ID under “Developer App”, then tap Trust

Launch the app again

Open the app from your home screen

Free Apple Developer accounts require you to re-sign apps every 7 days. Paid accounts ($99/year) allow apps to stay installed for a year.

Running on specific iOS devices

List available devices:

xcrun xctrace list devices

Run on a specific device:

npx react-native run-ios --device="Your iPhone Name"

Wireless debugging (iOS)

Debug without a cable:

Connect via USB initially

Connect your device via cable and ensure it appears in Xcode

Enable network debugging

In Xcode, go to Window → Devices and SimulatorsSelect your device, check “Connect via network”

Disconnect cable

Once the network icon appears next to your device, you can unplug the cable

Your Mac and iOS device must be on the same Wi-Fi network for wireless debugging.

Android devices

Prerequisites

Android device with USB debugging enabled
Android 7.0 (API 24) or newer
USB cable
Android SDK Platform Tools (adb)

Enable USB debugging

Enable Developer Options

On your Android device:

Go to Settings → About Phone
Tap Build Number 7 times
You’ll see “You are now a developer!”

Enable USB Debugging

Go to Settings → System → Developer Options
Enable USB Debugging
(Optional) Enable Install via USB for faster installs

Connect your device

Connect your Android device via USB cable. Your device will prompt you to allow USB debugging - tap Allow.

Verify connection

Check that your device is connected:

adb devices

You should see output like:

List of devices attached
14ed2fcc    device

Build and run

With your device connected and Metro running:

# Start Metro bundler
npx react-native start

# In another terminal, build and install
npx react-native run-android

The app will automatically install and launch on your connected device.

Connecting to development server

Your device needs to connect to the Metro bundler on your computer:

Via USB (Recommended)
Via Wi-Fi

Use reverse port forwarding:

adb reverse tcp:8081 tcp:8081

This makes port 8081 on your device map to port 8081 on your computer. Metro will work automatically.

If you can’t use USB reverse:

Get your computer's IP

macOS/Linux:

ipconfig getifaddr en0

Windows:

ipconfig

Look for your IPv4 address (e.g., 192.168.1.100)

Configure in-app developer menu

Shake your device or run adb shell input keyevent 82
Tap Settings
Tap Debug server host & port for device
Enter your IP and port: 192.168.1.100:8081
Reload the app

Running release builds

Test the production version of your app:

npx react-native run-android --mode release

Release builds:

Are optimized and minified
Have JavaScript bundle included
Don’t connect to Metro
Run at production performance

Release builds require a signing key for production. See Android documentation for generating release APKs.

Wireless debugging (Android)

Debug over Wi-Fi without USB:

Connect via USB first

Connect your device via USB and ensure adb devices shows it

Enable TCP/IP mode

adb tcpip 5555

Find device IP address

On your device: Settings → About Phone → Status → IP AddressOr via adb:

adb shell ip addr show wlan0

Connect wirelessly

adb connect <device-ip>:5555

Example:

adb connect 192.168.1.150:5555

Disconnect USB and verify

Unplug the USB cable and run:

adb devices

You should see your device with IP:port

To revert to USB mode:

adb usb

Testing device-specific features

Once running on device, you can test features unavailable in emulators:

Camera

import {Camera} from 'react-native-camera';

GPS/Location

import Geolocation from '@react-native-community/geolocation';

Push Notifications

import messaging from '@react-native-firebase/messaging';

Sensors

import {Accelerometer} from 'react-native-sensors';

iOS

Open the developer menu by:

Shaking your device
Three-finger tap (if shake doesn’t work)

Android

Open the developer menu by:

Shaking your device
Running adb shell input keyevent 82
Using hardware menu button (older devices)

Reload
Debug
Enable Fast Refresh
Settings
Show Inspector

Reload JavaScript bundle (same as pressing R twice in Metro)

Performance profiling on devices

React DevTools Profiler

Profile component render performance:

Install React DevTools

npm install -g react-devtools

Run React DevTools

react-devtools

Connect your app

Open developer menu on device → Enable Debug → Open Debugger

Use Profiler

Switch to Profiler tab in React DevTools to record and analyze renders

Native profiling

iOS (Instruments)
Android (Profiler)

Profile native iOS performance:

In Xcode, select Product → Profile (Cmd + I)
Choose a template:
- Time Profiler: CPU usage
- Allocations: Memory usage
- Network: Network activity
Click record and interact with your app

Troubleshooting

iOS: Code signing error

Error: “Code signing is required for product type ‘Application’”Solution:

Open Xcode
Select your project → Target
Go to Signing & Capabilities
Enable “Automatically manage signing”
Select your Team

iOS: Untrusted Developer

Error: “Untrusted Developer” when launchingSolution:

Go to Settings → General → VPN & Device Management
Tap your developer certificate
Tap Trust

Android: Device not detected

Issue: adb devices shows no devicesSolutions:

Ensure USB debugging is enabled
Try a different USB cable (some are charge-only)
Install device-specific USB drivers (Windows)
Run adb kill-server then adb start-server
Check USB connection mode (should be File Transfer/MTP)

Android: Can't connect to Metro

Error: “Could not connect to development server”Solutions:

Set up reverse port forwarding:
adb reverse tcp:8081 tcp:8081
Or configure device’s IP manually in developer menu
Ensure both computer and device are on same network
Check firewall isn’t blocking port 8081

Red screen on device but works on emulator

Possible causes:

Network configuration issues
Missing native dependencies
Platform-specific code errors

Solution:

Check error message details
Test with release build: --mode release
Review platform-specific code with Platform.OS

Building for distribution

Once you’re ready to share your app:

iOS TestFlight

Distribute beta builds to testers via TestFlight

Android Internal Testing

Use Google Play Console for internal testing

iOS App Store

Submit your app to the Apple App Store

Google Play Store

Publish to Google Play Store

Next steps

Test on multiple devices

Test on different screen sizes, OS versions, and manufacturers

Profile performance

Use profiling tools to identify bottlenecks

Test device features

Verify camera, GPS, notifications, and sensors work correctly

Prepare for release

Generate signed builds and prepare store listings

​iOS devices

​Prerequisites

​Setup steps

​Trust the developer certificate

​Running on specific iOS devices

​Wireless debugging (iOS)

​Android devices

​Prerequisites

​Enable USB debugging

​Build and run

​Connecting to development server

​Running release builds

​Wireless debugging (Android)

​Testing device-specific features

Camera

GPS/Location

Push Notifications

Sensors

​Developer menu on devices

​iOS

​Android

​Developer menu options

​Performance profiling on devices

​React DevTools Profiler

​Native profiling

​Troubleshooting

​Building for distribution

iOS TestFlight

Android Internal Testing

iOS App Store

Google Play Store

​Next steps

iOS devices

Prerequisites

Setup steps

Trust the developer certificate

Running on specific iOS devices

Wireless debugging (iOS)

Android devices

Prerequisites

Enable USB debugging

Build and run

Connecting to development server

Running release builds

Wireless debugging (Android)

Testing device-specific features

Developer menu on devices

iOS

Android

Developer menu options

Performance profiling on devices

React DevTools Profiler

Native profiling

Troubleshooting

Building for distribution

Next steps