Skip to main content

Set Up Your React Native Development Environment

This guide helps you prepare your machine before running an Instamobile React Native app. Complete this setup once, then use the same environment for any app package you download.

Quick Answer​

Install Node, Yarn through Corepack, Git, Xcode and CocoaPods for iOS, Android Studio and Android SDKs for Android, then verify the app with corepack yarn install --immutable, bundle install, bundle exec pod install, corepack yarn start, corepack yarn ios, and corepack yarn android.

If you are new to React Native, first confirm that your machine can run a clean React Native app. That separates local setup problems from app-specific configuration problems.

First 30 Minutes After Download​

Follow this order when opening an app package for the first time:

  1. Read the README.md included with the app package.
  2. Open the React Native app folder that contains package.json, ios/, android/, and src/.
  3. Check whether the app package includes .nvmrc, .ruby-version, Gemfile, or app-specific setup notes.
  4. Install JavaScript dependencies.
  5. Install iOS pods if you are on macOS.
  6. Start Metro.
  7. Run iOS or Android.
  8. Only customize branding, Firebase, payments, or push after the unmodified app runs locally.

Required Tools​

ToolRequired forHow to verify
Node.jsJavaScript tooling, Metro, React Native CLInode --version
Corepack/YarnDependency installationcorepack enable then corepack yarn --version
GitSource control and package installsgit --version
XcodeiOS buildsxcodebuild -version
Ruby/BundlerCocoaPods workflow on iOSruby --version and bundle --version
CocoaPodsiOS native dependenciespod --version
Android StudioAndroid builds and emulatorsOpen Android Studio and check SDK Manager
Android SDK Platform ToolsAndroid devices and emulatorsadb devices
WatchmanFaster file watching on macOSwatchman --version

Current TypeScript app packages use the stack documented here:

Use the official React Native environment setup guide as the baseline for your operating system:

Node and Yarn​

If the app package includes an .nvmrc, use it from the app folder:

nvm use

Enable Corepack so the project can use the package manager version it expects:

corepack enable
corepack yarn --version

Install packages from the app folder:

corepack yarn install --immutable

Keep yarn.lock committed. It makes installs reproducible across machines.

After installing packages, run the basic project checks:

corepack yarn typecheck
corepack yarn react-native config

iOS Setup​

Install Xcode from the Mac App Store or Apple Developer downloads, then open it once so it can finish installing required components.

Verify Xcode:

xcodebuild -version

If the app package includes a Gemfile, install Ruby gems with Bundler:

bundle install

Install pods from the app folder:

bundle exec pod install --project-directory=ios

If the project does not include a Gemfile, use the local CocoaPods install:

cd ios
pod install
cd ..

Android Setup​

Install Android Studio and open SDK Manager. Make sure you have:

  • Android SDK Platform Tools;
  • an Android SDK platform supported by the app;
  • at least one emulator image, or a physical device with USB debugging enabled.

Verify connected devices:

adb devices

If adb is not found, add Android platform tools to your shell path.

Run the App​

Start Metro in one terminal:

corepack yarn start

Run iOS in a second terminal:

corepack yarn ios

Run Android in a second terminal:

corepack yarn android

If Metro is serving stale code, restart it with:

corepack yarn start --reset-cache

Expo Packages Inside React Native Apps​

Some Instamobile apps include Expo packages for native capabilities such as image picking, camera access, file system access, localization, splash screen, or media utilities.

Install and build those packages through the same native iOS and Android projects shipped in the app package. After changing Expo or native packages, reinstall pods and rebuild the app.

Common Setup Issues​

Metro cannot find a module​

Install dependencies and restart Metro:

corepack yarn install --immutable
corepack yarn start --reset-cache

If the missing package includes native code, rebuild iOS or Android.

Watchman keeps recrawling the project​

Reset the watch for the repository:

watchman watch-del .
watchman watch-project .

Run those commands from the project root.

iOS cannot find Node during build​

Some React Native projects support ios/.xcode.env.local for local Node path overrides. Create it only on your machine:

export NODE_BINARY=/opt/homebrew/bin/node

Do not commit ios/.xcode.env.local.

CocoaPods fails after dependency changes​

Run pods again:

bundle exec pod install --project-directory=ios

If the error mentions a specific native dependency, check that package's React Native compatibility and iOS deployment target.

Android Studio cannot find the SDK​

Open Android Studio, go to SDK Manager, install the missing SDK or platform tools, then rerun:

corepack yarn android

Verification Checklist​

Before customizing the app, confirm:

  • corepack yarn install --immutable completes;
  • bundle exec pod install --project-directory=ios completes on macOS;
  • corepack yarn start starts Metro;
  • corepack yarn ios opens the iOS app;
  • corepack yarn android opens the Android app;
  • you can reload the app from Metro;
  • there are no startup red screens in the unmodified app.

Next Steps​