Codakey
Play
← Back to facebook/react-native

How to Deploy & Use facebook/react-native

# React Native Deployment & Usage Guide

## 1. Prerequisites

### Development Environment
- **Node.js**: LTS version (18.x or newer recommended)
- **Package Manager**: npm, Yarn, or pnpm
- **Watchman**: Required for macOS and Linux development (`brew install watchman`)
- **Git**: For version control and cloning repositories

### Platform-Specific Requirements

**iOS Development (macOS only)**
- macOS 13.5 or newer
- Xcode 15.0 or newer (includes iOS 15.1+ SDK)
- CocoaPods: `sudo gem install cocoapods`
- iOS Simulator or physical device running iOS 15.1+

**Android Development (Windows/macOS/Linux)**
- Android Studio (latest stable)
- Android SDK 34 (compileSdkVersion)
- Android 7.0 (API 24) minimum for devices/emulators
- JDK 17 (OpenJDK or Oracle)
- Android Virtual Device (AVD) or physical device with USB debugging enabled

**Note**: Building iOS apps requires macOS. Windows/Linux users can use [Expo](https://expo.dev) to develop iOS apps via cloud builds.

## 2. Installation

### Option A: New Application (Recommended)

Using React Native CLI:
```bash
npx react-native@latest init MyApp --version latest
cd MyApp

Using Expo (zero-config alternative):

npx create-expo-app MyApp
cd MyApp

Option B: Integrate into Existing App

Follow the Integration Guide for adding React Native to existing Android (Gradle) or iOS (Xcode) projects.

Option C: Build React Native from Source (Contributors)

git clone https://github.com/facebook/react-native.git
cd react-native
yarn install

3. Configuration

Environment Variables

Android (Required) Add to ~/.bashrc, ~/.zshrc, or Windows System Environment:

export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS/Linux
# or export ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk  # Windows

export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

iOS (macOS) Ensure Xcode command line tools are selected:

sudo xcode-select --switch /Applications/Xcode.app
sudo xcodebuild -runFirstLaunch

Project Configuration

iOS Dependencies

cd ios && pod install && cd ..

Android Gradle (Optional) Edit android/gradle.properties for memory settings:

org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m

4. Build & Run

Development Server

Start Metro bundler (keep running in separate terminal):

npx react-native start
# or
npm start

iOS

# Run on iOS Simulator (default)
npx react-native run-ios

# Run on specific device
npx react-native run-ios --device "iPhone 15 Pro"

# Run on physical device (requires signing configuration in Xcode)
npx react-native run-ios --device

Android

# Ensure emulator is running or device is connected
npx react-native run-android

# Run on specific variant
npx react-native run-android --variant=release

Debugging

  • Flipper: Install Flipper Desktop for debugging (included in React Native 0.71+)
  • Hermes: Enabled by default for performance; use Chrome DevTools via chrome://inspect
  • React DevTools: Run npx react-devtools for component inspection

Production Builds

iOS

cd ios
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos

Android

cd android
./gradlew assembleRelease  # APK output: android/app/build/outputs/apk/release/
./gradlew bundleRelease    # AAB for Play Store

5. Deployment

iOS (App Store)

  1. Configure signing in Xcode: ios/MyApp.xcworkspace → Signing & Capabilities
  2. Archive: Product → Archive
  3. Upload via Xcode Organizer or Transporter app
  4. Submit through App Store Connect

Android (Google Play)

  1. Generate upload key (one-time): 
    keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000
  2. Place in android/app/ and configure android/gradle.properties: 
    MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****
  3. Build AAB: cd android && ./gradlew bundleRelease
  4. Upload android/app/build/outputs/bundle/release/*.aab to Google Play Console

Alternative Platforms

  • Expo EAS: eas build --platform all for cloud builds without local native setup
  • Microsoft CodePush: For OTA JavaScript updates without store submission
  • Firebase App Distribution: For beta testing

6. Troubleshooting

Metro Bundler Issues

Error: Error: listen EADDRINUSE: Address already in use :::8081

npx react-native start --port 8088
# Update iOS: npx react-native run-ios --port 8088

Error: Unable to resolve module

npx react-native start --reset-cache
# or
npm start -- --reset-cache

iOS Build Failures

CocoaPods Errors:

cd ios && pod deintegrate && pod install --repo-update

Xcode Build Failures:

  • Clean build folder: Cmd+Shift+K in Xcode
  • Reset simulator: Device → Erase All Content and Settings

Android Build Failures

Gradle Daemon Issues:

cd android && ./gradlew --stop && ./gradlew clean

SDK/NDK Not Found:

  • Verify ANDROID_HOME points to correct SDK location
  • Install missing components via Android Studio SDK Manager

Duplicate Classes/Dex Merge Errors: Check for conflicting dependencies in android/app/build.gradle:

implementation("com.example:library:1.0.0") {
    exclude group: 'com.conflicting.group'
}

Runtime Issues

App crashes immediately:

  • Check adb logcat (Android) or Xcode Console (iOS) for native stack traces
  • Verify Hermes is enabled consistently across builds: npx react-native info

Network requests failing (iOS): Add to ios/MyApp/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Performance

  • Enable Hermes: Verify in android/app/build.gradle and ios/Podfile
  • Use Flipper to profile JavaScript and native threads
  • Enable ProGuard/R8 for Android release builds (enabled by default in new projects)
← Project overviewView alternatives to facebook/react-native →