Run a React Native App on iOS
This guide shows how to run an Instamobile React Native app on an iOS simulator or device from the app folder.
Quick Answer
From the app folder, install dependencies with corepack yarn install --immutable --immutable, install pods with bundle exec pod install --project-directory=ios,
start Metro with corepack yarn start, then run the app with corepack yarn ios.
Prerequisites
Before running iOS, confirm that you have:
- macOS;
- Xcode installed and opened at least once;
- Command Line Tools selected in Xcode settings;
- Node and Yarn configured;
- CocoaPods available through Bundler or a local pod install;
- an iOS simulator or a connected iOS device.
Current TypeScript app packages target iOS 17 or newer. For the full stack, see Current React Native Stack.
If your machine is not ready yet, start here:
1. Open the App Folder
Run commands from the React Native app folder, the one that contains:
package.json
ios/
android/
src/
If your package contains more than one app, open the specific app you want to run.
2. Select the Project Node Version
If the app package includes .nvmrc, run:
nvm use
Then install JavaScript dependencies:
corepack enable
corepack yarn install --immutable
3. Install iOS Pods
If the app package includes a Gemfile, prefer Bundler:
bundle install
bundle exec pod install --project-directory=ios
If there is no Gemfile, run CocoaPods directly:
cd ios
pod install
cd ..
This creates or updates the Xcode workspace used by the iOS build.
4. Start Metro
Start Metro in one terminal:
corepack yarn start
Keep this terminal open while developing. If Metro serves stale files, restart it with:
corepack yarn start --reset-cache
5. Run the iOS App
In a second terminal:
corepack yarn ios
To choose a simulator, pass the simulator name supported by your local Xcode installation:
corepack yarn ios --simulator "iPhone 16"
Simulator names depend on your installed Xcode version and available runtimes. Use Xcode's Devices and Simulators window if you need to check the exact name.
6. Open the App in Xcode
If you need signing, capabilities, entitlements, or detailed build logs, open the workspace:
open ios/Instamobile.xcworkspace
Some app packages keep historical workspace or target names internally. What matters for release is the app display name, bundle identifier, signing team, Firebase config, and app store metadata you configure for your product.
7. Configure a Physical Device
For a real iPhone:
- connect the device to your Mac;
- trust the computer on the device;
- open the workspace in Xcode;
- select the device;
- choose your signing team;
- build and run.
Physical devices require valid signing and a bundle identifier that belongs to your Apple Developer account.
Common iOS Issues
Xcode Cannot Find Node
Some projects support ios/.xcode.env.local for local Node path overrides.
Create it on your machine only:
export NODE_BINARY=/opt/homebrew/bin/node
Do not commit ios/.xcode.env.local.
Pods Are Out of Sync
Reinstall pods after native dependency changes:
bundle exec pod install --project-directory=ios
Then rebuild the app.
Metro Is Not Running
Start Metro manually:
corepack yarn start
If the app still shows stale code, restart Metro with:
corepack yarn start --reset-cache
Xcode Build Data Is Stale
Clean the build folder from Xcode, or delete Derived Data from Xcode settings, then rebuild.
Firebase iOS Config Is Missing
Firebase-backed apps need GoogleService-Info.plist inside the iOS app target.
Download it from your Firebase project and place it where the app expects
it.
Verification Checklist
Before customizing iOS behavior, confirm:
corepack yarn install --immutablecompletes;- pods install successfully;
corepack yarn startstarts Metro;corepack yarn iosbuilds and opens the simulator;- the app launches without a startup red screen;
- Xcode can open the workspace;
- Firebase, maps, push, payments, or other native services use your own config files when required.