Building for iOS and Shipping to TestFlight
After this chapter you will be able to take an Expo project and put a build into the hands of a tester on a physical iPhone. You will configure the application’s identity, define the build profiles, run a cloud build with EAS Build, create the App Store Connect record, submit the build with eas submit, and understand how over-the-air updates differ from a new release.
| Requirement | Why it is needed |
|---|---|
| An Expo account | EAS Build runs your build on Expo’s infrastructure under your account |
| A paid Apple Developer Program membership | TestFlight distribution requires it; a free account can only install on your own device for a limited period |
| A unique bundle identifier | The identity of your app in the App Store; it can never be changed after the first upload |
The configuration in app.json or app.config.ts | The bundle identifier, the version and the build number live there |
| An App Store Connect app record | Required before anything can be uploaded |
Start by authenticating the CLI.
eas login
If your organisation uses single sign-on, use eas login --sso instead.
Three values have to line up, and every one of them is in the configuration file.
{
"expo": {
"name": "Field Notes",
"slug": "field-notes",
"version": "1.0.0",
"ios": {
"bundleIdentifier": "com.example.fieldnotes",
"buildNumber": "1",
"supportsTablet": true,
"infoPlist": {
"NSCameraUsageDescription": "Field Notes uses the camera to photograph equipment."
}
}
}
}
- name - the display name on the home screen.
- bundleIdentifier - the reverse-DNS identifier. It must be unique across the App Store, and once the app has been uploaded it is permanent.
- version - the marketing version the App Store displays. Users see it on the store page.
- buildNumber - the build version, which must increase for every upload. TestFlight will refuse two builds with the same number.
If you prefer a typed configuration file, the same values live in app.config.ts:
import type { ExpoConfig } from 'expo/config';
const config: ExpoConfig = {
name: 'Field Notes',
slug: 'field-notes',
version: '1.0.0',
ios: {
bundleIdentifier: 'com.example.fieldnotes',
buildNumber: '1',
},
};
export default config;
You can check what the CLI actually resolved with npx expo config --type public.
eas build:configure
The command creates eas.json and writes a sensible starting point into it.
{
"cli": {
"version": ">= 5.0.0"
},
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal",
"ios": {
"simulator": true
}
},
"production": {
"autoIncrement": true,
"distribution": "store"
}
},
"submit": {
"production": {}
}
}
Three profiles, three purposes:
- development builds an app with a development client, so you can use libraries that need a custom native build. It is installed on registered devices, not distributed through TestFlight.
- preview builds an internal release for the team. Turning on the simulator option produces a build for the simulator, which cannot be installed on a physical device.
- production builds the binary that goes to TestFlight and the App Store.
autoIncrementmakes the build number go up by one on every build, so you never upload the same number twice.
eas build --platform ios --profile production
The CLI uploads your project, builds it on a remote machine, signs it with your distribution certificate, and prints a link to the finished artifact. On a first run it asks for an Apple Developer account and creates the certificates and the provisioning profile for you.
The build log is the same log you would see in Xcode, and it is where a native compilation error surfaces. Two things are worth knowing:
- The remote machine runs a specific Xcode version, and that version is listed at the top of the log. If your local Xcode is newer, your local build can succeed while the cloud build fails.
- You can build on your own machine with
eas build --local, which uses the same profile and the same configuration but compiles with your local Xcode. It is slower and it needs your machine, but it removes the version difference from the equation.
Certificates are managed for you:
eas credentials --platform ios
That command lists the credentials EAS has created, and lets you revoke or recreate them.
The build can be produced without it, but it cannot be uploaded until the app record exists.
In App Store Connect, create a new app and enter:
- the name, which must be unique on the store;
- the bundle identifier, typed exactly as it appears in your configuration - a mismatch here is the most common cause of a failed upload;
- a SKU, an internal string that identifies the build;
- the primary language;
- the access groups your app needs, if any.
The first time you run eas submit, the CLI offers to create an App Store Connect API key for you, which is the simplest way to authorise uploads.
eas submit --platform ios
The command asks which build to upload, or you can point it at one explicitly. When the upload finishes, the build appears in App Store Connect under the app’s TestFlight tab.
The build is processed before it becomes available. Processing usually takes a few minutes and can take longer the first time, because Apple runs additional checks on a new build.
TestFlight has two tester groups, and the difference matters for planning a release.
| Internal testers | External testers | |
|---|---|---|
| How many | Up to 100 | Up to 10,000 |
| Who | Members of your team and your organisation | Anyone you invite by email |
| Review | None; builds are available within minutes | The first build of each version goes through Beta App Review |
| Setup | Add the tester in App Store Connect | Add the tester in the TestFlight app |
Internal testers are the fast loop: install the build, test it, ship a fix as an over-the-air update. External testers are for release candidates, and the Beta App Review step has to be scheduled in advance.
An over-the-air update ships JavaScript and assets to apps that are already installed. It is the feature that changes how a team works, because a fix no longer waits for a store review.
Two things have to be true.
The app needs a runtime version. The runtime version is a string in the configuration that identifies a set of binaries that can exchange updates. It goes in app.json.
{
"expo": {
"runtimeVersion": "1.0.0"
}
}
The update must not contain native code. If the update needs a new native module, a new permission, or a changed native configuration, it needs a new binary. The runtimeVersion is the mechanism that prevents a broken update from reaching an incompatible binary.
# Publish an update to the production branch.
eas update --branch production --message "Fix the rounded total on the checkout screen"
The update is published to a branch, and branches are connected to channels, which the installed app subscribes to. A common setup is a production channel for released apps and a preview channel for internal builds, so testers always run the newest code and users only get what you intend them to have.
When the problem is in native code, build locally.
# Generate the native project from the configuration.
npx expo prebuild
# Build, install and launch on the simulator or a connected device.
npx expo run:ios
run:ios compiles the native project with Xcode, installs the app and starts the bundler. The generated ios/ directory is a normal Xcode project, so you can open it directly and attach the debugger.
The loop is: change the configuration, run npx expo prebuild, then npx expo run:ios again. If you have edited the generated project by hand, npx expo prebuild --clean discards those edits and regenerates the project, so keep manual changes in a config plugin instead.
EAS Build is designed to run from CI, and the CLI authenticates with a personal access token instead of an interactive login.
# In your CI secret store, create a token with `eas token` and store it as EXPO_TOKEN.
export EXPO_TOKEN="your-token-here"
eas build --platform ios --profile production --non-interactive
A typical pipeline builds on every pull request, submits the production profile on a release tag, and publishes an over-the-air update for anything that only touches JavaScript.
| Symptom | Cause | Fix |
|---|---|---|
| The upload is rejected with a bundle identifier mismatch | The App Store Connect record has a different identifier from the configuration | Make the two identical; the identifier cannot be changed after the first upload |
| The upload is rejected as a duplicate build | The build number did not increase | Turn on autoIncrement in the profile, or bump buildNumber manually |
| The build fails on a missing symbol that compiles locally | The cloud Xcode version differs from yours | Read the Xcode version at the top of the build log, or use eas build --local |
| A library works in the simulator but not on a device | The package ships native code and needs a development build | Run npx expo run:ios instead of using Expo Go |
| An update does not reach installed apps | The installed build has a different runtime version, or the channel does not match | Check runtimeVersion and the channel the build is subscribed to |
| The build installs but the camera permission is missing | The usage description was not declared in the configuration | Add it to ios.infoPlist and rebuild |
Your team wants a weekly release candidate for the QA team, plus a hot-fix channel for production. Set up the configuration and the commands, and describe what happens when a fix touches native code.
Approach:
Two channels with two different needs. The release candidate must be a real binary that QA can install, so it is a TestFlight build made with a preview profile and distributed to internal testers. The hot fix must reach users without a store review, so it is an EAS Update published to a branch that the released app’s channel follows. The rule that decides between them is whether the change touches native code.
Steps:
- Declare the identity once. Set
bundleIdentifier,versionandbuildNumberin the configuration, and give the app aruntimeVersionthat changes whenever a native change requires a new binary. - Define the profiles. A
previewprofile withdistribution: "internal"produces the weekly candidate; aproductionprofile withautoIncrementanddistribution: "store"produces the binary that goes to the App Store. - Run the weekly build.
eas build --platform ios --profile previewproduces a signed internal build that appears in TestFlight for the internal testers without any review. - Create the App Store Connect record once. The name, bundle identifier and SKU must exist before anything can be uploaded, and the identifier must match the configuration exactly.
- Publish the hot fix.
eas update --branch production --message "..."sends the JavaScript change to the devices on the production channel. No store review, no rebuild. - Know when the update path stops working. If the fix needs a new native module, a new permission or a changed native configuration, the update cannot be delivered as JavaScript. The runtime version must be bumped, a new binary built with
eas build --platform ios --profile production, and the binary submitted witheas submit --platform ios.
Answer:
{
"expo": {
"name": "Field Notes",
"slug": "field-notes",
"version": "1.4.0",
"runtimeVersion": "1.4.0",
"ios": {
"bundleIdentifier": "com.example.fieldnotes",
"buildNumber": "42"
}
}
}{
"cli": { "version": ">= 5.0.0" },
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal"
},
"production": {
"autoIncrement": true,
"distribution": "store"
}
},
"submit": {
"production": {}
}
}# Weekly release candidate for QA, installed from TestFlight by internal testers.
eas build --platform ios --profile preview
# Hot fix that only changes JavaScript and assets.
eas update --branch production --message "Fix the rounded total on the checkout screen"
# A change that touches native code: new binary, new runtime version, new upload.
# 1. Bump "runtimeVersion" to "1.5.0" in the configuration.
# 2. Build and submit.
eas build --platform ios --profile production
eas submit --platform iosThe rule the team should write down: a JavaScript-only change ships as an EAS Update and reaches users in minutes; a change that touches native code ships as a new binary and goes through TestFlight. The runtime version is what makes the distinction enforceable, because an update built for one runtime version never reaches a binary built for another.
