build-reference/app-versions

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

Remote version source configuration in eas.json

To enable remote version source, set cli.appVersionSource to 'remote' in eas.json. Then under the 'production' build profile, set the autoIncrement property to true. When remote version is enabled, build version values stored in app config are ignored and not updated when the version is incremented remotely. The remote version source values are set on the native project when running a build and are considered the source of truth.

Remote version source is recommended from EAS CLI 12.0.0

The remote version source is the recommended behavior from EAS CLI version 12.0.0 onwards.

Accessing app versions in your app code

To show the user-facing version inside your app, use Application.nativeApplicationVersion from the expo-application library. To show the developer-facing build version inside your app, use Application.nativeBuildVersion from the expo-application library.

npx testflight buildNumber auto-increment

When the npx testflight command is run subsequently after the initial run, the buildNumber automatically increments.

Runtime version management for binary compatibility

Each binary version of your app should use a different runtime version to ensure binary compatibility with updates. When you change the native runtime (such as adding or removing a native library or modifying app.json in Continuous Native Generation projects), you should increment the runtime version to prevent publishing incompatible JavaScript bundles to incompatible native runtimes.

Remote version initialization from local app config

The remote version is initialized with the value from the local project. For example, if you have `android.versionCode` set to `1` in app config, when you create a new build using the remote version source, it will auto-increment to `2`. If you do not have build versions set in your app config, the remote version will initialize with `1` when the first build is created.

Remote version source becomes source of truth

When the `remote` version property is enabled in eas.json, the build version values stored in app config are ignored and not updated when the version is incremented remotely. The remote version source values are set on the native project when running a build, which is considered the source of truth for these values. You can safely remove these values from your app config.

Sync existing versions to remote with eas build:version:set

To sync already defined versions to EAS Build remotely, run `eas build:version:set` in the terminal. Select the platform (Android or iOS) when prompted. When prompted whether to set app version source to remote, select yes. When prompted what version to initialize with, enter the last version number that you have set in the app stores. After these steps, app versions are synced to EAS Build remotely.

Sync remote versions to local with eas build:version:sync

To build your project locally in Android Studio or Xcode using the same version stored remotely on EAS, run `eas build:version:sync` to update your local project with the remote versions.

Remote version source limitations

Remote versioning has the following limitations: (1) `eas build:version:sync` on Android does not support existing React Native projects with multiple flavors, though the rest of remote versioning functionality works with all projects. (2) `autoIncrement` does not support the `version` option. (3) It is not supported if you are using EAS Update with runtime policy set to `"runtimeVersion": { "policy": "nativeVersion" }`; use the `"appVersion"` policy instead for similar behavior.

Local version source with existing React Native projects

In existing React Native projects using local version source, the values in native code take precedence. The libraries `expo-constants` and `expo-updates` read values from the app config file. If you rely on version values from a manifest, you should keep them in sync with native code. This is especially important if you are using EAS Update with runtime policy set to `"runtimeVersion": { "policy": "nativeVersion" }`, because mismatched versions may result in wrong update delivery. Use `expo-application` to read the version instead of depending on app config values.

Local version source limitations

Local version source has the following limitations: (1) With `autoIncrement`, you need to commit your changes on every build if you want the version change to persist, which can be difficult to coordinate when building on CI. (2) For existing React Native projects with Gradle configuration that supports multiple flavors, EAS CLI is not able to read or modify the version, so `autoIncrement` is not supported and versions will not be listed in the build details page on expo.dev.

App version properties in app config

Three properties define app versions in Expo app config: (1) `version` is the user-facing version visible in stores; on Android it represents `versionName` in android/app/build.gradle, on iOS it represents `CFBundleShortVersionString` in Info.plist. (2) `android.versionCode` is the developer-facing build version for Android, representing `versionCode` in android/app/build.gradle. (3) `ios.buildNumber` is the developer-facing build version for iOS, representing `CFBundleVersion` in Info.plist.

Display user-facing version in app

To show the user-facing version inside your app, use `Application.nativeApplicationVersion` from the `expo-application` library.

Display developer-facing build version in app

To show the developer-facing build version inside your app, use `Application.nativeBuildVersion` from the `expo-application` library.

Remote version source recommended from EAS CLI 12.0.0

The `remote` version source is the recommended behavior from EAS CLI version 12.0.0 onwards. EAS servers store and manage your app's developer-facing build version (android.versionCode and ios.buildNumber) remotely.

Version code must be unique for each release

The Version code identifies each release in Google Play Console. Every new release must have a unique value. In an Expo project, set this with expo.android.versionCode in your app config, or use remote version source to increment it automatically.

Give your agent this brain