🦸 Expo & Expo Router

Versioning

Under a managed expo workflow Android and iOS use different values to represent the user facing store version and the version for developers.

• User: The version field in app.json for iOS corresponds to CFBundleShortVersionString in Info.plist .
• User: For Android, the version field in app.json represents versionName in android/app/build.gradle.
• Developer: The ios.buildNumber field inapp.json represents CFBundleVersion inInfo.plist.
• Developer: Similarly, android.versionCode in app.json corresponds to versionCode inandroid/app/build.gradle

When submitting a new binary file to the app stores, it's essential to increment the iOS and Android version fields in app.json. Failure to do so may result in the rejection of the duplicate app version build by the stores.

Expo has automatic remote versioning built in, or you can write custom scripts and pipeline jobs to handle these versions. See sections below.

EAS Profiles

Before we get to deployments, you need separate build profiles for development, testing, and production. You can also set up profiles for white-labelling here.

These live in eas.json at the root of your project. All build configurations go under the build key. Here's a basic example:

JSON
1{
2    "build": {
3      "development": {
4        "developmentClient": true,
5        "distribution": "internal",
6        "channel": "dev-client-simulator",
7        "node": "18.18.2",
8        "env": {
9          "APP_ENV": "staging"
10        },
11        "android": {
12          "buildType": "apk"
13        },
14        "ios": {
15          "simulator": true
16        },
17        "cache": {
18          "disabled": "true",
19          "key": "bustcache"
20        }
21      },
22      "qa": {
23        "extends": "production",
24        "env": {
25          "APP_ENV": "qa"
26        },
27        "android": {
28          "distribution": "internal",
29          "buildType": "apk"
30        },
31        "channel": "the-joe-codes-qa-v1.0.0"
32      },
33      "production": {
34        "node": "18.18.2",
35        "env": {
36          "APP_ENV": "production"
37        },
38        "cache": {
39          "key": "bustcache"
40        },
41        "channel": "the-joe-codes-production-v1.0.0"
42      }
43    },
44    "submit": {
45      "production": {
46        "ios": {
47          "companyName": "TheJoeCodes",
48          "ascAppId": "123456789",
49          "bundleIdentifier": "com.TheJoeCodes.blog"
50          ...ANY_MORE_IOS_OPTIONS
51        },
52        "android": {
53          "applicationId": "com.TheJoeCodes.blog"
54          ...ANY_MORE_ANDROID_OPTIONS
55        }
56      },
57      "qa": {
58        "ios": {
59          "companyName": "TheJoeCodes",
60          "ascAppId": "987654321",
61          "bundleIdentifier": "com.TheJoeCodes.blog.qa"
62          ...ANY_MORE_IOS_OPTIONS
63        }
64        "android": {
65          ...ANY_MORE_ANDROID_OPTIONS
66        }
67      }
68    },
69    "cli": {
70      "version": ">= 5.6.0"
71    }
72  }

In the eas.json file above, you can see we have three distinct profiles:

• development: Your development builds include developer tools. Android APKs can be used on real Android devices via the "distribution": "internal" property. The developmentClient property creates a dependency on expo-dev-client in our build.
• qa: Your UAT environment build profile, extending production with a few overrides, is used for testing on real devices by installing directly onto your team's physical devices (APKs or TestFlight respectively). Note that the iOS simulator property is excluded for our QA setup.
• production: your optimized production build, devoid of developer tools, intended for your team's testing and the submission to app stores for end users. Note that if the file type for Android is not explicitly set and AAB is used, this is the preferred format for Play Store submissions.

You can generate a default eas.json by running eas build:configure (you'll need the EAS CLI installed globally: npm install -g eas-cli). Check the docs for the full setup.

Assembling EAS Deployments with GitHub Actions

You need a way to separate OTA deployments from native store submissions. A common approach is gated GitHub Actions that need manual approval for native builds, with automated OTA deploys on merge. What works best depends on your team.

The examples below are starting points. In practice you'd refine them further, maybe with version tagging, release notes from conventional commits, or hotfix branches for production rollbacks.

Example GitHub Action - Prepare, Build, and Submit a New UAT App Version:

New native dependencies that need to be shipped to your UAT environment? Manually trigger a GitHub action to bump the versions of your app.

Pseudocode example steps inside your workflow action YAML file (.github/workflows/update-uat-app-version.yml):

Assuming you have a distinct UAT version of your iOS app in App Store Connect and have configured eas submit correctly in your eas.json file. You can share the new Android APK with your team and notify them of the availability of a new iOS version for UAT. Alternatively, you could integrate a Slack webhook URL to post the details to a designated Slack channel!

Example GitHub Action - Deploying UAT OTAs:

Pseudocode example steps inside your workflow action YAML file (.github/workflows/deploy-uat-ota.yml):

You can read the bumped developer-facing version numbers for your UAT app using expo-constants and display it somewhere in your app as a nice way to show which UAT version of the app someone is running.

TSX
1import Constants from 'expo-constants';
2import { FC } from 'react';
3import { Text } from 'react-native';
4
5const AppVersionNumber: FC = () => {
6  return (
7    <Text>
8      {Constants.expoConfig?.ios?.buildNumber ||
9        Constants.expoConfig?.android?.versionCode}
10    </Text>
11  );
12};
13
14
15export default AppVersionNumber;

By having a UAT version of your app (besides the obvious reasons for testing...) and automatically deploying OTA updates to it, if a pull request with a native dependency change sneaks in, you should be able to catch this quite easily. Your UAT will probably blow up! 😄

Creating, Adding & Testing Plugins

Create a folder at your project root (I use "expo-plugins") with subdirectories for each module you're configuring. Then add your plugin.js files for iOS and Android.

BASH
1- expo-plugins
2  |- rn-firebase-mods
3    |- ios-plugin.js
4    |- android-plugin.js

Thereact-native-firebase package on their docs needs to be built as a static framework. To only apply static frameworks to this podfile, an iOS plugin might look like:

Next, add your plugin to your app.config.js file:

JAVASCRIPT
1plugins: [
2  './expo-plugins/rn-firebase-mods/ios-plugin',
3]

Run npx expo prebuild --clean to see your changes. Check the Podfile or build.gradle under the generated iOS/Android directories for a comment like # @generated begin firebase-mods - expo prebuild (DO NOT MODIFY). Make sure these native folders are in your gitignore. They're only for local builds and debugging plugins.

When you're ready to test, generate a new development build, download it from EAS (or build locally), and drag it onto your simulator.

BASH
1eas build --platform ios --profile development --non-interactive --no-wait --clear-cache;

EAS Local Builds setup and debugging - iOS

• Install fastlane via brew brew install fastlane.
• Install cocoapods via brew brew install cocoapods.
• Create a .env file at the root of your project directory.
• Add any build variables or injected runtime variables to your .env file.
• Next, create your local iOS EAS build:eas build --local --clear-cache --profile development --platform ios. This command will initiate a local iOS build under the development profile specified in your eas.json file. After a successful build, a file like build-123456789.tar.gz will be added to your project root. Simply double-click and unzip this file to obtain your development build, which you can then drag and drop onto the iOS simulator.
• Start your expo dev server on your mac: yarn expo start -c. Happy coding!

Environment variables help change the behaviour of your app depending on where it is, just add variables with an EXPO_PUBLIC_ prefix in .env files.

If your iOS local build fails, it can be hard to work out why. EAS cleans up the build directory by default, including all the Xcode logs. To keep the build artifacts for debugging, set these environment variables:

With those set, you can cd ~/expo/the-joe-codes-app/workdir and dig through the build logs to find the issue.

BASH
1artifacts              env
2artifacts.tar.gz       logs
3bin                    project.tar.gz
4build                  temporary-custom-build
5custom-build

I've encountered issues with pod caching on my local machine while running EAS local iOS builds. When creating local builds for iOS, EAS uses a cached set of pod files, typically located at: cd ~/Library/Caches/CocoaPods on Mac. If you're facing peculiar error messages or stuck in a debugging loop, it's worth trying the following commands:

• cd into ~/Library/Caches/CocoaPods and run pod cache clean --all.
• Clear out any Xcode cache at ~/Library/Developer/Xcode/DerivedData.
• Run expo prebuild --clean.

EAS Local Builds setup - Android

Android hasn't given me any issues. No special tricks or debugging tips here because it's just worked out of the box on my Mac.

• eas build --local --clear-cache --profile development --platform android
• Drag and drop the .apk file onto your Android simulator
• Start your expo dev server on your mac: yarn expo start -c. Happy coding!