Skip to main content
Environment Setup

​
Module Overview

Estimated Time: 1-2 hours | Difficulty: Beginner | Prerequisites: Module 1 completed
Setting up a React Native development environment can be tricky, especially for iOS development. This module provides step-by-step instructions for all platforms and both Expo and React Native CLI workflows. What You’ll Learn:
  • Expo vs React Native CLI decision
  • Node.js and package manager setup
  • iOS development setup (macOS only)
  • Android development setup (all platforms)
  • VS Code configuration
  • Troubleshooting common issues

​
Expo vs React Native CLI

Before setting up, choose your development approach: 
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Expo vs React Native CLI                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   Expo (Recommended for Most Projects)                                       │
│   ────────────────────────────────────                                       │
│   ✅ Zero native code configuration                                          │
│   ✅ Expo Go app for instant testing                                         │
│   ✅ EAS Build for cloud builds                                              │
│   ✅ Over-the-air updates                                                    │
│   ✅ Pre-built native modules                                                │
│   ✅ Works on Windows/Linux for iOS (via EAS)                               │
│   ⚠️  Some native modules require "development builds"                      │
│                                                                              │
│   React Native CLI (Bare Workflow)                                           │
│   ────────────────────────────────                                           │
│   ✅ Full native code access                                                 │
│   ✅ Any native module/SDK                                                   │
│   ✅ Custom native code                                                      │
│   ⚠️  Requires Xcode (macOS) for iOS                                        │
│   ⚠️  More complex setup                                                    │
│   ⚠️  Manual native configuration                                           │
│                                                                              │
│   Recommendation:                                                            │
│   Start with Expo. Use "development builds" when you need custom            │
│   native code. You get the best of both worlds.                             │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
  • You’re learning React Native
  • Building a new project from scratch
  • Don’t need custom native modules (yet)
  • Want faster development iteration
  • Need to build iOS apps on Windows/Linux
  • Want managed OTA updates

​
Prerequisites (All Platforms)

​
1. Install Node.js

React Native requires Node.js 18 or newer. 
# Using Homebrew (recommended)
brew install node

# Or using nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc  # or ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20

# Verify installation
node --version  # Should be v18.x or higher
npm --version   # Should be v9.x or higher

​
2. Install a Package Manager

npm comes with Node.js. No additional installation needed.
# Verify npm
npm --version

# Update npm (optional)
npm install -g npm@latest

​
3. Install Git

# Git comes with Xcode Command Line Tools
xcode-select --install

# Or using Homebrew
brew install git

# Verify
git --version

​
Expo Setup

​
Quick Start with Expo

# Create a new Expo project
npx create-expo-app@latest my-app

# Navigate to project
cd my-app

# Start development server
npx expo start

​
Install Expo Go

Download Expo Go on your physical device:

iOS

Download from App Store

Android

Download from Google Play

​
Running Your App

# Start the development server
npx expo start

# Options in the terminal:
# Press 'i' - Open iOS simulator (macOS only)
# Press 'a' - Open Android emulator
# Press 'w' - Open in web browser
# Press 'r' - Reload app
# Press 'm' - Toggle menu
# Press 'j' - Open debugger

# Or scan the QR code with:
# - iOS: Camera app
# - Android: Expo Go app

​
Expo Development Builds

For native modules not in Expo Go, create a development build: 
# Install EAS CLI
npm install -g eas-cli

# Login to Expo
eas login

# Configure your project
eas build:configure

# Create development build
eas build --profile development --platform ios
eas build --profile development --platform android

# Or build locally (requires native tooling)
npx expo run:ios
npx expo run:android

​
iOS Setup (macOS Only)

iOS development requires macOS. Windows and Linux users can use EAS Build for cloud-based iOS builds.

​
1. Install Xcode

# Install from Mac App Store (recommended)
# Search for "Xcode" in App Store

# Or install via command line
xcode-select --install

# After installation, open Xcode and accept the license
sudo xcodebuild -license accept

# Install additional components when prompted
Xcode Requirements:
  • macOS Ventura 13.5 or later (for Xcode 15)
  • ~25GB free disk space
  • Apple ID (free)

​
2. Install Xcode Command Line Tools

# Install command line tools
xcode-select --install

# Verify installation
xcode-select -p
# Should output: /Applications/Xcode.app/Contents/Developer

# If you have multiple Xcode versions
sudo xcode-select --switch /Applications/Xcode.app

​
3. Install CocoaPods

CocoaPods is the dependency manager for iOS: 
# Install CocoaPods using Ruby gem
sudo gem install cocoapods

# Or using Homebrew (recommended)
brew install cocoapods

# Verify installation
pod --version

# Setup CocoaPods (first time only)
pod setup

​
4. Install iOS Simulator

# Open Xcode
open -a Xcode

# Go to: Xcode → Settings → Platforms
# Click '+' and install iOS simulators

# Or via command line
xcodebuild -downloadPlatform iOS

# List available simulators
xcrun simctl list devices
Watchman improves file watching performance: 
# Install via Homebrew
brew install watchman

# Verify installation
watchman --version

​
iOS Setup Verification

# Create a test project
npx react-native@latest init TestProject
cd TestProject

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

# Or with Expo
npx create-expo-app@latest test-expo
cd test-expo
npx expo run:ios

​
Android Setup (All Platforms)

​
1. Install Java Development Kit (JDK)

React Native requires JDK 17: 
# Using Homebrew
brew install openjdk@17

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH

# Verify
java -version

​
2. Install Android Studio

Download Android Studio from developer.android.com/studio During installation, ensure these are selected:
  • Android SDK
  • Android SDK Platform
  • Android Virtual Device (AVD)

​
3. Configure Android SDK

# Open Android Studio
# Go to: More Actions → SDK Manager (or Settings → Languages & Frameworks → Android SDK)

# SDK Platforms tab - Install:
# - Android 14 (API 34) - or latest stable
# - Android 13 (API 33)

# SDK Tools tab - Install:
# - Android SDK Build-Tools 34.0.0
# - Android SDK Command-line Tools
# - Android Emulator
# - Android SDK Platform-Tools
# - Google Play services (optional)

​
4. Set Environment Variables

Add to ~/.zshrc or ~/.bashrc:
# Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
# export ANDROID_HOME=$HOME/Android/Sdk        # Linux

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

# Apply changes
source ~/.zshrc  # or source ~/.bashrc

# Verify
echo $ANDROID_HOME
adb --version

​
5. Create Android Virtual Device (AVD)

# Open Android Studio
# Go to: More Actions → Virtual Device Manager

# Click "Create Device"
# 1. Select hardware: Pixel 7 (or similar)
# 2. Select system image: API 34 (download if needed)
# 3. Name your AVD and finish

# Or via command line
# List available system images
sdkmanager --list | grep system-images

# Download system image
sdkmanager "system-images;android-34;google_apis;x86_64"

# Create AVD
avdmanager create avd -n Pixel_7_API_34 -k "system-images;android-34;google_apis;x86_64" -d "pixel_7"

# List AVDs
emulator -list-avds

# Start emulator
emulator -avd Pixel_7_API_34

​
6. Enable Hardware Acceleration

Hardware acceleration is enabled by default on macOS with Apple Silicon or Intel HAXM.

​
Android Setup Verification

# Create a test project
npx react-native@latest init TestProject
cd TestProject

# Start Android emulator (or connect physical device)
emulator -avd Pixel_7_API_34

# Run on Android
npx react-native run-android

# Or with Expo
npx create-expo-app@latest test-expo
cd test-expo
npx expo run:android

​
VS Code Setup

​
Install VS Code

Download from code.visualstudio.com

​
Essential Extensions

// .vscode/extensions.json
{
  "recommendations": [
    // React Native
    "msjsdiag.vscode-react-native",
    "expo.vscode-expo-tools",
    
    // JavaScript/TypeScript
    "dsznajder.es7-react-js-snippets",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    
    // Productivity
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense",
    "naumovs.color-highlight",
    "streetsidesoftware.code-spell-checker",
    
    // Git
    "eamodio.gitlens",
    "mhutchie.git-graph",
    
    // Testing
    "orta.vscode-jest",
    
    // Optional but useful
    "usernamehw.errorlens",
    "gruntfuggly.todo-tree",
    "wayou.vscode-todo-highlight"
  ]
}

​
VS Code Settings

// .vscode/settings.json
{
  // Editor
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  "editor.tabSize": 2,
  "editor.wordWrap": "on",
  
  // TypeScript
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  
  // Files
  "files.associations": {
    "*.js": "javascriptreact",
    "*.ts": "typescriptreact"
  },
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.expo": true,
    "**/ios/Pods": true
  },
  
  // Emmet
  "emmet.includeLanguages": {
    "javascript": "javascriptreact",
    "typescript": "typescriptreact"
  },
  
  // React Native
  "react-native.packager.port": 8081,
  
  // ESLint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

​
Launch Configuration

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Android",
      "cwd": "${workspaceFolder}",
      "type": "reactnative",
      "request": "launch",
      "platform": "android"
    },
    {
      "name": "Debug iOS",
      "cwd": "${workspaceFolder}",
      "type": "reactnative",
      "request": "launch",
      "platform": "ios"
    },
    {
      "name": "Attach to packager",
      "cwd": "${workspaceFolder}",
      "type": "reactnative",
      "request": "attach"
    },
    {
      "name": "Debug Expo",
      "cwd": "${workspaceFolder}",
      "type": "reactnative",
      "request": "launch",
      "platform": "exponent"
    }
  ]
}

​
Physical Device Setup

​
iOS Physical Device

# 1. Connect iPhone via USB
# 2. Trust the computer on your iPhone
# 3. Open Xcode → Window → Devices and Simulators
# 4. Select your device and enable "Connect via network" (optional)

# For development builds
# 1. Sign in with Apple ID in Xcode
# 2. Select your team in project settings
# 3. Enable "Automatically manage signing"

# Run on device
npx react-native run-ios --device "Your iPhone Name"

# Or with Expo
npx expo run:ios --device

​
Android Physical Device

# 1. Enable Developer Options on your Android device
#    Settings → About Phone → Tap "Build Number" 7 times

# 2. Enable USB Debugging
#    Settings → Developer Options → USB Debugging → Enable

# 3. Connect via USB and accept the debugging prompt

# 4. Verify device is connected
adb devices
# Should show your device

# Run on device
npx react-native run-android

# Or with Expo
npx expo run:android --device

​
Wireless Debugging (Android 11+)

# 1. Enable Wireless debugging in Developer Options
# 2. Pair device with pairing code
adb pair <IP>:<PORT>
# Enter pairing code when prompted

# 3. Connect to device
adb connect <IP>:<PORT>

# 4. Verify connection
adb devices

​
Troubleshooting

​
Common Issues

# Install React Native CLI globally
npm install -g react-native-cli

# Or use npx (recommended)
npx react-native <command>

# Clear CocoaPods cache
cd ios
pod cache clean --all
rm -rf Pods Podfile.lock
pod install --repo-update

# If still failing, try:
sudo gem install cocoapods
pod setup

# Create local.properties in android folder
echo "sdk.dir=$ANDROID_HOME" > android/local.properties

# Or on Windows
echo sdk.dir=C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Android\\Sdk > android\local.properties

# Clear emulator data
emulator -avd YOUR_AVD_NAME -wipe-data

# Or increase emulator storage in AVD settings

# Kill process on port 8081
# macOS/Linux
lsof -i :8081 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Windows
netstat -ano | findstr :8081
taskkill /PID <PID> /F

# Or use different port
npx react-native start --port 8082

# Clear Metro cache
npx react-native start --reset-cache

# Clear watchman
watchman watch-del-all

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules
npm install

# 1. Open project in Xcode
open ios/YourProject.xcworkspace

# 2. Select your project in navigator
# 3. Go to Signing & Capabilities
# 4. Select your Team
# 5. Enable "Automatically manage signing"
# 6. Change Bundle Identifier if needed

​
Clean Build Commands

# Full clean (nuclear option)
# Stop Metro
# Close simulators/emulators

# Clean watchman
watchman watch-del-all

# Clean Metro cache
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*

# Clean node modules
rm -rf node_modules
npm install  # or yarn

# Clean iOS
cd ios
rm -rf Pods Podfile.lock build
pod install --repo-update
cd ..

# Clean Android
cd android
./gradlew clean
cd ..

# Restart Metro
npx react-native start --reset-cache

​
Environment Verification Script

Create a script to verify your setup: 
#!/bin/bash
# save as verify-setup.sh

echo "🔍 Checking React Native Development Environment..."
echo ""

# Node.js
echo "📦 Node.js:"
node --version 2>/dev/null || echo "❌ Node.js not installed"
npm --version 2>/dev/null || echo "❌ npm not installed"
echo ""

# Watchman
echo "👀 Watchman:"
watchman --version 2>/dev/null || echo "⚠️ Watchman not installed (optional)"
echo ""

# Java
echo "☕ Java:"
java -version 2>&1 | head -n 1 || echo "❌ Java not installed"
echo ""

# Android
echo "🤖 Android:"
if [ -n "$ANDROID_HOME" ]; then
  echo "ANDROID_HOME: $ANDROID_HOME"
  adb --version 2>/dev/null | head -n 1 || echo "❌ adb not found"
else
  echo "❌ ANDROID_HOME not set"
fi
echo ""

# iOS (macOS only)
if [[ "$OSTYPE" == "darwin"* ]]; then
  echo "🍎 iOS:"
  xcodebuild -version 2>/dev/null || echo "❌ Xcode not installed"
  pod --version 2>/dev/null && echo "CocoaPods: $(pod --version)" || echo "❌ CocoaPods not installed"
  echo ""
fi

# React Native CLI
echo "⚛️ React Native:"
npx react-native --version 2>/dev/null || echo "Using npx for React Native CLI"
echo ""

echo "✅ Verification complete!"
Run with: 
chmod +x verify-setup.sh
./verify-setup.sh

​
Quick Reference

​
Essential Commands

# Create new project
npx create-expo-app@latest my-app          # Expo
npx react-native@latest init MyApp          # CLI

# Start development
npx expo start                              # Expo
npx react-native start                      # CLI

# Run on platforms
npx expo run:ios                            # Expo iOS
npx expo run:android                        # Expo Android
npx react-native run-ios                    # CLI iOS
npx react-native run-android                # CLI Android

# Clean and rebuild
npx expo start --clear                      # Expo
npx react-native start --reset-cache        # CLI

# Install dependencies
npx expo install <package>                  # Expo (ensures compatibility)
npm install <package>                       # CLI

​
Next Steps

Module 3: Project Structure

Learn how to organize your React Native project for scalability and maintainability