This tutorial will guide you through the process of running a React Native app on a physical device even if it is your first time doing it.
Prerequisites
- This guides assumes you have a running and working React Native project
- Make sure your machine environment is properly setup
- Access to the Apple Developer account
Table of contents
- My environment
- Enable developer mode on iPhone
- Prepare iPhone to run the app
- Managing devices, developer certificate and provision profile in your Apple account
- Installing iOS deploy
- Building the app
My environment
Some parts of this guide may vary depending on your machine environment, such as Xcode version or macOS version. Here is the list versions I used to run the app on my iPhone:
- macOS Sequoia 15.3
- Xcode Version 16.4
- NodeJS v20.19.4
- React Native v0.75.5
- iPhone 11 - iOS 18.6
Enable developer mode on your iPhone
Open the settings app on your iPhone and go to Settings > Privacy & Security > Developer Mode and enable it.
Tap Restart to continue. After the restart, you should see a popup to confirm that you want to enable developer mode. Tap Turn On.
| Find "Developer Mode" | Enable the switch and tap Restart | Tap Turn On |
|
|
|
✅ Now you have successfully enabled developer mode on your iPhone.
Prepare iPhone to run the app
Open Xcode, look for the Window menu and click on Devices and Simulators. Now connect your iPhone to your computer using a lightning/USB cable.
If it is the first time you are connecting the iPhone to your Mac you should see a popup on your iPhone asking you to trust the computer. Tap Trust.
Usually you should see the following screen. That means Xcode is copying the required files to the app on your iPhone. This step is completed automatically.
After that you should see the iPhone in the Devices tab.
✅ If you see this screen, you are ready to run the app on your iPhone.
Common issues:
Skip this section if your iPhone is already properly connected
Connecting the device before enabling developer mode:
If you did that you will probably see the following message in the Devices window
Waiting to reconnect to iPhone. Previous preparation error: Developer Mode disabled. To use iPhone for development, enable Developer Mode in Settings → Privacy & Security.
Solution: Enable developer mode on your iPhone before connecting it to your Mac.
Different networks
Another common issue is when your Mac and your iPhone are not connected to the same network. If that happens you will see the following message:
Ensure the device is unlocked and attached with a cable or associated with the same local area network as this Mac. The device must be opted into Developer Mode to connect wirelessly.
Solution: Make sure your iPhone is connected to the same network as your computer.
Copy files process gets stuck
The copy files process may take a few minutes to complete but sometimes, as it happened to me, that the process gets stuck.
Solution: Disconnect your device and try cleaning the Xcode cache and build files. You can do that by running the following command in the terminal:
npx react-native-clean-project
After cleaning, reconnect your iPhone and try again.
That solved the issue for me and after a few minutes I could see the iPhone connected.
Managing devices, developer certificate and provision profile in your Apple account
There are several steps to do in your Apple account to be able to run the app on your iPhone. First you need to get the device UDID, then you need to register the device in your Apple account, after that request a certificate from authority and create a new development certificate.
Follow this step-by-step guide on how to do that:
Get iPhone UDID and register device
UDID is short for Unique Device Identifier so with your iPhone connected to your computer, open Devices and Simulators in Xcode and copy the Identifier located right below the serial number
Register a new device
For the dark mode folks, the next screenshots will be in light mode ~MY EYES~
First, Go to your Devices list inside your Apple Developer account and click on Devices in the left menu. Click on the + button to add a new device.
On the Register a New Device page, enter the Device Name and Identifier and click Continue.
Review the information and click Register.
On the registration complete screen, click Done.
Now you should see the new device in the list of devices.
Create a iOS development certificate
Before creating a certificate you need to create a Certificate Signing Request (CSR) file. Open your Keychain Access app and go to Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority. Enter your email and name and select Save to disk.
Let's create the iOS development certificate:
First, go to Certificates, Identifiers & Profiles in your Apple Developer account.
Click on Certificates in the left menu and then click on the + button to add a new certificate.
Upload the Certificate Signing Request (CSR) file you created using the Certificate Assistant in the previous step and click Continue.
Select the "iOS App Development" option
Download the certificate and double click on it to install it in your Keychain Access app.
Update Provision Profile
Now, you have a new device registered and a new development certificate. The Provision Profile is what glues the two together.
This will be the last step that need to be done in your Apple account. (Finally!)
- Go to Provisioning Profiles
- Click on the plus button to create a new profile
- Select iOS App Development and click Continue
Select an app ID and click Continue
Select the iOS certificate you created in the previous step and click Continue
Select the device you registered previously and click Continue
Give a name to the provisioning profile and click Generate
After the profile is generated click Download
Open the Xcode project, go to your app target and select the Signing & Capabilities tab. Under Signing, import the provisioning profile you just downloaded.
Be sure that after importing the provisioning profile in your Xcode project it shows no error messages. Here is an example of how it should look like:
Installing iOS deploy
Depending on your iPhone OS version you need to install ios-deploy CLI. Please follow the instructions on the ios-deploy GitHub page to install it.
But if you use Homebrew you can install it by running the following command:
brew install ios-deploy
Building the app
Finally, you can go to your React Native project and build the app by running the following command in the terminal:
npx react-native run-ios --device 'YOUR IPHONE NAME'
Or instead you can use the device ID:
npx react-native run-ios --udid DEVICE_UDID
You can also pass scheme and mode as well. Here's an example:
npx react-native run-ios --device 'iPhone de Salatiel' --scheme='Development' --mode='Debug'
Hopefully you will see the following output after the build is completed:
> info Found Xcode workspace "Runner.xcworkspace"
> info Building (using "xcodebuild -workspace Runner.xcworkspace -configuration Debug -scheme Development -destination id=00000000000000")
> success Successfully built the app
> info Installing and launching your app on iPhone de Salatiel
> success Installed the app on the device.core
And you should see the app running on your iPhone.
✅ Well done!
Top comments (1)
Hey devs! This is my first post here so I appreciate any kind of feedback. I initially wrote this in 2024 because I had to test a new feature on a real iPhone and the tutorials I found wasn't updated or incomplete. I just revised the steps and still works so I decided to post it here.