npx testflight command purpose and scope
The npx testflight CLI tool is a single command that walks you through building, signing, and submitting your iOS app to TestFlight in an interactive workflow.
end-to-end workflow
70 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
npx testflight advantages
The npx testflight command saves developer time by eliminating separate build-and-submit steps, handles Apple credentials and provisioning profiles through guided prompts with EAS CLI, produces a new build and submits it to TestFlight without running separate commands, and works well on shared machines or CI runners where installing global packages is inconvenient.
When to use npx testflight
Use npx testflight to ship a TestFlight build quickly from your local machine, trigger one or many builds to TestFlight without configuring a full CI workflow, have internal test groups and want to make the latest changes available as soon as possible, or let EAS handle certificates, provisioning profiles, and API keys automatically.
npx testflight interactive workflow steps
The npx testflight command workflow includes these interactive prompts in sequence: initialize or detect a linked EAS project (creating a new EAS project if needed using the app config slug, or continuing with an existing one); confirm the bundle identifier and encryption type (buildNumber automatically increments on subsequent runs); sign in to Apple Developer with Apple ID and two-factor authentication; generate credentials by creating or updating distribution certificates and provisioning profiles; create a production build using the default EAS production profile to generate an .ipa file; verify App Store Connect access by checking for an App Store Connect API key and creating one if needed; submit the app to TestFlight by uploading the .ipa file to App Store Connect and enabling TestFlight distribution for the internal testing group.
Test production mode JavaScript with npx expo start --no-dev
To test how the JavaScript part of your app will run in production, start it with `npx expo start --no-dev`. This tells the bundler to minify JavaScript before serving it, stripping code protected by the __DEV__ boolean, removing most logging, HMR, Fast Refresh functionality, and making debugging harder. This allows you to iterate on the production bundle faster and identify issues that only occur in production.
Local build command as alternative debugging method
You can run `eas build --local` as an alternative to debugging on EAS Build. This command executes a series of steps as close as possible to what runs remotely on the hosted EAS Build service. It copies your project to a temporary directory and makes any necessary changes there. This provides a faster feedback loop for debugging build issues. Learn how to set this up and use it for debugging at /build-reference/local-builds/#use-local-builds-for-debugging.
Test locally with release mode to match EAS Build conditions
To determine if your project will build on EAS Build, it must first build and run locally in release mode. Run `npx expo run:android --variant release` and `npx expo run:ios --configuration Release` with your package manager (npm, yarn, pnpm, or bun) to test locally. If the project builds and runs locally in release mode, it will also build on EAS Build provided that build tool versions, environment variables, and the uploaded archive are the same in both environments. If CNG is being used, these commands will run `npx expo prebuild` to generate native projects; you likely want to clean up the changes afterward unless you want to manage these projects directly.
Fresh git clone test for troubleshooting builds that fail only on EAS
If `npx expo run:android --variant release` and `npx expo run:ios --configuration Release` work locally but builds fail on EAS Build, do a fresh `git clone` of your project to a new directory and get it running, ideally on a different machine. Pay attention to each setup step needed and verify that those steps are also configured for EAS Build. Check that environment variables are properly configured, verify that versions of Node.js, npm, Yarn, Xcode, Java, and other tools match in both environments, and ensure that the archive being uploaded to EAS Build includes the same relevant source files.
Conditions for successful local build predicting EAS Build success
If your project builds and runs locally in release mode with `npx expo run:android --variant release` and `npx expo run:ios --configuration Release`, it will also build on EAS Build provided that all of the following are true: relevant build tool versions (Xcode, Node.js, npm, Yarn, etc.) are the same in both environments, relevant environment variables are the same, and the archive uploaded to EAS Build includes the same relevant source files.
Automatic submission workflow saves time and coordination
Automatic submissions with EAS Build allow apps to be submitted to the respective store once an appropriate build is completed. This saves developers from waiting for the build to complete, avoids manual submission work, and eliminates the need to coordinate providing app store credentials to the team.
Purpose of --no-wait flag in CI builds
The --no-wait flag exits the CI step once the build has been triggered. This is important because you are not billed for CI execution time while EAS performs the build. If you need to add another CI step to run once the build is complete, remove this flag.
CircleCI configuration for EAS builds
Add configuration to circleci/config.yml with version 2.1. Define a default executor using docker image cimg/node:lts with working directory ~/my-app. Create an eas_build job that checks out code, installs dependencies with npm ci, and runs npx eas-cli build --platform all --non-interactive --no-wait. Configure a build_app workflow that triggers the eas_build job on commits to the master branch.
Bitbucket Pipelines configuration for EAS builds
Add configuration to bitbucket-pipelines.yml using the node:alpine image. Define npm cache, a default pipeline with a step that installs bash via apk, runs npm ci, and executes npx eas-cli build --platform all --non-interactive --no-wait.
GitLab CI configuration for EAS builds
Add configuration to .gitlab-ci.yml using the node:alpine image. Define cache settings for npm or Yarn, a build stage, and an eas-build job that installs bash via apk and runs npx eas-cli build --platform all --non-interactive --no-wait. Use npm ci or yarn install with appropriate cache settings before running the build.
Travis CI configuration for EAS builds
Add configuration to .travis.yml with language node_js, cache configuration for npm, and a build job that runs npm ci followed by npx eas-cli build --platform all --non-interactive --no-wait. Use node_js lts/* for the build stage.
GitHub Actions eas-build.yml example
name: EAS Build on: workflow_dispatch: push: branches: - main jobs: build: name: Install and build runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v6 with: node-version: 24 cache: npm - name: Setup Expo and EAS uses: expo/expo-github-action@v8 with: eas-version: latest token: ${{ secrets.EXPO_TOKEN }} - name: Install dependencies run: npm ci - name: Build on EAS run: eas build --platform all --non-interactive --no-wait
Command to trigger EAS builds from CI
To trigger new builds from CI, run npx eas-cli build --platform all --non-interactive --no-wait. This command triggers a new build on EAS and prints a URL linking to the build's progress in the EAS dashboard.
GitHub Actions workflow to trigger EAS builds
Add a workflow file at .github/workflows/eas-build.yml. Use expo/expo-github-action@v8 with eas-version: latest and pass the EXPO_TOKEN from secrets. The workflow should include steps to checkout the code, setup Node.js (version 24 in the example), install dependencies with npm ci, and build on EAS with eas build --platform all --non-interactive --no-wait. Trigger the workflow on workflow_dispatch and push events to the main branch.
EAS Build basic command
To build an app for both Android and iOS platforms using EAS Build, run the command: eas build --platform all. You can also build for one platform at a time by using --platform android or --platform ios as desired.
EAS Build works with existing React Native projects
EAS Build can be used with existing React Native projects created with npx react-native init or similar tools. It is designed to work for any native project, whether or not you use Expo and React Native.
EAS Build service purpose
EAS Build is a hosted Expo Application Services (EAS) service that builds app binaries (standalone apps) for Expo and React Native projects. It simplifies building apps for distribution, handles app signing credentials, supports internal distribution, integrates with EAS Submit for app store submissions, and has first-class support for the expo-updates library.
App store installation workflow
If you built for app store distribution, you must upload to an app store and then install the app from there (for example, from Apple's TestFlight app). You cannot install directly to your device from a store build.
Build for Android and iOS with EAS
Run eas build --platform android to build for Android, eas build --platform ios to build for iOS, or eas build --platform all to build for both platforms simultaneously.
EAS build command wait behavior
By default, the eas build command waits for your build to complete. You can interrupt it if you prefer not to wait. Monitor progress and read logs using the build details page link provided by EAS CLI.
Install build to device from dashboard
After a successful build, you can install the app directly to an Android device or iOS Simulator by navigating to the build details page from your build dashboard and clicking the 'Install' button.
Attach message to build command
You can attach a message to a build by passing --message to the build command, for example: eas build --platform ios --message "Some message". The message appears on the website and is useful for noting the build purpose for your team.
Custom builds work with EAS CLI and CI/CD pipelines
Custom builds can be run from EAS CLI or within a React Native CI/CD pipeline, including when using EAS Workflows.
Build and automatically submit to stores with eas build --auto-submit
Run eas build --auto-submit to build your app and automatically upload the binary for distribution on both the Google Play Store and Apple App Store.
End-to-end workflow: build and submit to stores
The typical workflow for distributing an app to the App Store is to use eas build --auto-submit, which both builds the app and automatically uploads the binary for distribution.
Migrate from CodePush to EAS Update - overview
To migrate a React Native project from CodePush to EAS Update, you must: ensure your app uses the latest Expo SDK version, uninstall CodePush, add an expo key to app.json, follow the EAS Update Getting Started guide, and resubmit your app to app stores. This guide assumes a default React Native project structure.
How to coordinate EAS Update with app store releases
Different deployment patterns provide different coordination strategies. In the two-command flow, updates are published directly to production after builds are submitted to app stores. In persistent staging flow, updates are merged to staging for testing before merging to production. In platform-specific flow, platform-specific branches trigger platform-specific updates. In branch promotion flow, version-based branches are pointed at staging channels for testing, then at production channels after verification, with users on old app versions continuing on old branches until they download new app versions from stores.
Recovery options for broken updates: rollback vs fix forward
When a broken update is published, you can either roll back to an older update that you know was working, or fix it forward. Rollback may not be safe if the broken update modified persistent state in a non-backwards-compatible way. Always test in a staging environment that emulates end user device state before rolling back.
Publish a fix as soon as possible after a broken update
When a broken update is published to production, the first step is to publish a new update with a fix as soon as possible, though not before being 100% confident in the fix. The error recovery mechanism will ensure that most users who downloaded the broken update can get the fix.
Update deployment workflow with staging and production
A typical deployment process can involve a staging Git branch and production Git branch paired with corresponding EAS Update branches. When a commit is pushed to the staging Git branch, an update is published to the staging EAS Update branch, which applies to all builds with the staging channel. Once changes are tested on staging builds, the staging Git branch is merged into the production Git branch, publishing an update to the production EAS Update branch that applies to builds with the production channel.
Create build before publishing updates
You need to create a build for Android or iOS before publishing updates with EAS Update. It is recommended to start with the 'preview' build profile and set up Internal distribution for your device or simulator.
How to coordinate EAS Update with app store releases
EAS Update can be used to quickly fix bugs between app store submissions or to roll out updates to existing app versions. For changes requiring new app binaries (native code changes, new SDK versions, permission changes), a new build must be created and submitted through EAS Build instead.
Create new builds after configuration changes
After making configuration changes to use EAS Update (runtimeVersion, channels), you must create new builds because these changes affect the native code layer inside builds. Existing builds will not work with the new update configuration.
Workflow for migrating from Classic Updates to EAS Update
Complete workflow: 1) Install EAS CLI and log in with `eas login`. 2) Run `eas update:configure` to initialize EAS Update. 3) Remove `expo.sdkVersion` and keep the new `runtimeVersion` field added by the configure command. 4) Add `channel` properties to your build profiles in eas.json, replacing `releaseChannel`. 5) Create new builds with the updated configuration. 6) Publish updates using `eas update --channel [channel-name] --message [message]`.
End-to-end workflow: code to app store release
A complete workflow from code to App Store release using EAS Workflows involves: (1) linking a GitHub repository to your EAS project, (2) creating a workflow file that defines build and submit jobs, (3) pushing code to trigger the workflow automatically or running it manually with eas workflow:run, (4) the build job creates the app binary with a specified build profile, (5) the submit job takes the build_id from the build job output and submits to the App Store.
Fingerprint job in deploy workflow
The fingerprint job has name 'Fingerprint', type 'fingerprint', and environment 'production'. It takes a hash of the native characteristics of the project using Expo Fingerprint and outputs android_fingerprint_hash and ios_fingerprint_hash.
Deploy to production workflow trigger
The workflow runs on each push to the main branch.
Deploy to production workflow overview
The deploy to production workflow detects if new native builds are needed using Expo Fingerprint. If a build does not exist for the current fingerprint, it builds the project and submits to app stores. If a build exists, it sends an over-the-air update instead.
Complete workflow from code to App Store release using EAS
The complete workflow is: (1) Developer pushes code to main branch triggering the workflow. (2) Fingerprint job computes native characteristics hash for Android and iOS. (3) Get-build jobs check if builds exist for each fingerprint. (4) If no build exists, build jobs compile for each platform, then submit jobs send builds to app stores. (5) If a build exists, update jobs send over-the-air updates to the production branch. This automation handles deciding whether native rebuilds are needed or if over-the-air updates suffice.
Build jobs only run if no existing build
The build_android and build_ios jobs only execute if the corresponding get-build job did not find an existing build. They use conditional: if: ${{ !needs.get_android_build.outputs.build_id }} (or ios equivalent). They have platform and profile parameters set to the respective platform and 'production'.
Get build jobs check for existing builds
Two get-build jobs (get_android_build and get_ios_build) check if a build already exists for the respective platform's fingerprint hash. They take parameters: fingerprint_hash (the hash from the fingerprint job) and profile (set to 'production'). They output build_id if a build exists.
Deploy to production workflow overview
A deploy to production workflow allows you to build and submit to the app stores or send an over-the-air update when merging to main.
iOS manual submission workflow via Xcode
To manually submit an iOS app to the Apple App Store without EAS Submit, follow this workflow: (1) Open the iOS workspace in Xcode using 'xed ios' from the project directory. In Signing & Capabilities, select your Apple Developer team to generate an automatically managed provisioning profile and signing certificate. (2) Configure a release scheme by opening Product > Scheme > Edit Scheme, selecting Run, and setting Build configuration to Release. (3) Build the app for release using Product > Build. (4) Archive the app using Product > Archive, then click Distribute App, select App Store Connect, and follow the prompts. Xcode will upload the build to App Store Connect. (5) Sign in to App Store Connect, select your app, and submit it to TestFlight or for App Review from the dashboard.
EAS Workflows automates iOS submission
EAS Workflows is the simplest way to run eas submit automatically after a build. Workflows run on EAS infrastructure and can be triggered by a git push or run manually from the CLI.
Trigger EAS Workflow manually
Trigger an EAS Workflow manually from the CLI using: eas workflow:run submit-ios.yml
EAS Workflows submit-ios.yml example
Create .eas/workflows/submit-ios.yml with: name: Submit iOS on: push: branches: ['main'] jobs: build_ios: name: Build iOS app type: build params: platform: ios profile: production submit_ios: name: Submit to TestFlight needs: [build_ios] type: testflight params: build_id: ${{ needs.build_ios.outputs.build_id }}
Workflow for using custom native code libraries in development builds
When using development builds, the workflow for custom native code libraries is: (1) Install the library with npm, for example 'npx expo install react-native-localize'; (2) If the library includes a config plugin, specify your preferred configuration in the app config; (3) Create a new development build either locally or with EAS.
Local module development workflow with fast feedback
When writing custom native code with CNG, generate native directories and build locally with 'npx expo run' to have a fast feedback loop and full access to native debugging tools in Android Studio and Xcode, even though EAS Build will regenerate these directories.
Launch app in iOS Simulator from Expo CLI
Run your app with npx expo start and press I from the command line to open it in the iOS Simulator. You can also press Shift + I to interactively select a simulator to open.
Production mode benefits
Production mode is useful for testing app performance and catching bugs that only show up in production. It minifies code and better represents the performance the app will have on end users' devices.
Simulate production mode locally with expo start
To simulate how a project will run on end users' devices, run: npx expo start --no-dev --minify. The --no-dev flag tells the Metro bundler to set __DEV__ environment variable to false and performs other production mode settings. The --minify flag minifies the app and eliminates unnecessary data such as comments, formatting, and unused code.
Development vs Production mode overview
A project always runs in either development or production mode. Running locally with npx expo start runs in development mode by default. A published project with eas update or any standalone app runs in production mode.
Development mode features
Development mode includes useful warnings and access to debugging tools. It provides remote JavaScript debugging in Chrome, live reload, hot reloading, and an element inspector. Development mode performs validations while the app runs to give warnings about deprecated properties or missing required properties.
Development mode performance impact
Development mode slows down app performance. When testing app performance, development mode must be disabled. The mode can be switched on and off with the Expo CLI, and the app must be closed and re-opened for the change to take effect.
Monitoring production app
Two ways to monitor your production app are crash reports and analytics. Crash reports help you learn about exceptions or errors that users encounter. You can use Sentry or BugSnag to enable crash reports. Analytics allows you to track how users interact with your app.
Cloud-based vs local development workflows
Whether you choose cloud-based or local development does not significantly alter your development loop. The choice is about how you produce and distribute your app binaries that your JavaScript code runs against. You can make this choice each time you run a new native build. Compiling your app in the cloud with EAS Build requires only running a single command and no installation of Android Studio or Xcode. Cloud builds make it easier to share your app with teammates or stakeholders. To compile locally, you need to install Android Studio and Xcode, then either run the build from those tools or use npx expo run:[android|ios].