Environment setup

This guide walks you through setting up your development environment for React Native. You’ll install the necessary tools to build and run apps on both iOS and Android.

Choose between Expo CLI (easier, managed workflow) or React Native CLI (full native control). This guide covers React Native CLI for maximum flexibility.

Prerequisites

macOS
Windows
Linux

Node.js 20.19.4+ or 22.13.0+ or 24.3.0+
Watchman (recommended for file watching)
Xcode (for iOS development)
Android Studio (for Android development)
JDK 17 (required for Android)

Installing Node.js

React Native requires a specific version of Node.js as defined in package.json:

package.json

"engines": {
  "node": "^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0"
}

Install Node.js

Download from nodejs.org or use a version manager like nvm:

# Using nvm (recommended)
nvm install 22.13.0
nvm use 22.13.0

Verify installation

node --version
npm --version

iOS development setup (macOS only)

Install Xcode

Download Xcode

Install Xcode from the Mac App Store (version 14.0 or newer recommended)

Install Command Line Tools

Open Xcode, go to Preferences → Locations, and select the Command Line Tools versionOr via terminal:

xcode-select --install

Install iOS Simulator

In Xcode, go to Preferences → Components and install your desired iOS Simulator versions

Install CocoaPods

CocoaPods manages iOS dependencies. React Native uses it extensively:

sudo gem install cocoapods

If you encounter permission issues, you may need to use a Ruby version manager like rbenv or install using --user-install.

Install Watchman (recommended)

Watchman watches files for changes and triggers actions. It improves performance significantly:

brew install watchman

Android development setup (all platforms)

Install Android Studio

Download Android Studio

Download from developer.android.com

Run the installer

During installation, ensure these components are selected:

Android SDK
Android SDK Platform
Android Virtual Device

Install Android SDK

Open Android Studio, go to Settings → Appearance & Behavior → System Settings → Android SDKInstall the following:

Android 14.0 (API 34) or latest
Android SDK Platform 34
Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Configure Android SDK environment variables

Add these to your shell profile (~/.zshrc, ~/.bash_profile, or ~/.bashrc):

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

[System.Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", 'User')

Reload your shell configuration:

source ~/.zshrc  # or ~/.bash_profile

Verify the setup:

adb --version

Install Java Development Kit (JDK)

React Native requires JDK 17. Android Studio includes a JDK, but you may need to install it separately:

macOS
Windows
Linux

brew install openjdk@17

# Add to PATH
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc

sudo apt-get install openjdk-17-jdk

Verify installation:

java -version

Create an Android Virtual Device (AVD)

Open Device Manager

In Android Studio, click Tools → Device Manager (or the device icon in the toolbar)

Create Virtual Device

Click Create Device, select a phone model (e.g., Pixel 6), and click Next

Download system image

Select a system image (API 34 recommended), download it, and click Next

Finish setup

Name your AVD and click Finish

Install React Native CLI

Do not install react-native-cli globally. React Native uses @react-native-community/cli which is included automatically.

The React Native CLI is accessed via npx or yarn:

npx react-native --version

Verify your setup

Create a test project to verify everything works:

npx react-native init TestApp
cd TestApp

Test iOS (macOS only)

# Install iOS dependencies
cd ios
pod install
cd ..

# Run on iOS Simulator
npx react-native run-ios

The first build may take 10-15 minutes as React Native compiles native dependencies.

Test Android

Start the emulator

Open Android Studio → Device Manager → Launch your AVDOr via command line:

emulator -avd <your-avd-name>

Run the app

npx react-native run-android

Troubleshooting

Build failures on iOS

Clear derived data and CocoaPods cache:

cd ios
rm -rf Pods Podfile.lock
pod cache clean --all
pod install
cd ..

Clean Xcode build: Product → Clean Build Folder (Shift + Cmd + K)

Android build failures

Clear Gradle cache:

cd android
./gradlew clean
cd ..

Check Android SDK: Ensure ANDROID_HOME is set correctly:

echo $ANDROID_HOME

Metro bundler issues

Reset Metro cache:

npx react-native start --reset-cache

Check port 8081: Ensure nothing else is using port 8081:

lsof -i :8081
kill -9 <PID>

Node version mismatch

React Native requires specific Node versions. Use nvm to manage versions:

nvm install 22.13.0
nvm use 22.13.0
nvm alias default 22.13.0

Optional tools

Flipper debugger

Flipper provides advanced debugging capabilities:

brew install --cask flipper

Flipper includes:

Network inspector
Layout inspector
Database viewer
Crash reporter

Watchman (Linux)

On Linux, install Watchman from source:

git clone https://github.com/facebook/watchman.git
cd watchman
git checkout v2023.12.04.00
sudo apt-get install -y autoconf automake build-essential libssl-dev libtool
./autogen.sh
./configure
make
sudo make install

Next steps

Now that your environment is configured:

Follow the quickstart guide to build your first app
Learn how to run on physical devices
Explore core components and APIs

Getting Started

Core Concepts

Architecture

Native Modules

Platform Guides

Performance

Developer Tools

Advanced Guides

Prerequisites

Installing Node.js

iOS development setup (macOS only)

Install Xcode

Install CocoaPods

Install Watchman (recommended)

Android development setup (all platforms)

Install Android Studio

Configure Android SDK environment variables

Install Java Development Kit (JDK)

Create an Android Virtual Device (AVD)

Install React Native CLI

Verify your setup

Test iOS (macOS only)

Test Android

Troubleshooting

Optional tools

Flipper debugger

Watchman (Linux)

Next steps

​Prerequisites

​Installing Node.js

​iOS development setup (macOS only)

​Install Xcode

​Install CocoaPods

​Install Watchman (recommended)

​Android development setup (all platforms)

​Install Android Studio

​Configure Android SDK environment variables

​Install Java Development Kit (JDK)

​Create an Android Virtual Device (AVD)

​Install React Native CLI

​Verify your setup

​Test iOS (macOS only)

​Test Android

​Troubleshooting

​Optional tools

​Flipper debugger

​Watchman (Linux)

​Next steps

Prerequisites

Installing Node.js

iOS development setup (macOS only)

Install Xcode

Install CocoaPods

Install Watchman (recommended)

Android development setup (all platforms)

Install Android Studio

Configure Android SDK environment variables

Install Java Development Kit (JDK)

Create an Android Virtual Device (AVD)

Install React Native CLI

Verify your setup

Test iOS (macOS only)

Test Android

Troubleshooting

Optional tools

Flipper debugger

Watchman (Linux)

Next steps