Skip to main content

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:

  1. connect the device to your Mac;
  2. trust the computer on the device;
  3. open the workspace in Xcode;
  4. select the device;
  5. choose your signing team;
  6. 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 --immutable completes;
  • pods install successfully;
  • corepack yarn start starts Metro;
  • corepack yarn ios builds 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.

Next Steps​