build reference details

35 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Build ID shown in eas build:run output

When running `eas build:run -p android`, each build in the displayed list has a build ID, the time elapsed since the build creation, the build number, the version number, and the git commit information associated with it.

.easignore file purpose and priority

A .easignore file defines which files EAS should ignore when uploading your project to the EAS Build servers. By default, the EAS CLI refers to the .gitignore file if it exists to determine which files to ignore. If you create a .easignore file, the EAS CLI prioritizes it over the .gitignore file.

Reducing upload time and archive size with .easignore

Ignoring unnecessary files with .easignore can help reduce your app's archive size and upload time during the build process.

Creating a .easignore file

Create a .easignore file in the root of your project. Copy the content of the .gitignore file into the .easignore file, then add any files that are unnecessary for the build process.

Example .easignore configuration

An example .easignore file content: ``` # Copy everything from your .gitignore file here # Ignore files and directories that EAS Build doesn't need to build your app /docs # Ignore native directories (if you are using EAS Build) /android /ios # Ignore test coverage reports /coverage ``` If your project does not contain android and ios directories, EAS Build will run Prebuild to generate these native directories before compilation.

Including files with .easignore negation pattern

You can use the .easignore file to include files with your EAS Build upload that are not committed to source control. To upload a file not in source control to EAS Build, add it to the .easignore file with a ! prefix, along with the rest of your .gitignore contents. The ! prefixed file should be last, so it takes precedence over any prior rules that would ignore it.

Example .easignore with negation pattern

An example .easignore file that includes a file not in source control: ``` # Copy everything from your .gitignore file here /android /ios # Include a file not in source control !temp_file.json ```

EAS Build server IP addresses location

A list of EAS Build server IP addresses is available at https://expo.dev/eas-build-worker-ips.txt. Linux runners are hosted in Google Cloud Platform. macOS runners are hosted in Expo's own macOS cloud. The list includes Last-Modified and Expires ISO 8601 timestamps specifying when it was last updated and when the current list is guaranteed not to change.

Maximum pending builds limit

The maximum number of pending builds is 50 per platform per account. If more than 50 builds are pending for a platform, new builds will be rejected until the number of pending builds drops below 50.

Build worker memory and CPU limits

EAS Build servers have fixed memory and CPU limits that may be insufficient for apps with significant build process resource requirements. To address this, use the 'large' resource class in eas.json. See the Server infrastructure reference for current specifications of Android (Ubuntu) and iOS (macOS) build servers.

Dependency caching behavior in EAS Build

Android build jobs install npm and Maven dependencies from a local cache. iOS build jobs install npm dependencies from a local cache and CocoaPods artifacts from a cache server. Intermediate artifacts like node_modules directories are not cached and restored based on package-lock.json or yarn.lock, but will be uploaded to build servers if committed to the Git repository.

Maximum build duration timeout

If a build takes longer than the maximum duration allowed for your plan, it will be canceled. The build timeout included with each plan is subject to change and can be found on the EAS pricing page.

Monorepo and workspace package manager support

EAS Build supports monorepos managed with package managers supporting workspaces. Official guidance is limited for package managers other than Bun, npm, pnpm, and Yarn. Third-party monorepo or workspaces tooling may not work as expected or may require additional setup. Check whether your tools and libraries work well within a monorepo before setting one up. See the Work with monorepos guide for more information.

Install latest build on simulator with --latest flag

Pass the --latest flag to the eas build:run command to download and install the latest build on the iOS Simulator. The command is: 'eas build:run -p ios --latest'.

Use eas build:run to download and install previous builds

Run the command 'eas build:run -p ios' at any time to download a specific build and automatically install it on the iOS Simulator. The command displays a list of available builds for the project, each showing the build ID, time elapsed since build creation, build number, version number, and git commit information.

Build ID information in build list

Each build in the eas build:run list includes a build ID, the time elapsed since the build creation, the build number, the version number, and the git commit information. Invalid builds are also displayed if a project has any.

How to get help: Discord, forums, and support plans

Join Discord and forums at https://chat.expo.dev/ to ask for help from the community and Expo team. The Expo team responds to high quality and well-articulated questions and issues, but responses are not guaranteed unless you are signed up for a support plan (see https://expo.dev/support-terms#target-response-time-guidelines-for-subscriptions). To ensure an Expo team member sees your question, file a ticket at https://expo.dev/contact.

Two main categories of EAS Build issues: build failures vs runtime errors

When using EAS Build, issues manifest in two ways: the build fails during compilation, or the build succeeds but the app crashes or hangs at runtime. Runtime errors include cases where an app runs locally but crashes immediately when running a built version, or works in Expo Go but hangs on the splash screen. Build failures occur during the compilation process itself.

How to locate build error messages on the EAS dashboard

To find build error details, go to the build details page on the EAS dashboard at https://expo.dev/accounts/[account]/projects/[project]/builds. Expand any failed build phases by clicking on them. The earliest phase with errors typically contains the most useful information; subsequent failed phases usually cascade from the first failure. Check logs carefully because entries prefixed with [stderr] may contain warnings and diagnostics rather than actual errors causing the build failure.

iOS build logs are truncated; access full Xcode logs when needed

The iOS build details page on EAS only displays an abridged version of logs because the full xcodebuild output can be approximately 10MB. When the abbreviated logs on the build details page do not contain useful information but you suspect a JavaScript build error occurred, scroll to the bottom of the build details page after the build completes and click to view or download the full Xcode logs.

Distinguish JavaScript build errors from native errors in logs

When a build fails due to a JavaScript error, you will see output like 'Metro encountered an error: Unable to resolve module ./src/Routes from /Users/expo/workingdir/build/App.js'. These errors indicate the app is trying to import a module that cannot be found. Common causes include filename case differences between Git and the developer's filesystem (for example, routes.js in Git but Routes.js locally), missing build steps that weren't configured for EAS Build, or files accidentally excluded in .gitignore.

CNG projects: build errors likely from config plugins or dependencies

If you are working on a Continuous Native Generation (CNG) project and the build error is native rather than JavaScript, the error is likely due to a config plugin or a dependency. Check the logs for any new packages added since the previous successful build. Run `npx expo-doctor` to verify that versions of Expo SDK dependencies are compatible with your Expo SDK version.

Compare builds feature to identify what changed between builds

When a previously successful EAS Build starts failing, use the Compare button on the EAS Build details page to compare the failed build against the successful one. Enter the build ID or complete build URL of the build you want to compare against, then click Compare. The comparison view displays metadata (status, environment, Expo SDK version) at the top and a side-by-side log comparison organized by build phase. Indicators show: 'Changed (X lines)' for phases with different output, '+ Added' for phases only in the comparison build, and '- Removed' for phases only in the original build.

Out-of-memory errors indicate large app bundles or problematic files

If a build fails with 'Gradle build daemon disappeared unexpectedly (it may have been killed or may have crashed)' in Gradle logs, the Node process bundling the app JavaScript was killed due to memory pressure. This often signals an extremely large app bundle, which increases binary size and causes slow boot times on low-end Android devices. Sometimes OOM errors occur when large text files are treated as source code, such as JavaScript files containing 1MB+ of HTML for a webview or similarly sized JSON files. Use Expo Atlas (at /guides/analyzing-bundles/) to determine bundle size and see where it comes from. Increase memory limits by using the 'large' resource class in eas.json.

Verify JavaScript bundles locally with npx expo export

When a build fails with 'Task :app:bundleReleaseJsAndAssets FAILED' (Android) or 'Metro encountered an error' (iOS), Metro bundler could not bundle the app's JavaScript. This error is usually followed by syntax error details. Since standard React Native projects perform this step late in the build, errors take a long time to surface. Run `npx expo export` locally to build the production bundle quickly and bypass other build steps. Repeatedly run this command, fixing syntax errors and other issues until the bundle builds successfully, then try EAS Build again.

When troubleshooting, gather build page link, error logs, and reproducible example

When asking for troubleshooting help on Discord, forums, or by filing a ticket, provide: (1) A link to your build page on the EAS dashboard (only accessible by your team or Expo employees; share a screenshot if you want to post publicly, or email secure@expo.dev for private sharing; omit if using `eas build --local`). (2) Error logs related to the build or runtime error. (3) A minimal reproducible example or link to your repository so other developers can reproduce the issue. If you cannot provide a reproducible example, it may not be possible to help you.

What is a build ID in EAS Build

A build ID is a unique identifier assigned to each build created with EAS Build. While the source does not explicitly define why you need it, build IDs are necessary for tracking, retrieving, and managing build artifacts and their details.

Build caching and performance

EAS Build supports faster builds via dependency caching and custom cache paths configuration.

Build server infrastructure

Android builds run on Linux runners hosted in Google Cloud Platform. iOS builds run on macOS runners hosted in Expo's macOS cloud.

Expo Orbit for build installation

Builds and updates on devices can be installed with Expo Orbit, providing a convenient way to test builds.

View build status and history

View your builds by visiting your build dashboard at expo.dev/builds or running eas build:list from the command line. If you are a member of an organization, find builds at expo.dev/accounts/[account]/builds.

Verifying custom build execution

After a custom build completes, you can verify that custom build steps were executed by checking the logs on the build's detail page.

Inspect Expo.plist configuration in iOS build

In an iOS build (locally built or from EAS), Expo.plist should contain: EXUpdatesRequestHeaders (dict with expo-channel-name), EXUpdatesRuntimeVersion (string with runtime version), and EXUpdatesURL (https://u.expo.dev/your-project-id).

Inspect iOS Simulator build Expo.plist configuration

When building an iOS Simulator build with EAS (using {"ios": {"simulator": true}} in build profile), download and unzip the result, right-click the app and select "Show Package Contents", then inspect the Expo.plist file. Expect to see: EXUpdatesRequestHeaders (dict with expo-channel-name key), EXUpdatesRuntimeVersion (runtime version string), and EXUpdatesURL (https://u.expo.dev/your-project-id).

Build ID output from EAS build job in workflows

When a workflow job of type 'build' completes, it outputs a build_id that subsequent jobs can reference. This build_id is accessed via the syntax ${{ needs.<job_name>.outputs.build_id }} and is used by Maestro test jobs to identify which built app to test.

Give your agent this brain