> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Development Setup

> Set up your Mac for iOS development with Soundcheck

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:

```bash theme={null}
chmod +x scripts/setup-ios-dev.sh
./scripts/setup-ios-dev.sh
```

***

## Manual setup

**1. Install Xcode**

Download and install Xcode from the [Mac App Store](https://apps.apple.com/app/xcode/id497799835).

After installation:

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

**2. Install Xcode Command Line Tools**

```bash theme={null}
xcode-select --install
```

**3. Accept Xcode License**

```bash theme={null}
sudo xcodebuild -license accept
```

**4. Install Homebrew**

```bash theme={null}
/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:

```bash theme={null}
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

**5. Install Watchman**

Watchman improves Metro bundler performance:

```bash theme={null}
brew install watchman
```

**6. Install CocoaPods**

```bash theme={null}
brew install cocoapods
```

**7. Configure UTF-8 Encoding**

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

```bash theme={null}
echo 'export LANG=en_US.UTF-8' >> ~/.zshrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.zshrc
source ~/.zshrc
```

**8. Install Project Dependencies**

```bash theme={null}
npm install
```

**9. Generate iOS Native Project**

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

```bash theme={null}
npx expo prebuild --platform ios --clean
```

> [!NOTE]
>
> 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)

```bash theme={null}
# Start Metro bundler
npm start

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

### Option 2: Using npm script

```bash theme={null}
npm run ios
```

### Option 3: Manual build

```bash theme={null}
# 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

```bash theme={null}
# 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

> [accordion] CocoaPods UTF-8 Error
>
> If you see `Unicode Normalization not appropriate for ASCII-8BIT`:
>
> ```bash theme={null}
> export LANG=en_US.UTF-8
> export LC_ALL=en_US.UTF-8
> ```

> [accordion] No Code Signing Certificates
>
> For simulator builds, add `CODE_SIGNING_ALLOWED=NO` to xcodebuild commands. This is not needed for Expo Go.

> [accordion] Simulator Not Found
>
> 1. Open Xcode
> 2. Go to **Xcode → Settings → Components**
> 3. Download an iOS Simulator

> [accordion] Pod Install Fails
>
> ```bash theme={null}
> cd ios
> pod deintegrate
> pod install --repo-update
> ```

> [accordion] Metro Bundler Issues
>
> Clear Metro cache:
>
> ```bash theme={null}
> npx expo start --clear
> ```
>
> Or reset Watchman:
>
> ```bash theme={null}
> watchman watch-del-all
> ```

***

## Resources

* [Expo iOS Simulator Guide](https://docs.expo.dev/workflow/ios-simulator/)
* [React Native Environment Setup](https://reactnative.dev/docs/environment-setup)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.