Understanding Expo Runtime Version, Version Code and Build Number
If you are building React Native Applications, knowing what expo runtime version, android version code and ios build numbers stand for and how they are used will help you setup applications properly for updates.
Why?
The reason is simple; to manage updates. Updates with React Native applications when using Expo are primarily of two forms:
- Store Updates: when you create a new build for your app and make a submission to the stores (i.e Apple App store or Google Playstore)
- Over the Air Updates: when you make minor changes to your app e.g changing color, text, images, etc which you want to simply send ‘over the air’ to your customers without going through the store approval process
Version Code and Build Number
Android Version Code and iOS Build Number are essentially how the stores track changes to your app (i.e know that you have a new app that you would like to serve to your customers).
Android Version Code are positive integers i.e 1,2,3,4,5, etc. The value is set in app.json file or app.config.js under the android field. See sample below:
"android": {
"versionCode": 1,
...
}While IOS Build numbers follow the semver methodology of versioning apps (i.e major.minor.patch) e.g 1.1.2and is set in app.json as well. See sample below:
"ios": {
"buildNumber": "1.0.0"
...
},Expo Runtime Version
Everytime you create a build with expo servers, expo also needs a way to track the builds you are creating — similar to the stores. Expo uses the app runtimVersion for this.
Now, you are probably wondering, what’s a sane way to keep track of all of these numbers and coventions? For this, expo provides a convenient method for setting the runtime version by allowing you to set a policy which can either be:
- nativeVersion: this uses the Android Version Code and Build Number as the expo runtime version
- appVersion: this uses the app version which is used to track the app version which is exposed to the users
"runtimeVersion": {
"policy": "appVersion"
},Some other people/teams do not use the policy — and simply uses a convention e.g positive integers to track runtimeVersion : the potential pitfall for this is that it can get confusing for new team members and might not make sense.
Over The Air Updates
When you release new builds and you need to deploy over the air updates, expo uses the runtime version of the app to deliver the update e.g if the current runtimeVersion for an android app is 2; expo will only be able deliver updates to users on runtimeVersion of 2.
Conclusion/Recommendation
Prefer using Development Builds as opposed to Expo Go for your development as the app behave very close to actual builds that will be used by customers.
Kindly ensure that your OTA updates do not cause your app to crash during load — you may have to make a submission to the store to resolve this.
Ensure to have a mechanism in place that allows all users to have the latest native builds of your app. You can have a json file somewhere for tracking the latest build number and versionCode and direct the customers to the store to update their app.
While over the air updates allows you deliver updates without going through the stores, new customers who install your app may not necessary get those updates (e.g due to network failure) so I will suggest having a policy in place to create new native builds and submit to the stores say every 90days (this the duration builds use on TestFlight) so that all the updates delivered over the air are always readily available to customers.
Background
Sometime in 2023, I wrote about my frustration in understanding these terminologies in this article and it somehow continues to get view weekly so I thought to write a proper article about it.
