Skip to main content
iOS development requires macOS. If you’re on Windows or Linux, skip to Android Setup.

​
Prerequisites

Before setting up iOS, ensure you have:
  • ✅ Prerequisites installed (Node.js, Ruby)
  • ✅ Dependencies installed (yarn install && yarn setup)
  • 💻 macOS (iOS development is only possible on macOS)

​
Installation Steps

1

Install Xcode

Download and install Xcode from the Mac App Store:
  1. Open the Mac App Store
  2. Search for “Xcode”
  3. Click Install (this is a large download, ~10-15 GB)
  4. Wait for installation to complete
After installation, open Xcode at least once to:
  • Accept the license agreement
  • Install additional components
  • Set up command line tools
You can also install Xcode Command Line Tools separately:
xcode-select --install
2

Install Watchman

Watchman is a file watching service used by React Native’s Metro bundler:
brew install watchman
Verify installation:
watchman --version
3

Install Bundler

Bundler manages Ruby dependencies (Fastlane, CocoaPods):
yarn install-bundle
This runs bundle install using the Gemfile.
4

Install CocoaPods Dependencies

Install iOS native dependencies with CocoaPods:
yarn install-pods
The first install-pods can take 10-30 minutes depending on your Mac’s speed and internet connection. Subsequent installs are much faster.

​
What Gets Installed

The CocoaPods installation installs numerous iOS dependencies:
  • Firebase - Analytics, messaging, and remote config
  • React Native core - RN iOS framework
  • Native modules - All React Native modules (camera, storage, etc.)
  • Reanimated - Animation library native code
  • Skia - Graphics rendering engine
  • Various pods - Networking, crypto, Bluetooth, and more

​
Verify iOS Setup

1

Check Xcode installation

xcodebuild -version
Should output Xcode version (15.0+).
2

Verify Pods installed

ls -la ios/Pods/
You should see numerous pod directories.
3

Open workspace in Xcode

open ios/Rainbow.xcworkspace
Always open Rainbow.xcworkspace, not Rainbow.xcodeproj. The workspace includes CocoaPods dependencies.

​
CocoaPods Configuration

Rainbow’s ios/Podfile has specific configurations:

​
Platform Version

platform :ios, '15.1'
Minimum iOS version is 15.1.

​
Modular Headers

Firebase pods use modular headers: 
pod 'Firebase', :modular_headers => true
pod 'FirebaseCore', :modular_headers => true
pod 'FirebaseRemoteConfig', :modular_headers => true

​
Expo Autolinking

Expo modules are auto-linked: 
require File.join(File.dirname(`node --print "require.resolve('expo/package.json')"`), "scripts/autolinking")

​
VisionCamera Configuration

Location API is disabled: 
$VCEnableLocation = false

​
Troubleshooting

Make sure you’re using the correct Ruby version (3.4.8):
ruby --version
which ruby  # Should NOT be /usr/bin/ruby
Use rbenv or rvm to install Ruby 3.4.8 (see Prerequisites).
Update your CocoaPods repo:
cd ios
bundle exec pod repo update
bundle exec pod install
This often means Node.js isn’t in Xcode’s PATH. The build scripts need node.
  1. Ensure you ran nvm use before opening Xcode
  2. Close Xcode completely
  3. Open Xcode from terminal: 
    open ios/Rainbow.xcworkspace
Alternatively, add nvm to your shell profile so it’s always available.
The iOS Simulator might be corrupted. Try:
  1. Quit Xcode and Simulator
  2. Reset simulators: 
    xcrun simctl erase all
  3. Restart Xcode
If you get outdated pod warnings:
cd ios
bundle exec pod install --repo-update
cd ..
Flipper can cause build issues. Try installing without Flipper:
yarn install-pods-no-flipper
If you encounter persistent build issues, clean everything:
# Clean iOS builds and pods
yarn clean:ios

# Reinstall pods
yarn install-pods
In Xcode:
  1. Product → Clean Build Folder (Cmd+Shift+K)
  2. Close Xcode
  3. Delete derived data: 
    rm -rf ~/Library/Developer/Xcode/DerivedData
  4. Reopen Xcode and rebuild

​
Gemfile Dependencies

The Gemfile specifies: 
ruby '>= 2.7.0'

gem "fastlane"
gem 'cocoapods', '>= 1.13', '!= 1.15.0', '!= 1.15.1'
gem 'activesupport', '>= 6.1.7.5', '<7.1.0'
gem 'bigdecimal'
  • fastlane - iOS build automation
  • cocoapods - Dependency manager (excludes problematic versions 1.15.0/1.15.1)
  • activesupport - Rails utilities
  • bigdecimal - Required for Ruby 3.4+

​
Alternative Installation Methods

​
JavaScript Core (JSC) Instead of Hermes

By default, Rainbow uses Hermes. To use JSC: 
yarn install-pods-fast-jsc
This sets USE_HERMES=NO during pod install.

​
Skip Flipper

For faster builds without the Flipper debugger: 
yarn install-pods-no-flipper

​
Next Steps

Android Setup

Set up Android development (optional)

Running the App

Build and run Rainbow on iOS

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us