EAS Build Guide¶

This guide describes how to perform three types of builds with EAS (Expo Application Services): cloud builds, local builds, and iOS builds. This is suitable for beginners and other developers who want to get started quickly.

There are 3 build profiles available: preview, development, and production which can be configured in the eas.json file. The preview profile is designed for quick tests and internal distribution of APK or IPA files. The development profile is intended for extensive testing with debug options enabled, also producing APK or IPA outputs. Finally, the production profile is configured for app store distribution, generating AAB or IPA files.

Preparation¶

Make sure you have EAS CLI installed:

npm install -g eas-cli

Ensure your project is configured for EAS Build:

eas build:configure

This creates an eas.json file in your project folder. This file contains the build profiles and settings for EAS Build. Modify this file according to your preferences if necessary.

Building with EAS¶

Cloud Build (Managed)¶

Cloud builds use the Expo servers to build your app. This is convenient because no local configuration is required.

You will need an EAS account, which you can create for free at expo.dev/signup.

If you want to perform an iOS build, you need an Apple Developer account https://developer.apple.com/programs.

Steps¶

Open the terminal in your project folder.
Log in to EAS:

npx eas login

Enter your email and password.

Start the cloud build:

npx eas build --platform android --profile preview

This will build the app in the cloud for Android using the preview build profile.

Or for iOS:

npx eas build --platform ios --profile production

This will build the app in the cloud for iOS using the production build profile.

Choose the build profile when prompted (for example preview, production, or development).
EAS will show a link where you can monitor the build status.

Example terminal output¶

✔ Logged in as user@example.com
✔ Using project at /path/to/project
? Choose the build profile › preview
✔ Build queued. You can monitor the build at:
https://expo.dev/accounts/username/projects/project/builds/xyz

...

=== build in progress ===
✔ Build finished successfully!
✔ Download the build artifacts:
https://expo.dev/accounts/username/projects/project/builds/xyz/artifacts

Local Build¶

With a local build, the app is built on your own computer. Useful for quick tests and process control.

Steps¶

Ensure the correct tools are installed:
Android: Android Studio / SDK https://developer.android.com/studio
iOS: macOS + Xcode (for local builds) https://developer.apple.com/xcode/
Start the local build:

npx eas build --platform android '--local' --profile preview 
npx eas build --platform ios '--local' --profile preview

Note

for ease we pre programmed the command in scripts in package.json like so:

"scripts":
  {
    "prod:build:android": "npx eas build --platform android --profile production --clear-cache",
    "prod:build:ios": "npx eas build --platform ios --profile production --clear-cache",
    "dev:build:android": "npx eas build --platform android  --profile development --clear-cache",
    "dev:build:ios": "npx eas build --platform ios --profile development --clear-cache",
    "preview:build:android": "npx eas build --platform android --profile preview --clear-cache",
    "preview:build:ios": "npx eas build --platform ios --profile preview --clear-cache",
  }

You can run these commands via:

  npm run prod:build:android # this will trigger a cloud production build for android 

  npm run prod:build:ios # this will trigger a cloud production build for ios

  npm run dev:build:android # this will trigger a cloud development build for android

  npm run dev:build:ios # this will trigger a cloud development build for ios

  npm run preview:build:android # this will trigger a cloud preview build for android

  npm run preview:build:ios # this will trigger a cloud preview build for ios

you can still add extra flags like -- --local if needed.

(note the extra -- before local in the npm scripts to pass the flag correctly)

You can rename the file afterward using F2.

The build runs locally and the result is in the ./build folder of your project.

Example terminal output¶

✔ Using project at /path/to/project
✔ Starting local build
✔ Preparing build environment
✔ Installing dependencies
✔ Building Android app locally
✔ Build finished successfully!
✔ Output: /path/to/project/build/app-release.aab

iOS Build (Cloud)¶

iOS builds require extra steps due to Apple certificates and provisioning profiles.

Steps¶

Open the terminal in your project folder.
Start the build:

npx eas build --platform ios --profile production

Follow the prompts by entering your Apple ID and password, providing the two-factor authentication code, and choosing a provisioning profile (EAS can handle this automatically).
EAS will start the cloud build and provide a link to monitor the status.

Note

for ease we pre programmed the command in scripts in package.json like so:

  "scripts":
  {
      "prod:build:ios": "npx eas build --platform ios --profile production --clear-cache",
      "dev:build:ios": "npx eas build --platform ios --profile development --clear-cache",
      "preview:build:ios": "npx eas build --platform ios --profile preview --clear-cache",
    }

You can run these commands via:

```bash
npm run prod:build:ios # this will trigger a production build for ios
npm run dev:build:ios # this will trigger a development build for ios
npm run preview:build:ios # this will trigger a preview build for ios
```

you can still add extra flags like -- --non-interactive if needed.

(note the extra -- before non-interactive in the npm scripts to pass the flag correctly)

Example terminal output¶

✔ Using project at /path/to/project
? Choose the build profile › production
? Apple ID: user@apple.com
? Password (app-specific or Apple ID): ********
? Two-factor code: 123456
✔ Using existing provisioning profile
✔ Build queued. Monitor here:
https://expo.dev/accounts/username/projects/project/builds/abc

Tips¶

Use --clear-cache if you have issues with old files. For local iOS builds, macOS is required, while iOS cloud builds require an Apple Developer account, though you can build in the cloud without macOS. For Android, you can build both in the cloud and locally—local builds require the Android SDK while cloud builds do not. Save output files (.apk, .aab, .ipa) in a central location for distribution or upload to app stores; you can easily rename the file afterward using F2.

Table of build commands¶

cloud builds

Goal	Platform	Command	Notes
Developer build (cloud)	iOS/Android	`eas build --profile development --platform ios/android`	For debugging, device testing, often with dev clients
Preview build (cloud)	iOS/Android	`eas build --profile preview --platform ios/android`	For testers, without full release signing
Production build (cloud)	iOS/Android	`eas build --profile production --platform ios/android`	App-store builds with all signing requirements

local builds

Goal	Platform	Command	Notes
Developer build (local)	iOS/Android	`eas build --local --profile development --platform ios/android`	Local debug build, great for quick iteration
Preview build (local)	iOS/Android	`eas build --local --profile preview --platform ios/android`	Same as cloud preview, but compiled locally
Production build (local)	iOS/Android	`eas build --local --profile production --platform ios/android`	Compile a full production build locally

❗These are the classic build commands. You can also add extra flags like --clear-cache or --non-interactive depending on your needs.

--clear-cache: clears the build cache to avoid issues with old files. Essentially a clean build. --non-interactive: for automated scripts without prompts, provides less terminal info.

Troubleshooting¶

EAS-CLI Debug Flowchart¶

Below is a visual flowchart for debugging EAS errors:

---
id: fa676993-7c73-4b02-be2a-1484a1043c3c
---
flowchart TD
    Start([EAS CLI Error]) --> A{eas command not working?}

    A -->|Yes| Login[expo login → eas whoami]
    A -->|No| B{eas build / submit / etc. fails?}

    B -->|Config| C[Config error → eas build:configure]
    B -->|Credentials| D[Signing error → eas credentials]
    B -->|Native| E[Native build error → npm install + pod-install]
    B -->|Network| F[Network / timeout → expo login + ping expo.dev]
    B -->|Other| G[JS / deps / permissions → lint + reinstall modules]


    style Login fill:#e8f5e8,stroke:#388e3c,color:#000
    style C fill:#e3f2fd,stroke:#1976d2,color:#000
    style D fill:#fff3e0,stroke:#ef6c00,color:#000
    style E fill:#ffebee,stroke:#d32f2f,color:#000
    style F fill:#f1f8e9,stroke:#4caf50,color:#000
    style G fill:#f3e5f5,stroke:#7b1fa2,color:#000

EAS CLI – All Commands per Category (Cheat Sheet)¶

Category	Common Issues	Commands (copy-paste)
Login / Auth	Not logged in, token expired	`expo login` `eas whoami` `expo logout && expo login`
Config	eas.json missing, wrong profile	`eas build:configure` `eas build:configure --profile preview`
Credentials	Certificates/keystore expired	`eas credentials` `eas credentials --platform ios` `eas credentials --clear`
Start Build	Platform or profile not specified	`eas build --platform android` `eas build --platform ios` `eas build -p all`
Native Errors	Gradle / CocoaPods / node_modules corrupted	`npm install` `cd ios && npx pod-install` `eas build --clear-cache`
Network / Timeout	VPN/firewall blocks expo.dev	`ping expo.dev` `curl https://expo.dev` `expo login`
Corrupt Dependencies	Lockfile or node_modules broken	`rm -rf node_modules` `rm -rf package-lock.json yarn.lock` + `npm install`
Permissions	No access to node_modules (macOS/Linux)	`sudo chown -R $USER node_modules`
Update CLI	Old EAS CLI version	`npm install -g eas-cli` `eas --version`
Clear Cache	Strange errors due to old cache	`eas build --clear-cache`
Submit App	Submit to stores after build	`eas submit --platform ios` `eas submit --platform android`

Copy the row you need → paste into terminal → done.

More Information¶

For more information, visit the EAS Build documentation.