iOS Development Setup

This guide will help you set up your Mac for iOS development with the Soundcheck mobile app.

Prerequisites

macOS (required for iOS development)
Xcode (from Mac App Store)
Node.js v20+ (via nvm recommended)

Quick setup (automated)

Run the setup script:

chmod +x scripts/setup-ios-dev.sh
./scripts/setup-ios-dev.sh

Manual setup

Install Xcode

Download and install Xcode from the Mac App Store.After installation:

Open Xcode
Go to Xcode → Settings → Components
Install an iOS Simulator (e.g., iOS 17 or later)

Install Xcode Command Line Tools

xcode-select --install

Accept Xcode License

sudo xcodebuild -license accept

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

For Apple Silicon Macs (M1/M2/M3), add to your shell profile:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Install Watchman

Watchman improves Metro bundler performance:

brew install watchman

Install CocoaPods

brew install cocoapods

Configure UTF-8 Encoding

CocoaPods requires UTF-8 encoding. Add to your ~/.zshrc:

echo 'export LANG=en_US.UTF-8' >> ~/.zshrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.zshrc
source ~/.zshrc

Install Project Dependencies

npm install

Generate iOS Native Project

The ios/ directory must be generated locally from app.config.js:

npx expo prebuild --platform ios --clean

The --clean flag removes any existing ios/ folder before regenerating. All native configuration comes from app.config.js. EAS Build runs this automatically during CI.

Running the app

Option 1: Using Expo (recommended)

# Start Metro bundler
npm start

# In the Expo CLI, press 'i' to open iOS Simulator

Option 2: Using npm script

npm run ios

Option 3: Manual build

# Open Simulator first
open -a Simulator

# Build the app
cd ios
xcodebuild -workspace soundcheck.xcworkspace \
  -scheme Soundcheck \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  CODE_SIGNING_ALLOWED=NO \
  build

# Install on simulator
xcrun simctl install booted build/Build/Products/Debug-iphonesimulator/Soundcheck.app

# Launch the app
xcrun simctl launch booted com.soundchecklive.app

# Go back to project root and start Metro
cd ..
npm start

Development builds vs Expo Go

Feature	Development Build	Expo Go
SecureStore	✅ Full support	❌ Limited
Notifications	✅ Full support	❌ Limited
Custom native code	✅ Yes	❌ No
Setup complexity	Higher	Lower

For full app functionality, use Development Build. For quick prototyping, Expo Go works but some features (auth tokens, push notifications) may not work correctly.

Useful commands

# List available simulators
xcrun simctl list devices available

# Boot a specific simulator
xcrun simctl boot "iPhone 16 Pro"

# Open Simulator app
open -a Simulator

# Check Xcode path
xcode-select -p

# Check installed tools
watchman --version
pod --version
node --version

Troubleshooting

CocoaPods UTF-8 Error

If you see Unicode Normalization not appropriate for ASCII-8BIT:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

No Code Signing Certificates

For simulator builds, add CODE_SIGNING_ALLOWED=NO to xcodebuild commands. This is not needed for Expo Go.

Simulator Not Found

Open Xcode
Go to Xcode → Settings → Components
Download an iOS Simulator

Pod Install Fails

cd ios
pod deintegrate
pod install --repo-update

Metro Bundler Issues

Clear Metro cache:

npx expo start --clear

Or reset Watchman:

watchman watch-del-all

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

iOS Development Setup

Prerequisites

Quick setup (automated)

Manual setup

Running the app

Option 1: Using Expo (recommended)

Option 2: Using npm script

Option 3: Manual build

Development builds vs Expo Go

Useful commands

Troubleshooting

Resources

​Prerequisites

​Quick setup (automated)

​Manual setup

​Running the app

​Option 1: Using Expo (recommended)

​Option 2: Using npm script

​Option 3: Manual build

​Development builds vs Expo Go

​Useful commands

​Troubleshooting

​Resources

Prerequisites

Quick setup (automated)

Manual setup

Running the app

Option 1: Using Expo (recommended)

Option 2: Using npm script

Option 3: Manual build

Development builds vs Expo Go

Useful commands

Troubleshooting

Resources