build-reference/local-builds

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

Run EAS Build locally with --local flag

You can run the same build process that runs on EAS Build servers directly on your machine by using the `eas build --local` flag. For Android, run `eas build --platform android --local`. For iOS, run `eas build --platform ios --local`.

Local builds use cases

Local builds are useful for debugging build failures that occur on EAS servers and cannot be reproduced easily, and for meeting company policies that restrict use of third-party CI/CD services by running the entire process on your own infrastructure.

EAS servers communication in local builds

When using local builds, the only communication with EAS servers is to verify that the project account/slug exists and to download managed credentials if used.

Local builds platform limitation

You can only build for a specific platform with local builds. The option `all` is disabled for local builds.

Software version customization not supported in local builds

Customizing versions of software is not supported in local builds. Fields `node`, `yarn`, `fastlane`, `cocoapods`, `ndk`, and `image` in eas.json are ignored when running local builds.

Caching not supported in local builds

Caching is not supported for local builds, unlike cloud builds.

Secret EAS environment variables not supported in local builds

EAS environment variables with Secret visibility are not supported in local builds. Set them in your local environment instead.

Windows support for local builds

On Windows, you can use WSL for local EAS Builds, but Windows is not officially supported. Only macOS and Linux are supported for local builds.

Difference between local development builds and eas build --local

To compile your app locally for development, use `npx expo run:android` or `npx expo run:ios` commands. The `eas build --local` flag follows different procedures and is used to replicate the exact EAS Build server process locally. For production builds locally, see the Create a production build locally guide.

Repack tool overview and purpose

@expo/repack-app is a CLI tool that repackages an existing Android APK, iOS IPA, or iOS .app bundle without performing a full native build. It updates the existing artifact with a new JavaScript (JS) bundle, assets, and app metadata (such as app name, version, and package name or bundle identifier). Since there is no native compilation involved, a repack is typically much faster than a full native build.

When repack is safe to use

Repack assumes the source binary's native side is unchanged since it was built. If you added a native dependency, changed a config plugin, or upgraded the Expo SDK, a repacked artifact will have JS that expects native APIs that do not exist, and will likely crash at runtime. Use fingerprint to compare the source binary's native identity against your current project. If the fingerprints match, then repack is safe. If they differ, do a full native build instead.

Repack vs EAS Update distinction

Repack is not a replacement for EAS Update. EAS Update ships a new JS bundle to apps that are already installed, and users see it on the next launch. Repack produces a new installable artifact. A good rule of thumb is to use repack for internal testing (QA devices, testers, CI smoke tests) and use EAS Update to deliver JS changes to production users.

Repack use cases

Repack is useful for QA cycles where you distribute one base build to testers, then repack with JS fixes for each iteration without waiting for a native rebuild. It is also useful for CI optimization where you build native once per fingerprint, then repack the JS bundle on every subsequent PR to cut wait times from minutes to seconds. Additionally, repack enables branch testing where you test multiple JS branches against the same native binary to isolate JavaScript-only changes.

Standalone CLI minimum required arguments

At minimum, --platform and --source-app are required arguments for repack. The tool runs npx expo export:embed under the hood to produce a fresh JS bundle, swaps it into the source binary, and writes the output artifact. The output format always matches the --source-app input: an APK input produces an APK, an IPA produces an IPA, and a .app bundle produces a .app bundle.

Repack Android command syntax

To repack an Android APK, run: npx @expo/repack-app --platform android --source-app MyApp.apk

Repack iOS IPA command syntax

To repack an iOS IPA, run: npx @expo/repack-app --platform ios --source-app MyApp.ipa

Repack iOS .app bundle command syntax

To repack an iOS .app bundle (for simulator builds), run: npx @expo/repack-app --platform ios --source-app MyApp.app

Repack EAS Workflows integration

EAS Workflows provides a pre-packaged repack job type that handles signing and build management automatically. See EAS Workflows pre-packaged jobs documentation for full syntax, parameters, and examples.

Signing requirements for repack

To produce an artifact installable on a physical device, pass signing credentials alongside --platform and --source-app. Without them, the Android APK is output unsigned and the iOS IPA cannot be installed on a device. iOS .app bundles intended for the simulator do not need signing and can skip this step. If you do not already have signing credentials locally, obtain a keystore (Android) or a signing identity and provisioning profile (iOS) from App credentials documentation.

Repack Android signing command syntax

To repack an Android APK with signing credentials, run: npx @expo/repack-app --platform android --source-app MyApp.apk --ks keystore.jks --ks-key-alias my-alias

Repack iOS signing command syntax

To repack an iOS IPA with signing credentials, run: npx @expo/repack-app --platform ios --source-app MyApp.ipa --signing-identity "Apple Distribution: ..." --provisioning-profile /path/to/profile.mobileprovision. Note that iOS repacking supports ad-hoc and development signing only.

JS bundle only mode for repack

By default, repack updates the JS bundle, assets, and app metadata (app name, version, bundle identifier, and the expo-updates manifest). Pass --js-bundle-only when you intentionally want to update only the JS bundle and leave all native config untouched.

Repack production limitations

Repack is not recommended for production Google Play Store or Apple App Store submissions. Production builds should go through the complete build pipeline for correct symbolication and signing.

Repack CLI reference - options table

Repack CLI options: -p, --platform <platform> (Required, android or ios); --source-app <path> (Required, path to APK/IPA/.app); -o, --output <path> (output path, defaults to repacked.apk/repacked.ipa/repacked.app in project root); -w, --working-directory <path> (path to working directory for temporary files); --skip-working-dir-cleanup (skip cleanup after repack); -v, --verbose (enable verbose logging); --js-bundle-only (update only JS bundle, skip native config); --embed-bundle-assets (force running npx expo export:embed for JS bundle and assets, even for debug builds); --bundle-assets-sourcemap-output <path> (generate source map at specified path, requires --embed-bundle-assets); [project-root] argument (path to project root, defaults to current working directory).

Repack Android-specific CLI options

Android-specific repack options: --ks <path> (path to keystore file); --ks-pass <password> (keystore password, defaults to pass:android, supports formats pass:<password>, env:<name>, file:<file>); --ks-key-alias <alias> (keystore key alias); --ks-key-pass <password> (keystore key password, supports formats pass:<password>, env:<name>, file:<file>); --android-build-tools-dir <path> (path to Android SDK build-tools directory).

Repack iOS-specific CLI options

iOS-specific repack options: --signing-identity <identity> (code signing identity); --provisioning-profile <path> (path to provisioning profile, or alternatively a JSON-encoded value for multi-target apps such as when bundling app extensions).

Build local app variants with APP_VARIANT environment variable

When building locally with expo run:android or expo run:ios, set the APP_VARIANT environment variable. For example: APP_VARIANT=development npx expo run:ios compiles the development variant as a debug build.

Switch app variants requires clean prebuild regeneration

APP_VARIANT changes only the app's name and package name, not how the binary is compiled. To switch variants, run expo prebuild --clean to regenerate native directories with the new variant, then run expo run with the same APP_VARIANT set on both commands so clean prebuild and compilation use the same variant.

Local builds with EAS Build

You can run builds locally on your machine instead of in the cloud using eas build --local. Local builds are useful for debugging or for security policies that require local builds.

Development builds reuse

Development builds can be reused across your team. When two team members run eas build:dev and the project fingerprint matches, the existing build is downloaded from EAS instead of creating a new one, saving time and resources.

Give your agent this brain