iOS

There are two ways to work on the iOS side of a mobile app:

Build on the platform. The platform builds a simulator app you can run on a Mac. It uses an AWS Mac, so it is costly.
Build on your own Mac. Run the app in the iOS Simulator, or on a device, straight from the source with Xcode. This is the everyday way to develop, and it costs nothing extra.

💸

iOS builds on the platform run on bare-metal AWS Mac instances, which are costly, and AWS sometimes has none free. Develop on your own Mac day to day, and use the platform build when you need a build to share. Do the Android side first: see Android Builds.

What the platform builds

The platform produces an unsigned iOS simulator app, delivered as a .zip containing a .app. It runs in the Xcode Simulator on a Mac. It is not an installable iPhone app: running on a real iPhone, TestFlight and the App Store need Apple code signing, which the platform does not set up yet.

Build on the platform

The iOS simulator app section is at the bottom of the same page as the Android build (the microapp’s Mobile app tab, or Mobile in the project sidebar). It has its own status and its own build list, so it never blocks, and is never blocked by, an Android build.

Enable mobile builds first

iOS builds share the setup of the Android app. If you see Enable mobile builds first, enable Android builds once on the same page (see Android Builds) and come back.

Start the build

Optionally enter a Version name (same rules as Android; empty gives 1.0.<build number>), then click Build iOS simulator app.

The first build of the day starts a build Mac and takes about 25 minutes. Later builds that day take about 5 minutes.
If AWS is still preparing a Mac, the build waits. The platform gives up on its own after a long wait and shows the reason; a build that never reports back is marked Failed after about 110 minutes.
Only one iOS build runs at a time.

Download

When the build shows Succeeded, click Simulator app (.zip). Files expire after a limited time.

Run it in the Simulator

On a Mac with Xcode:

Unzip the download to get the .app.
Start a simulator (open Simulator, or boot a device from Xcode).
Install and launch it, using your app’s bundle identifier (the ios.bundleIdentifier in app.json, the same reverse-DNS id as the Android package):


xcrun simctl install booted path/to/YourApp.app
xcrun simctl launch booted <your-bundle-id>

You can also drag the .app onto the Simulator window.

Build on your own Mac

You can use a personal MacBook for development and for compiling the app. You need:

A Mac with Xcode installed from the App Store (open it once to accept the licence and install the iOS Simulator runtime).
Node.js 22 and npm.
Your mobile microapp’s starter (see Create a Mobile App).

Run in the Simulator

In the starter folder:


npm install
npx expo start

Press i to open the iOS Simulator. The app reloads as you edit.

Compile a native build

When you need the real native build (for native modules, or to debug in Xcode):


npx expo run:ios

This generates the ios/ project, compiles it with Xcode and launches the app in the Simulator. To run on a physical iPhone you need an Apple developer account and signing set up in Xcode; follow the Expo documentation for your SDK version at docs.expo.dev .

⚠️

ios/ and android/ are generated by Expo and are listed in .gitignore. Never commit them. Make native changes in app.json or config plugins, so the platform build, which regenerates the native project every time, gets them too.

Develop with Claude Code and Xcode

A workable setup on a Mac:

Open the starter folder in Claude Code. The starter includes CLAUDE.md and the MCP configuration, so the assistant already knows the project, your DaaS and your API.
Keep npx expo start running in a terminal with the Simulator open, so you see every change.
Use Xcode only when you need it: compiling with npx expo run:ios, the debugger, Instruments or signing. Xcode reads the generated ios/ folder.
Ask Claude Code to change the code, app.json and config plugins. Ask it to run npm run typecheck, npx expo lint and npx expo-doctor before you commit.

💡

Expo changes between SDK versions. Check the documentation for the expo version in package.json before you rely on a command or an API, and tell your assistant to do the same.

Troubleshooting

Problem	What to do
Enable mobile builds first is shown	Enable Android builds once on the same page. iOS uses the same setup.
The iOS build is waiting for a long time, or fails after a long wait	AWS may have no Mac capacity free. Try again later, or build on your own Mac.
Build iOS simulator app is greyed out	An iOS build is already running, or you do not have the Admin role on the project.
The `.app` will not install on an iPhone	Expected: it is a simulator build. Use the Simulator, or build for a device yourself with your Apple developer account.
`xcrun simctl install` fails with “No devices are booted”	Start a simulator first, then run the command again.
`npx expo run:ios` fails on signing or the Simulator runtime	Open Xcode once, accept the licence, install an iOS Simulator runtime, and check your Expo SDK’s documentation.
A build is refused with “Mobile was just disabled and its resources are still being removed”	Mobile builds were disabled a moment ago. Wait a few minutes, then start the build again.
Download says File expired	Build again.