Skip to main content

Running on iOS

This guide applies to Instamobile React Native CLI templates running on macOS.

Prerequisites​

Before you begin, make sure you already have:

  • the latest stable Xcode
  • CocoaPods
  • Node and Yarn installed
  • a working iOS simulator

If this is your first React Native iOS project, complete the shared setup guide first:

1. Install Dependencies​

From the root of the downloaded template:

yarn install

If the project ships with an .nvmrc, run this first:

nvm use

2. Install Pods​

cd ios
pod install
cd ..

This generates or refreshes the CocoaPods workspace used by Xcode.

3. Start Metro​

In one terminal, run:

yarn start --reset-cache

Keep this terminal open while developing.

4. Run the App​

In a second terminal:

yarn ios

React Native CLI will build the native app and boot the default simulator.

5. If Xcode Cannot Find Node​

Many React Native projects include ios/.xcode.env and support a local ios/.xcode.env.local override.

If your build fails because Xcode cannot locate the correct Node binary:

  1. open ios/.xcode.env
  2. follow the inline instructions
  3. create ios/.xcode.env.local on your machine only

A typical value looks like this:

export NODE_BINARY=/opt/homebrew/bin/node

Do not commit .xcode.env.local.

6. Running From Xcode​

You can also open the generated workspace directly in Xcode:

open ios/Instamobile.xcworkspace

A few templates may still keep historical workspace or target names internally. That does not affect the shipped app name, bundle identifier, or app store submission, as long as those values are properly white-labeled in the project settings.

7. Common iOS Troubleshooting​

Metro is not running​

Start it manually:

yarn start --reset-cache

Pods are out of sync​

Reinstall them:

cd ios
pod install
cd ..

Xcode derived data is stale​

Delete derived data from Xcode settings or from the filesystem, then rebuild.

Notes​

  • Debug builds use Metro during development
  • Release or archive builds bundle JavaScript automatically
  • Some templates use Expo modules inside a React Native CLI app; this is expected and supported