Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facebook/react-native/llms.txt

Use this file to discover all available pages before exploring further.

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

  • 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"
}
1

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
2

Verify installation

node --version
npm --version

​
iOS development setup (macOS only)

​
Install Xcode

1

Download Xcode

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

Install Command Line Tools

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

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.
Watchman watches files for changes and triggers actions. It improves performance significantly: 
brew install watchman

​
Android development setup (all platforms)

​
Install Android Studio

1

Download Android Studio

Download from developer.android.com
2

Run the installer

During installation, ensure these components are selected:
  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
3

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
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: 
brew install openjdk@17

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

​
Create an Android Virtual Device (AVD)

1

Open Device Manager

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

Create Virtual Device

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

Download system image

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

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

1

Start the emulator

Open Android Studio → Device Manager → Launch your AVDOr via command line:
emulator -avd <your-avd-name>
2

Run the app

npx react-native run-android

​
Troubleshooting

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)
Clear Gradle cache:
cd android
./gradlew clean
cd ..
Check Android SDK: Ensure ANDROID_HOME is set correctly:
echo $ANDROID_HOME
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>
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:
  1. Follow the quickstart guide to build your first app
  2. Learn how to run on physical devices
  3. Explore core components and APIs

Build docs developers (and LLMs) love

Get started for freeTalk to us