eas-ios-simulator-builds

name	eas-ios-simulator-builds
description	Create and use iOS simulator development builds with EAS for Expo/React Native apps. Use when setting up simulator-only profiles, building, installing, and running dev clients on iOS simulators.
license	MIT
metadata	{"author":"amannhimself.dev"}

EAS iOS Simulator Builds

Overview

How to set up and run iOS simulator development builds with EAS (no Apple credentials required). Focused on creating simulator-only profiles, building, installing, and running the Expo dev client on iOS simulators.

Quick start

• Prereqs: macOS with Xcode + Command Line Tools installed; EAS CLI installed; iOS Simulator available.
• Install expo-dev-client if not present: bunx expo install expo-dev-client.
• Use the simulator profile when building: bunx eas build --profile ios-sim --platform ios.
• Install/run after build: download the .tar.gz, extract the .app, then xcrun simctl install booted path/to.app and xcrun simctl launch booted host.exp.Exponent (or the app bundle ID).

Profile setup (eas.json)

Add a simulator-only profile (no signing):

{
  "build": {
    "ios-sim": {
      "extends": "development",
      "ios": {
        "simulator": true
      }
    }
  }
}

Notes:

• simulator: true ensures a simulator build (no Apple account/signing).
• Keep bundle identifiers consistent with your app config; OTA/runtimeVersion rules still apply.

Build & install

1. Build: bunx eas build --profile ios-sim --platform ios
   • This produces a .tar.gz containing the .app bundle.
2. Extract: tar -xzf <downloaded>.tar.gz
3. Install on a booted simulator: xcrun simctl install booted <path/to>.app
4. Launch: xcrun simctl launch booted <bundleIdentifier> (check your app.config.ts/app.json for the identifier).

Run with your app

• Start the Metro server: bunx expo start (or with your APP_VARIANT env if applicable).
• Open the installed dev client in Simulator and scan the QR or use the Metro URL to load the app.

Troubleshooting

• If the simulator isn’t booted, start one from Xcode or xcrun simctl boot "iPhone 15" before install.
• If the app won’t launch, verify the bundle identifier matches the installed app (simctl get_app_container booted <bundleIdentifier>).
• Clear cache if loading issues: bunx expo start -c.
• If you accidentally build a device build, ensure simulator: true is set in the profile you’re using.