iOS Device Setup Guide

iOS Device Setup Guide

This guide will walk you through setting up your development environment to run the Bartendie app on a physical iPhone connected to your Mac.

Prerequisites

1. Mac with Xcode installed (latest version recommended)
2. Physical iPhone connected via USB cable
3. Apple Developer Account (free account works for development)
4. iPhone unlocked and trusted on your Mac

Step 1: Connect Your iPhone

1. Connect your iPhone to your Mac using a USB cable
2. Unlock your iPhone
3. If prompted, tap “Trust This Computer” on your iPhone
4. Enter your iPhone passcode if requested

Step 2: Verify Device Connection

Check that your Mac recognizes your iPhone:

# List all connected iOS devices
xcrun xctrace list devices

You should see your iPhone listed with its name and UDID.

Alternatively, you can check in Xcode:

1. Open Xcode
2. Go to Window → Devices and Simulators (or press Cmd + Shift + 2)
3. Your iPhone should appear in the left sidebar under “Devices”

Step 3: Configure Xcode Signing

1. Open the iOS project in Xcode:

   cd shaker
   open ios/Bartendie.xcworkspace

2. In Xcode:

   • Select the Bartendie project in the navigator
   • Select the Bartendie target
   • Go to the Signing & Capabilities tab
   • Check “Automatically manage signing”
   • Select your Team from the dropdown (your Apple ID)
   • Xcode will automatically create a provisioning profile

3. If you see any errors:

   • Make sure you’re signed in to Xcode with your Apple ID: Xcode → Settings → Accounts
   • Add your Apple ID if it’s not already there
   • For a free account, you may need to accept the Apple Developer Agreement

Step 4: Build and Run on Device

Option 1: Using npm script (Recommended)

The project includes a script that automatically detects your connected device:

cd shaker
npm run ios:device

This will:

• Automatically detect your connected iPhone
• Build the app
• Install it on your device
• Start the Metro bundler

Option 2: Using Expo CLI

cd shaker
npm run start:ios

Then in the Expo Dev Tools, press i to select your device, or scan the QR code with your iPhone’s camera (if on the same network).

Option 3: Using Xcode directly

1. Open the workspace:

   cd shaker
   open ios/Bartendie.xcworkspace

2. In Xcode:

   • Select your iPhone from the device dropdown (next to the play button)
   • Click the Play button (or press Cmd + R)
   • Xcode will build and install the app on your device

Step 5: Trust the Developer Certificate (First Time Only)

When you first launch the app on your iPhone:

1. The app will appear on your home screen
2. When you try to open it, you’ll see: “Untrusted Developer”
3. Go to Settings → General → VPN & Device Management (or Device Management)
4. Tap on your developer certificate (your Apple ID email)
5. Tap “Trust [Your Apple ID]”
6. Confirm by tapping “Trust”
7. Return to the home screen and open the app

Step 6: Configure Network Access (For Development)

Since the app uses --localhost flag, you need to ensure your iPhone can connect to your Mac’s Metro bundler:

Option A: Same Wi-Fi Network (Recommended)

1. Make sure both your Mac and iPhone are on the same Wi-Fi network
2. Find your Mac’s local IP address:

   ipconfig getifaddr en0

3. Update the Metro bundler connection:
   • When Metro starts, it will show a QR code
   • Shake your iPhone to open the developer menu
   • Select “Configure Bundler”
   • Enter your Mac’s IP address (e.g., 192.168.1.100:8081)

Option B: Use USB Connection (Expo)

If using Expo Dev Client, you can use USB connection:

• The --localhost flag may need to be removed for USB tunneling
• Or use expo start --tunnel for a cloud connection

Troubleshooting

Device Not Detected

1. Check USB connection: Try a different cable or USB port

2. Restart services:

   # Kill any running Metro bundlers
   killall node
   
   # Restart
   npm run ios:device

3. Check Xcode: Make sure Xcode is up to date and Command Line Tools are installed:

   xcode-select --install

Build Errors

1. “ld: framework ‘React’ not found” (linker can’t find React-Core-prebuilt):

   Do a full clean and reinstall of iOS native deps:

   cd shaker
   npm run clean
   rm -rf ios/Pods ios/Podfile.lock ios/build
   cd ios
   pod install
   cd ..
   npm run ios:device

   If it still fails, clear Xcode DerivedData then rebuild:

   rm -rf ~/Library/Developer/Xcode/DerivedData
   cd shaker && npm run ios:device

2. Other build failures – clean build folder:

   cd shaker
   npm run clean
   cd ios
   pod install

3. Check signing: Ensure your Apple ID is added in Xcode Settings → Accounts

4. Update CocoaPods:

   cd shaker/ios
   pod install --repo-update

App Crashes on Launch

1. Check device logs in Xcode: Window → Devices and Simulators → Select your device → View Device Logs

2. Verify network connection: Make sure Metro bundler is running and accessible

3. Clear app data: Delete the app from your iPhone and reinstall

Metro Bundler Connection Issues

1. Check firewall: Make sure your Mac’s firewall allows connections on port 8081

2. Use tunnel mode (if on different networks):

   npm run start -- --tunnel

3. Check localhost setting: If using --localhost, ensure both devices are on the same network

Quick Reference Commands

# List connected devices
xcrun xctrace list devices

# Run on connected device (auto-detect)
cd shaker && npm run ios:device

# Start Metro bundler only
cd shaker && npm start

# Clean and rebuild
cd shaker && npm run clean && cd ios && pod install

Next Steps

Once your app is running on your iPhone:

• Hot Reload: Changes to your code will automatically reload on the device
• Debugging: Use React Native Debugger or Chrome DevTools
• Performance: Use Xcode Instruments for performance profiling
• Logs: View device logs in Xcode’s Devices window

Additional Resources

• Expo Development Builds
• React Native iOS Setup
• Xcode Device Management