simiancraft/simiancraft-skills / skills/expo-ios-simulator
expo-ios-simulator
VerifiedRun and drive an Expo / React Native app on the iOS Simulator. Pick an execution mode (Expo Go, dev client, Storybook-mobile, web-on-mobile), build and install a dev client, and clear the recurring Expo/RN prompts that block automation: the push-token alert that stacks until the overlay darkens the screen, the "Open in app?" deep-link dialog, the dev menu, and the element-inspector trap. Sits ON TOP of ios-simulator; failures route to ios-simulator-triage. Project-agnostic; discovers bundle id and scheme from the app config. Use for "run my Expo app on the simulator", "load a dev client", or "drive Storybook on iOS".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| references/development-builds.md | markdown | 4.4 KB |
| references/execution-modes.md | markdown | 2.1 KB |
| references/expo-go.md | markdown | 3.2 KB |
| references/known-prompts.md | markdown | 5.3 KB |
references/development-builds.md
View on GitHub---
title: Development builds
summary: build and install an Expo dev client on the simulator; the expo run:ios device-picker pitfall, the direct xcodebuild + simctl path, Metro readiness, the dev-client deep link, and waiting for the first bundle
status: complete
sources:
- https://docs.expo.dev/guides/local-app-development/ (npx expo run:ios; prebuild, compile, install, launch, and Metro)
- "xcodebuild (Apple; the direct simulator build) and xcrun simctl install/launch/openurl"
- "Observed behavior of npx expo run:ios and the dev-client deep link (reproducible; run to confirm for your Expo version)"
- "Observed behavior of Metro's /status endpoint (packager-status:running) and the first-bundle Bundling banner (reproducible; run to confirm for your Expo version)"
---
# Development builds
Reference for **expo-ios-simulator**. An Expo app with native modules cannot run in
Expo Go; it needs a **development build** (a dev client). This is the build-and-install
half; the prompts and dev menu that follow are in `known-prompts.md`.
## The standard build: expo run:ios
`npx expo run:ios` runs prebuild if `ios/` is missing, installs pods (`pod install`), compiles
with Xcode, installs the binary, launches it, and starts Metro. It is the documented
one-shot path.
## The headless simulator pitfall
`expo run:ios` selects a target device, and driven headlessly it tends to choose a
**physical-device** build, which then fails with `No code signing certificates are
available`. The Expo docs do not cover simulator-vs-device or signing, so for a
reliable simulator build, bypass the picker and drive `xcodebuild` directly (the
`ios/` project already exists after one prebuild + pod install):
```bash
xcodebuild -workspace ios/<App>.xcworkspace -scheme <App> -configuration Debug \
-sdk iphonesimulator -destination "id=<udid>" -derivedDataPath ios/build \
CODE_SIGNING_ALLOWED=NO build
```
The product is `ios/build/Build/Products/Debug-iphonesimulator/<App>.app`. Install that
path with `xcrun simctl install booted <product-path>` (see **ios-simulator**
`references/lifecycle.md`).
## Metro, and connecting the dev client
In practice, with `CI=1`, `expo run:ios` exits after launching and does not keep Metro
alive, so the dev client lands on a "could not connect" screen. Start Metro as its own
persistent process (`CI=1` here too, so it never waits on its interactive terminal UI),
**verify it is serving before launching the app**, then point the dev client at it:
```bash
CI=1 npx expo start --dev-client & # serve Metro on :8081 (its own process)
until curl -s http://localhost:8081/status | grep -q packager-status:running; do sleep 1; done
xcrun simctl launch booted <app-bundle-id> # open the app; it reconnects to Metro
xcrun simctl openurl booted "<scheme>://expo-development-client/?url=http%3A%2F%2Flocalhost%3A8081" # or force a specific Metro URL
```
The deep link raises an "Open in '<App>'?" system dialog when the app is not already
frontmost (launching the app first, as above, can skip it); if it appears, dismiss it by
accessibility, not coordinates: `axe tap --label "Open" --udid <udid>`.
## Wait for the first bundle
The deep link does not make the app interactive: Metro then builds and serves the JS bundle
(a "Bundling NN%..." banner, then the splash screen), which takes tens of seconds cold.
Driving before it finishes taps into a void that still reports success (dispatch is not
confirmation; see **ios-simulator** `references/driving.md`). Wait by polling the
accessibility tree until the app's own labels appear:
```bash
until [ "$(axe describe-ui --udid <udid> | jq '[.. | objects | select(.AXLabel? != null)] | length')" -gt 2 ]; do sleep 3; done
```
A splash screen exposes at most a node or two; a rendered screen exposes many. Then read
what actually rendered (the label inventory one-liner in **ios-simulator**
`references/driving.md`) before the first tap.
Discover `<App>` (scheme and workspace) and `<app-bundle-id>` from `app.config`
(`scheme`, `ios.bundleIdentifier`); never hardcode them. If `app.config` sets no `scheme`,
the dev client registers the fallback `exp+<slug>`, so use
`exp+<slug>://expo-development-client/?url=...`.
## See also
- **ios-simulator** `references/lifecycle.md` (simctl install/launch) and `references/driving.md` (`axe tap`).
- `known-prompts.md`: the dialogs and the dev menu after launch.
- `execution-modes.md`: when a dev client is the right mode versus Expo Go or web.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |