Running the App

This guide covers how to run Rainbow in development mode on iOS and Android.

Prerequisites

Before running the app, ensure you’ve completed:

✅ Prerequisites - Node.js, Ruby, and tools installed
✅ Installation - Dependencies installed with yarn install && yarn setup
✅ iOS Setup or Android Setup - Platform-specific configuration

Development Workflow

The typical development workflow involves two steps:

Start Metro Bundler - JavaScript bundler (like webpack for React Native)
Run on Platform - Build and launch on iOS/Android

Start Metro Bundler

In one terminal, start the Metro bundler:

yarn start

Metro will start and display:

               ######                ######               
             ###     ####        ####     ###             
            ##          ###    ###          ##            
            ##             ####             ##            
            ##             ####             ##            
            ##           ##    ##           ##            
            ##         ###      ###         ##            
             ##  ####                ####  ##             
          ######                        ######            
      ###     ##       ###      ###       ##     ###      
   ###         ## ######## #### ######## ##         ###   
  ##           ####                    ####           ##  
 ##             ###                    ###             ## 
  ##           ####                    ####           ##  
   ###         ## ######## #### ######## ##         ###   
      ###     ##       ###      ###       ##     ###      
          ######                        ######            
             ##  ####                ####  ##             
            ##         ###      ###         ##            
            ##           ##    ##           ##            
            ##             ####             ##            
            ##             ####             ##            
            ##          ###    ###          ##            
             ###     ####        ####     ###             
               ######                ######               

Welcome to Metro!

Keep Metro running in this terminal while developing. It watches for file changes and provides hot reload.

Running on iOS

Command Line (Recommended)
Xcode
Physical Device

Run from terminal:

yarn ios

This:

Builds the app with Xcode
Launches iOS Simulator
Installs and runs Rainbow

The default simulator is iPhone 16 Pro. To use a different device:

# List available simulators
xcrun simctl list devices

# Run on specific device
react-native run-ios --simulator="iPhone 15 Pro Max"

Run from Xcode for more control:

Open workspace

open ios/Rainbow.xcworkspace

Always open Rainbow.xcworkspace, not Rainbow.xcodeproj.

Select scheme and device

In Xcode:

Select Rainbow scheme (top toolbar)
Select target device or simulator (next to scheme)

Build and run

Press Cmd+R or click the Play button.

Using Xcode allows you to:

Debug native code
View native logs
Use Xcode’s debugger
Configure build settings

To run on a physical iOS device:

Connect device

Connect your iPhone/iPad via USB.

Trust computer

On your device, tap Trust when prompted.

Configure signing

In Xcode:

Open ios/Rainbow.xcworkspace
Select Rainbow target
Go to Signing & Capabilities
Select your Team (Apple Developer account)
Xcode will create a provisioning profile

Select device and run

Select your physical device from the device list
Press Cmd+R

You need an Apple Developer account (free or paid) to run on physical devices.

Running on Android

Command Line (Recommended)
Android Studio
Physical Device

Run from terminal:

yarn android

This:

Builds the app with Gradle
Launches emulator (if not already running)
Installs and runs Rainbow

Make sure you have an emulator created or a physical device connected before running.

Run from Android Studio:

Open project

Launch Android Studio from terminal:

# macOS
open -a "Android Studio"

Then open the android/ folder.

Wait for Gradle sync

Let Gradle sync complete (can take a few minutes on first run).

Select device

In Android Studio toolbar:

Select target device from dropdown
Or click Device Manager to start an emulator

Run app

Click the Run button (green play icon) or press Shift+F10.

To run on a physical Android device:

Enable Developer Options

On your Android device:

Go to Settings → About Phone
Tap Build Number 7 times
Return to Settings
Open Developer Options

Enable USB Debugging

In Developer Options:

Enable USB Debugging
Connect device via USB
Tap Allow when prompted on device

Verify connection

adb devices

Your device should be listed.

Reverse ports

Allow device to connect to Metro bundler:

yarn android-reverse-ports

This runs: adb reverse tcp:8081 tcp:8081

Run app

yarn android

Development Features

Hot Reload

When Metro is running, changes to JavaScript/TypeScript files automatically reload:

Fast Refresh: Preserves component state while reloading
Automatic: Saves the file, app updates

Fast Refresh works for most React components. Some changes (like adding new native modules) require a full rebuild.

Access the developer menu:

iOS Simulator: Press Cmd+D
Android Emulator: Press Cmd+M (macOS) or Ctrl+M (Windows/Linux)
Physical Device: Shake the device

Options include:

Reload
Debug
Enable/disable Fast Refresh
Toggle Element Inspector
Show Performance Monitor

Remote Debugging

React DevTools

Install standalone React DevTools:

npm install -g react-devtools
react-devtools

Then open the developer menu and enable Debug.

Chrome DevTools (Legacy)

In developer menu, select Debug to open Chrome DevTools.

Chrome DevTools debugging is deprecated in newer React Native versions. Use React DevTools or Flipper instead.

Flipper

Flipper is a debugging platform for mobile apps:

Download Flipper: https://fbflipper.com/
Build app with Flipper enabled (default)
Open Flipper while app is running

Features:

Network inspector
React DevTools
Logs viewer
Layout inspector

Element Inspector

Inspect UI elements:

Open developer menu
Select Toggle Element Inspector
Tap elements to see details (styles, props, etc.)

Environment-Specific Builds

Development Mode

Default mode when running yarn ios or yarn android:

Hot reload enabled
Developer menu accessible
No optimizations
Larger bundle size

Release Mode

Run in release mode for performance testing:

yarn ios --mode Release

Release mode:

✅ Full optimizations
✅ Smaller bundle size
✅ Production-like performance
❌ No hot reload
❌ No developer menu

Use release mode when testing performance or E2E tests. Set IS_TESTING=true in .env for E2E tests.

Multiple Devices

Run on All Android Devices

Run on all connected Android devices:

# Reverse ports on all devices
yarn android-reverse-ports-all

# Install APK on all devices
yarn android-all:apk

Switch Between Devices

iOS: Select different simulator in Xcode or use --simulator flag. Android: If multiple devices are connected, specify device:

# List devices
adb devices

# Run on specific device
adb -s <device_id> install app.apk

Troubleshooting

Metro bundler fails to start

Clear watchman and Metro cache:

yarn clean:packager
yarn start --reset-cache

iOS build fails with 'Command PhaseScriptExecution failed'

Node is not in Xcode’s PATH:

Close Xcode
Run nvm use in terminal
Open Xcode from terminal: open ios/Rainbow.xcworkspace

Android build fails with 'Cannot run program node'

Android Studio doesn’t have node in PATH:

Close Android Studio
Launch from terminal: open -a "Android Studio"
Reopen the android/ folder

App crashes immediately on launch

Check Metro bundler is running:

yarn start

View logs:

iOS: Xcode console or react-native log-ios
Android: Android Studio logcat or react-native log-android

Red screen: 'Unable to connect to development server'

iOS: Ensure Metro is running and simulator can reach localhost.Android: Reverse ports:

yarn android-reverse-ports

Hot reload not working

Check Metro is running
Open developer menu
Ensure Fast Refresh is enabled
Try manual reload: Cmd+R (iOS) or R+R (Android)

Clean build and retry

If issues persist, clean everything:

# Full clean
./scripts/nuke.sh

# Reinstall
yarn install && yarn setup
yarn install-pods  # iOS only

# Rebuild
yarn ios  # or yarn android

Performance Tips

Use release mode for accurate performance testing
Disable Remote JS Debugging (it slows down the app significantly)
Use Flipper or React DevTools instead of Chrome DevTools
Profile with React DevTools Profiler
Monitor performance with yarn shopify:perf if using Shopify performance tools

Introduction

Setup

Development

Prerequisites

Development Workflow

Start Metro Bundler

Running on iOS

Running on Android

Development Features

Hot Reload

Developer Menu

Remote Debugging

React DevTools

Chrome DevTools (Legacy)

Flipper

Element Inspector

Environment-Specific Builds

Development Mode

Release Mode

Multiple Devices

Run on All Android Devices

Switch Between Devices

Troubleshooting

Performance Tips

Next Steps

Building

Debugging

Build docs developers (and LLMs) love

Introduction

Setup

Development

​Prerequisites

​Development Workflow

​Start Metro Bundler

​Running on iOS

​Running on Android

​Development Features

​Hot Reload

​Developer Menu

​Remote Debugging

​React DevTools

​Chrome DevTools (Legacy)

​Flipper

​Element Inspector

​Environment-Specific Builds

​Development Mode

​Release Mode

​Multiple Devices

​Run on All Android Devices

​Switch Between Devices

​Troubleshooting

​Performance Tips

​Next Steps

Building

Debugging

Build docs developers (and LLMs) love

Prerequisites

Development Workflow

Start Metro Bundler

Running on iOS

Running on Android

Development Features

Hot Reload

Developer Menu

Remote Debugging

React DevTools

Chrome DevTools (Legacy)

Flipper

Element Inspector

Environment-Specific Builds

Development Mode

Release Mode

Multiple Devices

Run on All Android Devices

Switch Between Devices

Troubleshooting

Performance Tips

Next Steps