configuration & prerequisites

163 notes in this subject, read out of this brain and free to use. This is page 1 of 3.

EAS CLI configuration command and steps

EAS CLI configures a project when running 'eas build:configure' or 'eas build' if the project is not yet configured. The configuration process performs four main steps: (1) prompts to select platform(s) to configure, (2) creates eas.json file in the root directory, (3) configures the project (which varies by project type), and (4) optionally commits changes if cli.requireCommit is set to true.

Bare React Native projects require no additional configuration steps

For existing React Native projects (bare projects), there are no additional configuration steps required during the EAS CLI configuration process beyond the standard four steps.

CNG in monorepo configuration

If building a project that uses Continuous Native Generation (CNG) in a monorepo, additional configuration steps are required. Consult the Working with Monorepos guide for CNG-specific setup.

Native directories handling with EAS Build

If your project does not contain android and ios directories, EAS Build will automatically run Prebuild to generate these native directories before compilation.

Git submodules initialization requirement

When using EAS Build with Git submodules, if you are building on CI or have cli.requireCommit set to true in eas.json, or if a submodule is in a private repository, you must initialize the submodule to avoid uploading empty directories. With the default Version Control Systems (VCS) workflow and no CI/private repository constraints, submodule content is uploaded as-is.

Submodule initialization example script

#!/usr/bin/env bash mkdir -p ~/.ssh # Real origin URL is lost during the packaging process, so if your # submodules are defined using relative urls in .gitmodules then # you need to restore it with: # # git remote set-url origin git@github.com:example/repo.git # restore private key from env variable and generate public key umask 0177 echo "$SSH_KEY_BASE64" | base64 -d > ~/.ssh/id_rsa umask 0022 ssh-keygen -y -f ~/.ssh/id_rsa > ~/.ssh/id_rsa.pub # add your git provider to the list of known hosts ssh-keyscan github.com >> ~/.ssh/known_hosts git submodule update --init

eas-build-pre-install hook for submodule checkout

Add an eas-build-pre-install npm hook to check out submodules. The hook script must create the .ssh directory, decode the base64 encoded SSH key from an environment variable into ~/.ssh/id_rsa, generate the public key with ssh-keygen, add the git provider to known_hosts (e.g., ssh-keyscan github.com), and run git submodule update --init.

Create SSH secret for submodule access

To initialize a submodule on EAS Build builder, create a secret containing a base64 encoded private SSH key that has permission to access the submodule repositories. This secret will be used in the build pre-install hook.

Restore git remote URL for relative submodule URLs

When building on EAS Build, the real origin URL is lost during the packaging process. If your submodules are defined using relative URLs in .gitmodules, you must restore the origin URL manually in the eas-build-pre-install hook using git remote set-url origin with the full git repository URL (e.g., git@github.com:example/repo.git).

SSH key file permissions in submodule initialization

In the eas-build-pre-install hook, set umask to 0177 before decoding the SSH private key to ~/.ssh/id_rsa to ensure restrictive permissions, then reset umask to 0022 before generating the public key.

Local step: git index check with cli.requireCommit

If cli.requireCommit is set to true in eas.json, EAS CLI checks whether the git index is clean before building. If there are uncommitted changes, EAS CLI offers to commit them or abort the build process.

Local step: Xcode project configuration validation

Projects that manage their own native directories (android and ios) require an additional step: check whether the Xcode project is configured to be buildable on EAS servers to ensure the correct bundle identifier and Apple Team ID are set.

iOS build prerequisites: native configuration

Before running a production iOS build, projects with managed native directories must have the Xcode project correctly configured with the correct bundle identifier and Apple Team ID set.

Authentication required for local builds

To use local builds, authenticate with Expo by running `eas login` or alternatively set `EXPO_TOKEN` using token-based authentication.

Required tools for local builds

For local builds, you are responsible for ensuring your environment has all necessary tools installed: Node.js, Yarn, npm, fastlane (iOS only), CocoaPods (iOS only), Android SDK, and NDK.

Using npm cache with Yarn 1 via eas-build-pre-install hook

To use the EAS npm cache with Yarn 1, add the eas-build-pre-install npm hook in package.json to override the registry URLs in yarn.lock. The hook uses sed to replace the default Yarn registry URL (https://registry.yarnpkg.com) with the EAS_BUILD_NPM_CACHE_URL environment variable.

eas-build-pre-install hook for Yarn 1 registry override example

Add this script to package.json to enable npm cache with Yarn 1: ```json { "scripts": { "eas-build-pre-install": "bash -c \"[ ! -z \\\"$EAS_BUILD_NPM_CACHE_URL\\\" ] && sed -i -e \\\"s#https://registry.yarnpkg.com#$EAS_BUILD_NPM_CACHE_URL#g\\\" yarn.lock\" || true" } } ``` This script checks if EAS_BUILD_NPM_CACHE_URL is set, then replaces all occurrences of the Yarn registry URL in yarn.lock with the cache URL.

EAS npm cache incompatibility with Yarn 1 Classic

By default, the EAS npm cache does not work with Yarn 1 (Classic) because yarn.lock files contain URLs to registries for every library. Yarn 1 does not provide any way to override these registry URLs, and the Yarn team does not plan to support this feature in Yarn 1. This issue is fixed in Yarn 2 and later versions.

Prerequisites for npx testflight

To use npx testflight, you need: a React Native iOS project you want to deploy to TestFlight, a paid Apple Developer account, and an Expo account.

Manual .npmrc configuration for private registries

For private npm registries such as Verdaccio, create a .npmrc file in your project's root directory. The basic configuration is: registry=__REPLACE_WITH_REGISTRY_URL__. If your registry requires authentication, include the token: //registry.example.com/:_authToken=${NPM_TOKEN} followed by registry=https://registry.example.com/.

Private npm packages from npm require NPM_TOKEN secret

To use private packages published to npm with EAS Build, you must provide a read-only npm token by adding the NPM_TOKEN secret to your account or project's secrets. This allows EAS Build to install private dependencies successfully.

Configuration for both private npm packages and private registry

To use both private npm packages and a private registry, create a .npmrc file in your project root with scoped package configuration. Example: //registry.npmjs.org/:_authToken=${NPM_TOKEN}, @johndoe:registry=https://registry.npmjs.org/, and registry=https://registry.johndoe.com/. The scoped package registry (prefixed with @) takes precedence for packages in that scope.

Private repository submodules require SSH key setup

If your project contains a submodule in a private repository, you must initialize it by setting up an SSH key before EAS Build can access it.

Use 'large' resource class to increase memory for EAS Build

To increase memory limits on EAS Build builders, set the resourceClass to 'large' in your eas.json. Refer to the Android-specific resource class documentation at /build-reference/infrastructure/#android-build-server-configurations and iOS-specific resource class documentation at /build-reference/infrastructure/#ios-build-server-configurations for more information.

Monorepo support: EAS Build has first-class Yarn workspaces support

EAS Build requires the entire source code rather than a compiled JavaScript bundle and manifest, functioning like a typical CI service. For monorepos, you must upload the entire monorepo to the EAS Build builders, set it up, and run the build. EAS Build has first-class support for Yarn workspaces. Success may vary when using other monorepo tools. For more information, see the Working with monorepos guide at /guides/monorepos.

Gitignore files prevent upload to EAS Build servers

When you run `eas build`, your project files are uploaded to Expo's build servers, but any file or directory listed in .gitignore is not uploaded. This is intentional to prevent sensitive information like API keys from being exposed. If your project imports a file listed in .gitignore, the build will fail with a 'None of these files exist' error.

Solutions for handling gitignored files in EAS Build

There are four approaches to resolve 'None of these files exist' errors caused by gitignored files: (1) Remove the import statement for the ignored file and test if the project functions without it. (2) Remove the files or directories from .gitignore, but this poses security risks if sensitive information is present. (3) Encode the file with base64, save the string as a secret, and create the file in an EAS Build hook using the guide at https://expo.fyi/eas-build-archive.md#how-can-i-upload-files-to-eas-build-if-they-are-gitignored. (4) Refactor source code to avoid importing sensitive files on the client side; instead use environment variables or serve them through your backend.

Migrate existing React Native project to use CNG for variants

If using app config as source of truth for bundle identifiers and package names across variants, migrate to Continuous Native Generation (CNG) and add android and ios directories to .gitignore. This ensures app config takes precedence over native project configuration when using variants.

Link GitHub repository to Expo project

To link a GitHub repository to an Expo project, visit the project's GitHub settings page at https://expo.dev/accounts/[account]/projects/[projectName]/github. Install the Expo GitHub App on the GitHub account, then use the repository selector to link the repository. Only users with Owner or Admin access to the Expo account can install the app. GitHub organization repositories can only be linked to Expo organizations.

Base directory configuration for GitHub builds

If Expo project source code is in the root of the repository, no configuration is needed. If the source code is in a subdirectory, configure the 'Base directory' settings on the project's GitHub settings page. You can also specify a base directory for individual builds, which does not change the global project settings.

GitHub build troubleshooting

When GitHub builds fail, error information will be commented on the attempted commit. Verify: (1) all Prerequisites are met, (2) base directory is accurate for monorepo setups, (3) build profile name matches exactly in eas.json, as builds will not dispatch if a matching profile cannot be found.

Prerequisites for triggering builds from GitHub

To trigger EAS builds from GitHub, three prerequisites must be met: (1) The image field must be set in eas.json for build profiles used with GitHub, (2) A successful build must be run from the local machine for each platform to support on GitHub using 'eas build -p [all|ios|android]', (3) An Expo user in the organization must have a linked GitHub user with access to the target repository and must accept permissions from the Expo GitHub app.

Prerequisites for triggering EAS builds from CI

Before triggering EAS builds from CI, you must run at least one successful build locally. This accomplishes several critical configuration steps: initializing the project on EAS by generating a projectId, adding an eas.json file defining build profiles, populating critical app config properties for native builds such as android.packageName and ios.bundleIdentifier, and ensuring build credentials are created including Android keystores and iOS distribution certs and provisioning profiles.

Local build command to configure for CI

Run eas build -p [all|android|ios] from your local terminal for each platform you want to support on CI. This command will prompt for any additional configuration needed and make that configuration available for future non-interactive runs.

EXPO_TOKEN environment variable for CI authentication

To authenticate with your Expo account on CI, store a personal access token in the EXPO_TOKEN environment variable in the CI settings. Create a personal access token from your Expo account settings to use for programmatic access.

Ad hoc provisioning profile refresh for internal distribution on CI

For internal distribution builds on CI with ad hoc provisioning, refresh the ad hoc provisioning profile to ensure registered devices added after the last build are included. For eas build, pass --refresh-ad-hoc-provisioning-profile with --non-interactive. For EAS Workflows, set refresh_ad_hoc_provisioning_profile: true in the build job's params.

ASC API token environment variables for iOS credential repair

To handle iOS credential repairs on CI, such as re-signing provisioning profiles, pass ASC API information through environment variables. The required environment variables are: EXPO_ASC_API_KEY_PATH (the path to the ASC API Key .p8 file, for example /path/to/key/AuthKey_SFB993FB5F.p8), EXPO_ASC_KEY_ID (the key ID of the ASC API Key, for example SFB993FB5F), EXPO_ASC_ISSUER_ID (the issuer ID of the ASC API Key, for example f9675cff-f45d-4116-bd2c-2372142cee09), EXPO_APPLE_TEAM_ID (the Apple Team ID, for example 77KQ969CHE), and EXPO_APPLE_TEAM_TYPE (the Apple Team Type, which must be one of IN_HOUSE, COMPANY_OR_ORGANIZATION, or INDIVIDUAL).

Expo Orbit system requirements

Expo Orbit relies on the Android SDK on macOS, Windows, and Linux. On macOS only, it requires xcrun for device management. Both Android Studio and Xcode must be set up and installed.

EAS Build handles app signing

EAS Build can generate and manage Android keystores, iOS provisioning profiles and distribution certificates automatically, or you can provide your own credentials. See App signing credentials documentation for more information.

Store developer accounts required for app store builds

Before building for app stores, you must have a store developer account. Google Play Developer membership is a one-time $25 USD fee. Apple Developer Program membership costs $99 USD annually.

Configure project for EAS Build

Run eas build:configure to set up your Android or iOS project for EAS Build. This command handles the configuration process behind the scenes.

Expo account required for EAS Build

EAS Build is available to anyone with an Expo account, regardless of whether you use the Free plan or a paid subscription. You can sign up at expo.dev/signup. Paid subscribers get additional build concurrencies, priority queue access, and increased build timeout limits.

Development build setup with expo-dev-client

For development, install the expo-dev-client library by running npx expo install expo-dev-client to create a development build, which is a debug build containing the expo-dev-client library and provides a flexible development environment.

Prerequisites for creating first EAS build

Before creating your first EAS build, you need a React Native Android or iOS project (can use npx create-expo-app@latest my-app --template default@sdk-57 to create one), an Expo account (sign up at expo.dev/signup), and the latest EAS CLI installed globally.

Android app signing credentials with EAS

For Android app signing credentials, you can let EAS CLI generate a new keystore by selecting 'Generate new keystore' (stored securely on EAS servers), reuse credentials from previous expo build:android builds, or manually generate your keystore.

Additional configuration for special scenarios

Additional configuration may be required if your app uses environment variables, is inside a monorepo, depends on private npm packages, or requires specific tool versions like Node, Yarn, npm, CocoaPods, or Xcode.

iOS app signing credentials with EAS

For iOS app signing credentials, you can let EAS CLI generate a provisioning profile and distribution certificate by signing into your Apple Developer Program account and following prompts, reuse credentials from previous expo build:ios builds, or manually generate credentials.

Advanced features automatically enabled via config plugins

Advanced features such as payments, notifications, universal links, and iCloud can be automatically enabled based on your config plugins or native entitlements.

EAS manages native code signing automatically

EAS Build automatically manages all native code signing for Android and iOS for any React Native app, eliminating the need for manual code signing configuration.

Latest Expo SDK version required for CodePush migration

To migrate from CodePush to EAS Update, you must use the latest Expo SDK version. Instructions are not available for older Expo SDK and React Native versions. Additional hands-on support for integrating with older versions can only be provided for enterprise customers.

Uninstall CodePush package

Remove the react-native-code-push package from your project using 'npm uninstall react-native-code-push'. You must also remove CodePush references from JavaScript and native code to avoid conflicts and unexpected behavior with EAS Update, such as the app periodically fetching updates from both services.

Running eas update:configure

Run `eas update:configure` in your project if you haven't already to set up channel configuration and runtime version policy.

Channel configuration without EAS Build

If you do not use EAS Build, you must modify the channel used in your native project configuration. When you release to production, ensure you update the channel name in native config to "production". When you release to staging, ensure you update the channel name in native config to "staging".

AndroidManifest.xml expo-updates configuration

In android/app/src/main/AndroidManifest.xml, expect to see: `<meta-data android:name="expo.modules.updates.EXPO_RUNTIME_VERSION" android:value="your-runtime-version-here"/>` and `<meta-data android:name="expo.modules.updates.EXPO_UPDATE_URL" android:value="https://u.expo.dev/your-project-id-here"/>`.

Native expo-updates configuration after prebuild

When `eas build` is run, `npx expo prebuild` is executed on EAS servers to unpack android and ios directories. If the project does not have these directories, run `npx expo prebuild` locally to inspect the project state. Check for these files: android/app/src/main/AndroidManifest.xml and ios/your-project-name/Supporting/Expo.plist. Both should contain EAS Update URL and runtime version configuration.

Expo.plist expo-updates configuration

In ios/your-project-name/Supporting/Expo.plist, expect to see: `<key>EXUpdatesRuntimeVersion</key><string>your-runtime-version-here</string>` and `<key>EXUpdatesURL</key><string>https://u.expo.dev/your-project-id-here</string>`.

expo-updates required configuration in app.json

When setting up EAS Update by running `eas update:configure`, the app config (app.json or app.config.js) should contain: runtimeVersion (should be set, default is {"policy": "appVersion"}), updates.url (should be a value like https://u.expo.dev/your-project-id matching the project ID), and updates.enabled (should not be false; true by default if not specified). Ensure expo-updates is included in package.json.

Verify expo-updates installation

To ensure expo-updates is included in the project, run one of: `npx expo install expo-updates` (npm), `yarn expo install expo-updates` (yarn), `pnpm expo install expo-updates` (pnpm), or `bun expo install expo-updates` (bun).

Debug environment variable for native expo-updates debugging

To create a debug build of the app with expo-updates enabled (closer to production), set the debug environment variable: `export EX_UPDATES_NATIVE_DEBUG=1`. This allows debugging native code while loading the app through expo-updates.

Android local debug build with expo-updates

To create an Android debug build with expo-updates enabled: set `export EX_UPDATES_NATIVE_DEBUG=1`, ensure the desired channel is set in AndroidManifest.xml, then execute a debug build with Android Studio or from command line.

Give your agent this brain