How I Set Up My Local Environment to Run a React Native iOS App

Setting up a React Native project for iOS locally sounds simple—until you hit the usual roadblocks: Ruby versions, CocoaPods issues, Xcode configuration, and mysterious build failures. Here’s a clean, real-world setup that actually works.

🍎 Step 0 — Prepare Xcode (Critical but Easy to Miss)

Even if you already installed Xcode from the App Store, your system may not be fully configured for command-line builds. I ran into issues until I completed these steps:

1. Select the Correct Xcode Path

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p

Expected output:

/Applications/Xcode.app/Contents/Developer

2. Accept the Xcode License

sudo xcodebuild -license

Then:

• Press space to scroll through the license
• Type agree at the end

Without this, builds may fail silently or with confusing errors.

3. Install Command Line Tools (if not already)

xcode-select --install

React Native iOS builds rely on Xcode toolchain and iOS SDKs. Proper configuration prevents pod install or build failures.

🧰 Step 1 — Understand Your Ruby Setup

Check which Ruby you are actually using:

which ruby
ruby -v

If it shows something like:

~/.rbenv/shims/ruby
ruby 2.7.6

This means rbenv is managing your Ruby, not system or Homebrew Ruby.

🚀 Step 2 — Install a New Ruby Version with rbenv

rbenv install 3.3.0
rbenv global 3.3.0
rbenv rehash
ruby -v

📦 Step 3 — Install CocoaPods

gem install cocoapods
pod --version

📁 Step 4 — Install iOS Dependencies

cd ios
pod install

🔄 Step 5 — Update Pod Repositories (If Needed)

pod repo update
# or combine with install
pod install --repo-update

⚠️ Common Issues and Fixes

• pod install fails: run pod repo update
• CocoaPods not found: run gem install cocoapods and rbenv rehash
• Ruby version not changing: make sure rbenv is active with eval "$(rbenv init -)"
• Permission errors with gem: avoid sudo, use rbenv-managed Ruby

🧼 Optional Cleanup

If you installed Ruby via Homebrew but don’t use it:

brew uninstall ruby

This avoids confusion since rbenv is managing Ruby versions.

✅ Final Workflow Summary

# Install Ruby
rbenv install 3.3.0
rbenv global 3.3.0

# Install CocoaPods
gem install cocoapods

# Install iOS dependencies
cd ios
pod install --repo-update

💡 Key Takeaways

• CocoaPods depends on Ruby → keep Ruby updated
• rbenv overrides system and Homebrew Ruby
• brew upgrade ruby does NOT affect rbenv
• Always run pod install inside the ios folder
• Use pod repo update when dependencies fail

🎯 Final Thoughts

The biggest confusion came from having multiple Ruby environments: system Ruby, Homebrew Ruby, and rbenv Ruby. Once I realized rbenv was in control, everything became predictable. If you're working with React Native and iOS, a clean Ruby + CocoaPods setup will save you hours of debugging.

❤️ Support This Blog

---

If this post helped you, you can support my writing with a small donation. Thank you for reading.

---

Coffee ☕ Thanks 🙏 Extra Support ❤️