Setting up environment - Simulators

[EBOD13]

---

Labels: setup dx
Assigned by: Daniel

---

Overview

We are not using Expo Go for this project. All contributors must run the app through a native emulator or simulator using the React Native CLI. This issue ensures everyone's local environment is properly set up before writing any code.

Complete every step for your OS and confirm in a comment that your environment is working.

---

Prerequisites

Make sure you have the following installed before starting:

• Node.js v18 or later
• Git
• A code editor (VS Code recommended)

---

macOS — iOS Simulator setup

1. Install Xcode from the Mac App Store (this takes a while — start it early).

2. Open Xcode → Settings → Locations and confirm the Command Line Tools dropdown is set to the current Xcode version.

3. Open Xcode → Settings → Platforms → add the iOS simulator runtime if not already present.

4. Install CocoaPods:

   sudo gem install cocoapods

5. From the project root, install JS and pod dependencies:

   npm install
   cd ios && pod install && cd ..

6. Start Metro and launch on the iOS Simulator:

   npx react-native start
   # in a second terminal:
   npx react-native run-ios

The app should open in the simulator automatically. If prompted, choose iPhone 15 or later.

---

Windows — Android Emulator setup

1. Install Android Studio from developer.android.com/studio. During setup, make sure Android SDK, Android SDK Platform, and Android Virtual Device are all checked.

2. Open Android Studio → SDK Manager → install:

   • Android SDK Platform 34
   • Android SDK Build-Tools 34

3. Set the ANDROID_HOME environment variable in your system settings:
   ANDROID_HOME = C:\Users\AppData\Local\Android\Sdk
   Also add to your Path:
   %ANDROID_HOME%\emulator
   %ANDROID_HOME%\platform-tools

4. Open AVD Manager in Android Studio → create a new virtual device (Pixel 7, API 34 recommended) → start it.

5. From the project root:

   npm install
   npx react-native start
   # in a second terminal:
   npx react-native run-android

The app should install and launch on your running emulator.

---

Verify your setup

Once the app is running, confirm all of the following:

• The app launches without a red error screen
• Metro bundler is running and shows no errors in the terminal
• Fast Refresh works — make a small text change in any screen file and confirm the simulator/emulator updates without a full rebuild

---

Common issues

pod install fails on macOS
Try sudo arch -x86_64 gem install ffi then re-run pod install.

"SDK location not found" on Windows
Double-check that ANDROID_HOME is set correctly and that you've restarted your terminal after setting environment variables.

Metro bundler port conflict
If port 8081 is in use, run npx react-native start --port 8082 and pass --port 8082 to run-ios / run-android as well.

App crashes immediately on launch
Run npx react-native log-ios or npx react-native log-android to see native logs and share the output in a comment on this issue.

---

Definition of Done

Drop a comment confirming:

1. Your OS and device (e.g. "macOS, iPhone 15 Pro Simulator, iOS 17" or "Windows, Pixel 7 Emulator, API 34")
2. That the app launches and Fast Refresh works
3. Any issues you hit and how you resolved them — helps future contributors