AgentSkillsCN

eas-ios-simulator-builds

使用EAS为Expo/React Native应用创建和使用iOS模拟器开发版本。在设置仅限模拟器的配置文件、构建、安装和运行iOS模拟器上的开发客户端时使用。

SKILL.md
--- frontmatter
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):

jsonc
{
  "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.