DEV Community

Prabhakar
Prabhakar

Posted on

React Native Setup Guide — Run Your First App on a Brand New Mac or Windows Machine

#reactnative #mobile #setup #beginners

React Native Setup Guide — Run Your First App on a Brand New Mac or Windows Machine

You just got a fresh machine. You need to run a React Native app. This guide takes you from zero to a running app on iOS or Android — step by step, nothing skipped.

Everything here is aligned with the official React Native environment setup docs.

Important: iOS apps can only be built on a Mac. Android works on both Mac and Windows.

On Linux? This guide focuses on Mac and Windows, but React Native works on Linux too (Android only). Follow the official Linux setup instructions.

Table of Contents

What You'll Install

Tool What It Does Platform
Homebrew / Chocolatey Installs other tools for you Mac / Windows
Git Downloads the project code Both
Node.js (>= 22) Runs the JavaScript code Both
Watchman Watches files for changes Mac only
Xcode Builds the iOS app Mac only
Ruby & CocoaPods Manages iOS native libraries Mac only
JDK 17 (Azul Zulu) Required by Android builds Both
Android Studio Builds the Android app Both

Part 1 — Mac Setup

Step 1: Install Homebrew

Open the Terminal app (press Cmd + Space, type "Terminal", hit Enter).

Paste this and press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Enter fullscreen mode Exit fullscreen mode

Follow the on-screen instructions.

Apple Silicon (M1/M2/M3/M4) users — important! After the install finishes, Homebrew will print two commands under "Next steps" that look like this:

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

You must run both of these. Copy and paste them exactly as shown in your terminal output. Without this step, the brew command won't be found.

Close and reopen Terminal after running the above.

Verify it works:

brew --version
Enter fullscreen mode Exit fullscreen mode

You should see something like Homebrew 4.x.x.

Step 2: Install Git 

brew install git
Enter fullscreen mode Exit fullscreen mode

Verify:

git --version
Enter fullscreen mode Exit fullscreen mode

Step 3: Install Node.js

React Native requires Node 22.11.0 or newer.

brew install node
Enter fullscreen mode Exit fullscreen mode

Verify:

node --version
Enter fullscreen mode Exit fullscreen mode

It should show v22.x.x or higher.

Using nvm instead? That works too — but you'll need an extra Xcode config step later (covered in the Troubleshooting section).

Step 4: Install Watchman 

brew install watchman
Enter fullscreen mode Exit fullscreen mode

Watchman helps Metro (the React Native bundler) detect file changes quickly. It's highly recommended by the official docs for better performance.

Step 5: Install Xcode (for iOS)

  1. Open the App Store on your Mac.
  2. Search for Xcode and click Get / Install (it's around 12 GB — grab a coffee).
  3. After install, open Xcode once and accept the license agreement.

Set the Command Line Tools:

  1. In Xcode, go to Settings (or Preferences) → Locations tab.
  2. In the Command Line Tools dropdown, select the most recent version.

Install an iOS Simulator:

  1. In Xcode, go to Settings → Platforms (or Components) tab.
  2. Click the + icon and select iOS... to download a simulator runtime.
  3. Pick the latest iOS version available.

Step 6: Install JDK 17 (for Android)

React Native requires JDK 17. The official docs recommend the Azul Zulu distribution.

brew install --cask zulu@17
Enter fullscreen mode Exit fullscreen mode

After Homebrew finishes, it downloads a .pkg installer. You need to run it manually:

  • Apple Silicon (M1/M2/M3/M4): Open the .pkg file from /opt/homebrew/Caskroom/zulu@17/
  • Intel Mac: Open it from /usr/local/Caskroom/zulu@17/

You can find the exact path in the Homebrew output after the install.

Now add JAVA_HOME to your shell config. Open ~/.zprofile (or ~/.zshrc):

open -e ~/.zprofile
Enter fullscreen mode Exit fullscreen mode

If the file doesn't exist, create it: touch ~/.zprofile && open -e ~/.zprofile

Add this line at the bottom:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
Enter fullscreen mode Exit fullscreen mode

Save, close, and reload:

source ~/.zprofile
Enter fullscreen mode Exit fullscreen mode

Verify:

java -version
Enter fullscreen mode Exit fullscreen mode

It should show openjdk version "17.x.x".

Warning: Using a JDK version higher than 17 may cause build issues. If you must use a higher version, you'll need to update the Gradle version in your project's android/gradle/wrapper/gradle-wrapper.properties.

Step 7: Install Android Studio (for Android)

  1. Download from developer.android.com/studio.
  2. Open the .dmg file and drag Android Studio into Applications.
  3. Open Android Studio and go through the setup wizard — choose Standard install.
  4. Make sure these are checked during setup:
    • Android SDK
    • Android SDK Platform
    • Android Virtual Device

Install the required SDK components:

  1. Open Android Studio → Settings (or Preferences) → Languages & Frameworks → Android SDK.

  2. In the SDK Platforms tab:

    • Check Show Package Details (bottom-right corner).
    • Expand Android 15 (VanillaIceCream) and check:
      • Android SDK Platform 35
      • Pick the right system image for your chip:
      • Intel Mac: Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image
      • Apple Silicon Mac: Google APIs ARM 64 v8a System Image

  3. In the SDK Tools tab:

    • Check Show Package Details (bottom-right corner).
    • Expand Android SDK Build-Tools and check 36.0.0.
    • Also make sure Android SDK Command-line Tools (latest) is checked.

  4. Click Apply / OK to install everything.

Set up environment variables:

Open ~/.zprofile (or ~/.zshrc):

open -e ~/.zprofile
Enter fullscreen mode Exit fullscreen mode

Add these lines at the bottom:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
Enter fullscreen mode Exit fullscreen mode

Save, close, and reload:

source ~/.zprofile
Enter fullscreen mode Exit fullscreen mode

Create an Android Emulator:

  1. Open Android Studio.
  2. Click More Actions → Virtual Device Manager (or Tools → Device Manager).
  3. Click Create Device.
  4. Pick a phone (e.g., Pixel 8) → Next.
  5. Select the VanillaIceCream API Level 35 system image → Next → Finish.

Part 2 — Windows Setup

Reminder: Windows can only build the Android version. For iOS, you need a Mac.

Step 1: Install Chocolatey

Open PowerShell as Administrator (right-click the Start button → "Terminal (Admin)" or "PowerShell (Admin)").

Paste this and press Enter:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
Enter fullscreen mode Exit fullscreen mode

Close and reopen PowerShell as Administrator.

Verify:

choco --version
Enter fullscreen mode Exit fullscreen mode

Step 2: Install Node.js, JDK 17, and Git 

choco install -y nodejs-lts microsoft-openjdk17 git
Enter fullscreen mode Exit fullscreen mode

Close and reopen PowerShell. Verify all three:

node --version
java -version
git --version
Enter fullscreen mode Exit fullscreen mode

Node should be v22.x.x or higher. Java should be openjdk version "17.x.x".

Step 3: Install Android Studio

  1. Download from developer.android.com/studio.
  2. Run the installer, choose Standard setup.
  3. Make sure these are checked during setup:
    • Android SDK
    • Android SDK Platform
    • Android Virtual Device
    • Performance (Intel HAXM) — if you're not using Hyper-V

Install the required SDK components:

  1. Open Android Studio → Settings → Languages & Frameworks → Android SDK.

  2. In the SDK Platforms tab:

    • Check Show Package Details (bottom-right corner).
    • Expand Android 15 (VanillaIceCream) and check:
      • Android SDK Platform 35
      • Google APIs Intel x86 Atom_64 System Image

  3. In the SDK Tools tab:

    • Check Show Package Details (bottom-right corner).
    • Expand Android SDK Build-Tools and check 36.0.0.
    • Also make sure Android SDK Command-line Tools (latest) is checked.

  4. Click Apply / OK to install everything.

Set environment variables:

  1. Open Start → search "Environment Variables" → click "Edit the system environment variables".
  2. Click the Environment Variables button.
  3. Under User variables, click New:
    • Variable name: ANDROID_HOME
    • Variable value: %LOCALAPPDATA%\Android\Sdk
  4. Select Path in User variables → Edit → New → add:
    • %LOCALAPPDATA%\Android\Sdk\platform-tools
  5. Click OK on all dialogs.

Create an Android Emulator:

  1. Open Android Studio.
  2. Click More Actions → Virtual Device Manager (or Tools → Device Manager).
  3. Click Create Device.
  4. Pick a phone (e.g., Pixel 8) → Next.
  5. Select the VanillaIceCream API Level 35 system image → Next → Finish.

Part 3 — Get the Code

You have two options: clone an existing project from a repo, or create a brand new app from scratch. Pick the one that applies to you.

Option A: Clone an Existing Project

This is for you if your team already has a React Native app in a Git repository.

Step 1: Clone the repo

git clone <your-repo-url>
cd <project-folder>
Enter fullscreen mode Exit fullscreen mode

Replace <your-repo-url> with your actual repository URL (e.g., https://github.com/your-org/your-app.git).

Step 2: Set up environment variables

Many projects use a .env file. Check if there's a .env.example in the project root:

Mac / Linux:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell):

Copy-Item .env.example .env
Enter fullscreen mode Exit fullscreen mode

Open .env in any text editor and fill in the values. Ask your team for the correct values if you're unsure.

If there's no .env.example, your project may not need one — check with your team.

Step 3: Install dependencies

Check which package manager your project uses by looking at the lock file in the project root:

Lock File Package Manager Install Command
package-lock.json npm npm install
yarn.lock Yarn yarn install
pnpm-lock.yaml pnpm pnpm install

If you need Yarn: npm install -g yarn
If you need pnpm: npm install -g pnpm

Step 4: Install iOS dependencies (Mac only)

React Native iOS projects use CocoaPods to manage native libraries.

If your project has a Gemfile (most do):

bundle install
cd ios && bundle exec pod install && cd ..
Enter fullscreen mode Exit fullscreen mode

If your project does NOT have a Gemfile:

sudo gem install cocoapods
cd ios && pod install && cd ..
Enter fullscreen mode Exit fullscreen mode

For more details, see the CocoaPods Getting Started guide.

Now skip ahead to Part 4 — Run the App.

Option B: Create a Brand New App

This is for you if you're starting from zero — no existing project.

You have two paths: Expo (recommended by the official React Native docs) or bare React Native (no framework). Here's a quick comparison:

Expo Bare React Native
Best for Most apps, faster setup Full native control from day one
Setup One command One command + CocoaPods
Native code access Yes (via config plugins or ejecting) Yes (direct)
OTA updates Built-in (EAS Update) Manual
Recommended by Official React Native docs —

Path 1: Create with Expo (Recommended) 

npx create-expo-app@latest MyApp
cd MyApp
Enter fullscreen mode Exit fullscreen mode

That's it. Expo handles the native setup for you.

To run it:

npx expo start
Enter fullscreen mode Exit fullscreen mode

Then press i for iOS Simulator or a for Android Emulator.

Learn more: Expo docs

Path 2: Create with bare React Native (No Framework)

First, make sure you don't have the old global CLI installed:

npm uninstall -g react-native-cli @react-native-community/cli
Enter fullscreen mode Exit fullscreen mode

Then create the project:

npx @react-native-community/cli@latest init MyApp
cd MyApp
Enter fullscreen mode Exit fullscreen mode

Install iOS dependencies (Mac only):

cd ios && pod install && cd ..
Enter fullscreen mode Exit fullscreen mode

Now continue to Part 4 — Run the App.

Part 4 — Run the App

Note: If you used Expo (Option B, Path 1), follow the Expo commands above instead — you don't need Metro separately.

Step 1: Start Metro (the JS Bundler)

Metro is the JavaScript build tool for React Native — think of it like Vite or Webpack for mobile.

npm start
Enter fullscreen mode Exit fullscreen mode

Or with Yarn:

yarn start
Enter fullscreen mode Exit fullscreen mode

Keep this terminal open. Metro needs to stay running while you use the app.

If you run into cache issues, use: npm start -- --reset-cache

Step 2: Run the App

Open a second terminal in the project folder.

For iOS (Mac only):

npm run ios
Enter fullscreen mode Exit fullscreen mode

This opens the iOS Simulator and builds the app. The first build takes several minutes — this is normal.

For Android:

Make sure your Android Emulator is running first (open it from Android Studio → Device Manager), then:

npm run android
Enter fullscreen mode Exit fullscreen mode

You can also build and run directly from Xcode (iOS) or Android Studio (Android) if you prefer.

Step 3: You're Running!

If everything worked, you should see your app on the simulator/emulator. Here's what to know:

  • Fast Refresh is on by default — when you edit and save a file, the app updates instantly without a full rebuild.
  • Full Reload — if you need to reset the app state:
    • iOS: Press R in the Simulator.
    • Android: Press R twice, or Cmd + M (Mac) / Ctrl + M (Windows) to open the Dev Menu → Reload.
  • Dev Menu — shake the device (or use the keyboard shortcut above) to access debugging tools, element inspector, and more.

Part 5 — Run on a Physical Device (Optional)

Simulators are great for development, but you might want to test on a real phone.

iOS (Physical iPhone/iPad)

  1. Connect your iPhone to your Mac with a USB cable.
  2. Open the .xcworkspace file in the ios/ folder with Xcode.
  3. Select your connected device from the device dropdown (top bar).
  4. Go to Signing & Capabilities → select your Team (a free Apple ID Personal Team works).
  5. Click the Play button in Xcode to build and run.

First time? Your iPhone will ask you to trust the developer certificate. Go to Settings → General → VPN & Device Management on your phone and trust it.

Android (Physical Phone)

  1. On your phone, go to Settings → About Phone → tap Build Number 7 times to enable Developer Mode.
  2. Go to Settings → Developer Options → enable USB Debugging.
  3. Connect your phone to your computer with a USB cable.
  4. Approve the "Allow USB Debugging?" prompt on your phone.
  5. Verify the connection: 
adb devices
Enter fullscreen mode Exit fullscreen mode

You should see your device listed.

  1. Run the app: 
npm run android
Enter fullscreen mode Exit fullscreen mode

It will install directly on your phone instead of the emulator.

Troubleshooting

"Command not found" (node, java, brew, etc.)

Close your terminal completely and open a new one. Shell config changes (~/.zprofile, ~/.zshrc) only take effect in new sessions.

Mac Apple Silicon specific: If brew is not found after installing Homebrew, you missed the PATH setup step. Run:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
Enter fullscreen mode Exit fullscreen mode

iOS build fails with "CocoaPods not found"

Make sure you ran bundle install first. If it still fails:

sudo gem install cocoapods
cd ios && pod install && cd ..
Enter fullscreen mode Exit fullscreen mode

iOS build fails with signing errors

  1. Open the .xcworkspace file inside the ios/ folder using Xcode.
  2. Select your project in the left sidebar.
  3. Go to Signing & Capabilities.
  4. Select your Team (create a free Personal Team with your Apple ID if you don't have one).
  5. Try building again.

iOS build fails when using nvm

If you use nvm to manage Node versions, Xcode can't find Node during builds. Fix it:

  1. Create or edit the file ios/.xcode.env.local in your project: 
export NODE_BINARY=$(which node)
Enter fullscreen mode Exit fullscreen mode
  1. Add the following to ~/.zshenv (not ~/.zshrc): 
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
Enter fullscreen mode Exit fullscreen mode
  1. In Xcode, make sure all Shell Script Build Phases use /bin/zsh as the shell.

Android build fails with "SDK location not found"

Create a file at android/local.properties with this content:

Mac:

sdk.dir=/Users/<YourUsername>/Library/Android/sdk
Enter fullscreen mode Exit fullscreen mode

Windows:

sdk.dir=C:\\Users\\<YourUsername>\\AppData\\Local\\Android\\Sdk
Enter fullscreen mode Exit fullscreen mode

Android Emulator won't start

  • Windows: Make sure Virtualization (VT-x / AMD-V) is enabled in your BIOS/UEFI settings.
  • Mac: Make sure you selected the right system image for your chip (ARM for Apple Silicon, x86 for Intel).

Metro shows "port 8081 already in use"

Something else is using port 8081. Kill it:

Mac:

lsof -i :8081 | grep LISTEN | awk '{print $2}' | xargs kill -9
Enter fullscreen mode Exit fullscreen mode

Windows:

netstat -ano | findstr :8081
taskkill /PID <PID_NUMBER> /F
Enter fullscreen mode Exit fullscreen mode

Build fails after pulling new code

When teammates add new dependencies or change native code, you need to reinstall:

npm install
Enter fullscreen mode Exit fullscreen mode

For iOS, also re-run:

cd ios && bundle exec pod install && cd ..
Enter fullscreen mode Exit fullscreen mode

Then restart Metro with a clean cache:

npm start -- --reset-cache
Enter fullscreen mode Exit fullscreen mode

Nuclear option — clean everything and start fresh

When nothing else works:

Mac:

# Remove all generated files
rm -rf node_modules ios/Pods ios/build android/app/build

# Reinstall everything
npm install
cd ios && bundle exec pod install && cd ..

# Start fresh
npm start -- --reset-cache
Enter fullscreen mode Exit fullscreen mode

Windows:

# Remove generated files
Remove-Item -Recurse -Force node_modules, android\app\build

# Reinstall
npm install

# Start fresh
npm start -- --reset-cache
Enter fullscreen mode Exit fullscreen mode

Quick Reference

Command What It Does
npm install Install JS dependencies
npm start Start Metro bundler
npm start -- --reset-cache Start Metro with cache cleared
npm run ios Build & run on iOS Simulator
npm run android Build & run on Android Emulator
cd ios && bundle exec pod install Install iOS native dependencies
adb devices List connected Android devices

That's it. Your React Native app should be running on your simulator, emulator, or physical device. If you're still stuck, check the official React Native environment setup docs or ask your team.

Happy building!

Top comments (0)