Topic 2: Mac Installation

📖 6 min read · 🎯 beginner · 🧭 Prerequisites: configuring-express, insert-select-update-delete-queries

Why this matters

Before you write a single line of React Native code, your Mac needs the right tools installed — Homebrew, Node, Watchman, Xcode, Android Studio. Skip one, and nothing works. I know that sounds like a lot, but we'll set it up once, in the right order, and you'll never have to think about it again. By the end of this lesson, your Mac will be ready to build and run apps for both iOS and Android. That's the foundation everything else sits on — so let's get it right.

What You'll Learn

Install and verify every prerequisite tool (Homebrew, Node.js, Watchman, Xcode)
Scaffold a new React Native project and navigate its directory
Launch your app on an iOS simulator from within Xcode
Configure Android Studio, create a virtual device, set environment variables, and run the app on an Android emulator

The Analogy

Think of setting up a React Native environment like opening a professional kitchen before the first dinner service. Homebrew is the supply-delivery system that stocks your pantry; Node.js is the industrial stove that actually cooks the JavaScript; Watchman is the smoke detector that notices the moment an ingredient changes; and Xcode plus Android Studio are the two separate ovens — one for Apple-shaped dishes, one for Android-shaped ones. You would not seat guests until every appliance is plugged in, tested, and confirmed hot. That is exactly what this lesson does for your Mac.

Chapter 1: Prerequisites

Before installing anything, confirm you need all four tools:

Homebrew — the package manager for macOS that simplifies installing command-line software
Node.js — the JavaScript runtime that powers the Metro bundler and the React Native CLI
Watchman — a filesystem-watching daemon developed by Meta that detects source-file changes and triggers fast rebuilds
Xcode — Apple's IDE, which bundles the iOS simulator and the build toolchain required to compile native iOS code

Chapter 2: Installing Homebrew

Homebrew is the foundation. Everything else in this lesson flows through it.

Step 1 — Install Homebrew

Open Terminal and paste the official install script:

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

The script will prompt for your macOS password and walk you through each step. Once the prompt returns, Homebrew is ready and you can use the brew command to install any subsequent tool.

Chapter 3: Installing Node.js and Watchman

With Homebrew available, both tools install in a single command each.

Step 1 — Install Node.js

brew install node

Step 2 — Install Watchman

brew install watchman

Watchman is not strictly required to run React Native, but it dramatically speeds up the bundler's file-watching on large projects and is recommended by the official docs.

Chapter 4: Installing Xcode

Xcode provides the iOS simulator, the iOS build toolchain, and the Xcode Command Line Tools that many native dependencies expect.

Step 1 — Install Xcode

Download and install Xcode from the Mac App Store. The download is several gigabytes; plan accordingly.

Step 2 — Install Xcode Command Line Tools

xcode-select --install

A graphical prompt will appear to confirm. Click "Install" and wait for the download to finish. These tools include git, clang, make, and other utilities that native build scripts rely on.

Chapter 5: Installing the React Native CLI

The React Native CLI is the command-line interface used to create and manage React Native projects.

Step 1 — Install React Native CLI globally

npm install -g react-native-cli

Installing globally (-g) makes the react-native command available from any directory in your Terminal session.

Chapter 6: Creating a New React Native Project

With the environment bootstrapped, create a project to verify everything is wired together correctly.

Step 1 — Scaffold the project

npx react-native init MyFirstApp

npx ensures you always run the latest version of the initializer without a separate install step. The command creates a MyFirstApp/ directory with a complete project structure including android/ and ios/ sub-projects.

Step 2 — Navigate to the project directory

cd MyFirstApp

All subsequent react-native commands must be run from inside this directory.

Chapter 7: Running the React Native App on an iOS Simulator

Step 1 — Start the iOS Simulator

Open Xcode.
Go to Xcode → Preferences → Components.
Download the simulator runtime you want (e.g., iOS 14.5).
Go to Xcode → Open Developer Tool → Simulator.
Select a device from Hardware → Device (e.g., iPhone 11).

Step 2 — Run the React Native app on iOS

npx react-native run-ios

This command starts the Metro Bundler (the JavaScript packager) and compiles the native iOS project, then launches the app inside the running simulator. You will see the default React Native welcome screen if everything is configured correctly.

Chapter 8: Running the React Native App on an Android Emulator

Android requires Android Studio, an Android Virtual Device (AVD), and a pair of environment variables.

Step 1 — Install Android Studio

Download and install Android Studio from https://developer.android.com/studio.

Step 2 — Configure the Android SDK

Open Android Studio.
Go to Preferences → Appearance & Behavior → System Settings → Android SDK.
Confirm that the required SDK platforms and SDK tools are checked and installed.

Step 3 — Create an Android Virtual Device (AVD)

Open Android Studio.
Go to Tools → AVD Manager.
Click "Create Virtual Device".
Select a device model and click "Next".
Select a system image (e.g., Pie, Q) and click "Next".
Review the AVD configuration and click "Finish".

Step 4 — Set up environment variables

React Native needs to know where your Android SDK lives. Open Terminal and run:

echo "export ANDROID_HOME=$HOME/Library/Android/sdk" >> ~/.bash_profile
echo "export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools" >> ~/.bash_profile
source ~/.bash_profile

ANDROID_HOME tells the build tools where the SDK is installed. The PATH additions make adb, emulator, and related binaries available at the command line.

Step 5 — Start the Android Emulator

Open Android Studio.
Go to Tools → AVD Manager.
Click the "Play" button next to your created AVD to launch the emulator.

Step 6 — Run the React Native app on Android

With the emulator running, open Terminal in your project directory and execute:

npx react-native run-android

This compiles the native Android project, installs the APK on the emulator, and starts the Metro Bundler if it is not already running.

🧪 Try It Yourself

Task: Create a brand-new React Native project named CouncilApp, run it on the iOS simulator, and change the default welcome text.

Scaffold the project:

npx react-native init CouncilApp
cd CouncilApp

Open App.tsx (or App.js) and find the text that reads "Welcome to React Native". Change it to "Welcome to Vizag".
Start the simulator and run:
```
npx react-native run-ios
```

Success criterion: The iOS simulator displays "Welcome to Vizag" in the centre of the screen with no red error overlay.

🔍 Checkpoint Quiz

Q1. Why does the React Native setup on macOS require both Xcode and Android Studio, rather than just one IDE?

Q2. Given the following Terminal session, what is wrong?

$ npx react-native init MyApp
$ npx react-native run-ios
error: No Xcode installation was found. Make sure you have Xcode installed...

A) Watchman was not installed via Homebrew
B) xcode-select --install was never run and Xcode Command Line Tools are missing
C) ANDROID_HOME is not set
D) The project directory name contains uppercase letters

Q3. After running the snippet below, what does source ~/.bash_profile accomplish?

echo "export ANDROID_HOME=$HOME/Library/Android/sdk" >> ~/.bash_profile
source ~/.bash_profile

A) It restarts the Terminal application
B) It applies the newly written environment variables to the current shell session without reopening Terminal
C) It installs the Android SDK at the specified path
D) It writes the variable to /etc/environment for system-wide access

Q4. A teammate cloned your MyFirstApp repo on a fresh Mac that already has Homebrew but nothing else. List the minimum ordered steps they must complete before npx react-native run-android succeeds.

A1. Xcode provides the iOS simulator and the Apple build toolchain needed to compile and run the iOS target; Android Studio provides the Android SDK, emulator, and toolchain for the Android target. React Native is cross-platform, so both tool chains are necessary to build and test on both platforms.

A2. B) The error message explicitly says no Xcode installation was found, which typically means the Xcode Command Line Tools were never installed. Running xcode-select --install and completing the Xcode Command Line Tools installation resolves this.

A3. B) source (or .) re-executes the file in the current shell process, immediately loading any newly exported variables — like ANDROID_HOME — into the active session without requiring the user to open a new Terminal window.

A4. Minimum ordered steps: (1) brew install node and brew install watchman; (2) Install Xcode from the Mac App Store and run xcode-select --install; (3) npm install -g react-native-cli; (4) Download and install Android Studio, configure the Android SDK, and create an AVD; (5) Set ANDROID_HOME and update PATH in ~/.bash_profile, then source ~/.bash_profile; (6) Start the AVD emulator; (7) cd MyFirstApp && npx react-native run-android.

🪞 Recap

Homebrew is the macOS package manager used to install Node.js and Watchman in a single command each.
Xcode (from the Mac App Store) plus xcode-select --install provide the iOS simulator and native build toolchain.
npm install -g react-native-cli makes the react-native command globally available; npx react-native init <Name> scaffolds a new project.
Android Studio, an AVD, and the ANDROID_HOME / PATH environment variables must all be in place before npx react-native run-android can succeed.
npx react-native run-ios and npx react-native run-android both start the Metro Bundler and deploy the app to the respective simulator or emulator.

📚 Further Reading

React Native Environment Setup — macOS — the official, always-current guide for macOS target platforms
Homebrew Documentation — package manager reference and troubleshooting
Xcode Release Notes — track which simulator runtimes are available in each Xcode version
Android Studio User Guide — AVD Manager, SDK Manager, and emulator configuration in depth
⬅️ Previous: Insert, Select, Update, Delete Queries
➡️ Next: Node Projects