Set up iOS development environment for React Native/Expo. Use when configuring Xcode, CocoaPods, iOS simulators, or troubleshooting iOS-specific build issues. Invoked by: "ios setup", "xcode", "cocoapods", "ios environment", "ios simulator".
Version: 1.0.0 Last Updated: 2026-01-11 Status: Active
Note: This is a template. Replace placeholders like
{PROJECT_NAME},{WORKSPACE_NAME}, and{BUNDLE_ID}with your actual project values.
Configure a complete iOS development environment for building and running the mobile app on iOS simulators and physical devices. This guide covers Xcode installation, command line tools, CocoaPods, watchman, and simulator configuration.
ALWAYS: Setting up new Mac for iOS development, Xcode installation, CocoaPods issues, simulator configuration, code signing setup SKIP: Android-only development, Windows/Linux environments (iOS requires macOS)
xcode-select --installbrew install watchmancurl https://get.volta.sh | bash && volta install node@20task run-ios┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Install Xcode │────>│ Setup CLI │────>│ Install │
│ (App Store) │ │ Tools │ │ Dependencies │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
v
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Run on │<────│ Configure │<────│ Setup │
│ Simulator │ │ Simulator │ │ Node/Ruby │
└─────────────────┘ └─────────────────┘ └─────────────────┘
| Phase | Description | Time |
|---|---|---|
| 1 | Install Xcode | 30-60 min |
| 2 | Setup CLI Tools | 5 min |
| 3 | Install Dependencies | 10 min |
| 4 | Configure Simulator | 5 min |
| 5 | Verify Installation | 5 min |
After installation, open Xcode once to:
# Verify Xcode installation
xcodebuild -version
# Expected: Xcode 15.x or later
xcode-select --install
A dialog will appear. Click Install to proceed.
xcode-select -p
# Expected: /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
Watchman is required for React Native's Metro bundler to efficiently watch file changes.
brew install watchman
Verify installation:
watchman version
Volta provides automatic version switching for Node.js:
# Install Volta
curl https://get.volta.sh | bash
# Restart terminal, then install Node 20
volta install node@20
# Pin project to Node 20
volta pin node@20
Verify:
node --version # Should show v20.x.x
volta --version # Should show version info
CocoaPods is managed automatically by Expo, but you can install manually if needed:
sudo gem install cocoapods
Ruby is required for CocoaPods:
ruby --version # Should be available on macOS
gem --version # Should be available
If Ruby issues occur:
brew install ruby
ccache dramatically speeds up C/C++ compilation for native iOS builds.
# Install ccache
brew install ccache
# Add to PATH (add to ~/.zshrc)
export PATH="/opt/homebrew/opt/ccache/libexec:$PATH"
# Verify installation
ccache --version
ccache -s # Show statistics
Important: To use ccache with Xcode, launch Xcode from terminal:
xed ios/{WORKSPACE_NAME}.xcworkspace
From Xcode:
From terminal:
open -a Simulator
xcrun simctl list devices
When running task run-ios, Expo will prompt you to select a simulator. You can also specify directly:
# Run on specific simulator
expo run:ios --device "iPhone 15 Pro"
# Check Node version
node --version
# Check Watchman
watchman version
# Check Xcode tools
xcode-select -p
# Check Homebrew
brew --version
# Check Ruby
ruby --version
# Ensure environment is set up
task setup-dev
# Run on simulator (SIMULATOR=1 is default in .env.example)
task run-ios
# Ensure environment is set up
task setup-dev
# Run on simulator (SIMULATOR=1 is default in .env.example)
task run-ios
The SIMULATOR environment variable controls code signing:
| Value | Target | Code Signing |
|---|---|---|
SIMULATOR=1 | iOS Simulator | Not required (default) |
SIMULATOR=0 | Physical device | Required |
Your .env.local file is created by:
task setup-local-env
To switch targets, edit .env.local:
SIMULATOR=1 # For simulator (default)
SIMULATOR=0 # For physical device
Then rebuild: task run-ios
Recommended for development:
ios/{WORKSPACE_NAME}.xcworkspace in XcodeFor production builds, use EAS Build which handles signing automatically:
task eas-build-ios
SIMULATOR=0 in your .env filetask run-ios
If you encounter strange build issues:
rm -rf ~/Library/Developer/Xcode/DerivedData
Or in Xcode: Xcode > Settings > Locations > Derived Data (click arrow to open in Finder, then delete contents).
# Reset all simulators
xcrun simctl shutdown all
xcrun simctl erase all
# In a separate terminal while app is running
xcrun simctl spawn booted log stream --level debug --predicate 'subsystem == "{BUNDLE_ID}"'
# Run on simulator
task run-ios
# Build native project only (no run)
task build-ios
# Regenerate native project
task generate
# Clean and rebuild
task clean
task generate
task run-ios
# List available simulators
xcrun simctl list devices
# Open simulator
open -a Simulator
# Reset simulator
xcrun simctl erase all
# For simulator (no code signing)
SIMULATOR=1
# For physical device (requires signing)
SIMULATOR=0
| Issue | Solution |
|---|---|
| "No signing certificate" error | Set SIMULATOR=1 in .env for simulator; configure signing in Xcode for device |
| "Command PhaseScriptExecution failed" | Run cd ios && pod deintegrate && pod install && cd .. |
| Simulator not appearing | Run killall Simulator && open -a Simulator |
| Build taking too long | Verify ccache is enabled: ccache -s, use task generate-soft for incremental prebuild |
| ccache not working | Launch Xcode from terminal: xed ios/*.xcworkspace |
| Xcode not found | Install Xcode from App Store |
| xcode-select path wrong | Run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer |
| CocoaPods version mismatch | Run sudo gem install cocoapods to update |
| Metro bundler not connecting | Ensure pnpm start is running in a separate terminal |
Push notifications require:
For development without push notifications, the placeholder Firebase credentials work fine.
See /setup-env skill for Firebase setup details.
| Skill | Purpose | When to Use |
|---|---|---|
/setup-dev | Full environment setup | Complete development environment |
/setup-android | Android environment | Setting up Android development |
/setup-env | Environment variables | Configuring .env files |
/help | Issue diagnosis | When encountering build errors |
/deploy | App deployment | Building for App Store |
Note: Skill paths (
/skill-name) work after deployment. In the template repo, skills are in domain folders.
End of SOP