Introduction
So you’ve got a React Native application and things are going well: you write code and when you’re ready to release to your customers, you create your Google Play and App Store builds, fill in all the information, submit your builds and now you wait for the approval or rejection. Have you ever thought to yourself “Man, I wish I could skip the stores for this critical bug fix I have?” Well, you’re in luck! Visual Studio App Center and, more specifically, CodePush allow you to do exactly that! Read on to learn more about CodePush, Visual Studio App Center, and how to use it with React Native.
What is Visual Studio App Center?
Visual Studio App Center is a free (the free version is limited to a certain amount of build minutes per month, 1 build at a time, and a 30 day trial of testing) suite of tools that help you Build, Test and Distribute your applications. There’s a wide range of platforms that are supported: native iOS apps, native Android apps, Windows apps, Xamarin apps, and, of course, React Native apps!
Build allows you to set up a pipeline for building your application, instead of doing it on your own machine. This allows for a consistent build experience, and for anyone to make a build with the latest code without having to set up the project on their own machine, so nice!
Test allows you to test your application using an automated testing framework (like Appium) on a number of devices (like the latest iPhones and Android devices). This can be very helpful since you probably don’t have 400+ phones lying around (and if you do, we may need to talk…), and testing on multiple device sizes and versions is important when building a mobile application.
Distribute allows you to create groups and release builds to internal testers (think other teammates, people in your company), the app stores, or to your customers directly (this is where CodePush comes in)! You can set up groups of people to distribute to, and they can download the latest builds directly from Visual Studio App Center, no need for TestFlight or Google Play Beta!
Now that you have an overview of Visual Studio App Center, let’s dive in further to CodePush, the whole reason we’re here!
What is CodePush and what are the limitations?
CodePush is a service that belongs to Visual Studio App Center, that allows you to push updates to your applications without having to go through the Google Play Console or the App Store. The only officially supported platform for CodePush as of this writing is React Native. Cordova used to be a supported platform, but that was retired from service in early 2022.
There are some limitations to be aware of with using CodePush, as not all changes are eligible to be used. Builds that are eligible are limited to only those that modify HTML, CSS, JS and images. Whenever a new binary needs to be built (like changes to native code, or adding new Native Modules), you’ll have to go through Google Play and the App Store. You can find a list of changes that disqualify you from using CodePush for a build here.
Additionally, you also are not allowed to drastically change your application without going through an app review, as per the Apple Developer Program License Agreement, Section 3.3.2.
With those caveats in mind, let’s look at some alternatives to CodePush for a React Native application.
What are the alternatives to CodePush for React Native?
The other easily available option for Over the Air (OTA) Updates is to use Expo . They have a service called EAS Update, which uses the expo-updates library to perform OTA updates. Up until a couple of years ago, you needed to integrate with Expo to use this feature, but now it’s available to use as a standalone with React Native apps, much like CodePush.
EAS Update has similar limitations as Visual Studio App Center: you can only push JS Bundle changes directly to your customers, and anything that changes the native projects will require deploying a build to the stores. EAS Updates has many of the same features as CodePush, and really it comes down to preference if you want to use this service. I’d recommend browsing through their documentation.
Setup and Installation
Now it’s time to get this show on the road! You’ll first want to make sure you have an app setup for each platform you want to support inside of AppCenter. You can also install AppCenter Analytics to easily see which versions are installed for your user. You can find detailed instructions for setting up apps in AppCenter and installing Analytics here.
To get started with CodePush, you’ll have to go into each of your App Center projects (the iOS and Android projects) and navigate to Distribute -> CodePush and click on `Create Standard Deployments`. This will create `Staging` and `Production` deployments, with the default instructions being for `Staging`.
We will now want to install the App Center CLI with npm i -g appcenter-cli and we’ll want to add the CodePush SDK to the app, you can find detailed instructions for installing here.
Once you are all set up, make a small update to your HTML (like changing a word) and then you can push an update simply by running:
appcenter codepush release-react -a <insert App Center owner name>/<insert App Center App Name> -d Staging
Assuming you pointed your app to the staging environment, you should see a new release in the Staging environment in the Code Push section of App Center. If you run your app on a physical device, it will download the update and the next time you restart your app, you should see your changes. And voila, you now have CodePush working!
How Does CodePush Work?
By default, CodePush will download updates when the user starts your application and apply them the next time the app restarts. There are no prompts, or really any indication that this process is happening. However, you can configure CodePush’s behavior with many different options!
You can find the full API reference here, but there are a few things I want to point out:
- You have to specify a target version when making a release, and you can use a wild character to target multiple versions (ex: 1.0.x, or 1.1.1 – 1.2.2, >= 1.1.1)
- You can mark your builds as Mandatory, so that everyone will receive the update, regardless of choice. This can be done when you go to release a build with the CLI and use the -m flag. This can also be done in the Release UI by editing and toggling Required Update
- You can prompt a user for permission before downloading an update by setting updateDialog: true. If a build is set to Mandatory, the user will not get to choose whether to install it or not, but will still get notified
- You can change the frequency of when AppCenter checks for updates by setting the checkFrequency option, and you can choose when optional updates get installed by setting installMode
- If a user is offline, nothing changes with your application. No updates will be installed, but your users will also not get stuck
Recommendations on Using CodePush
Keep your secrets in your CI/CD pipeline
As mentioned a few times before, you never want to commit your app_secret to your repository. Instead, you can set these in your build/CI/CD pipelines. App Center allows you to do this for React Native, you can find instructions on that here. Keep in mind that for the free tier, you are limited on how many build minutes you can use in a month, and are also limited to 1 concurrent build at a time.
Multi-environment deployments
If you noticed when you set up CodePush, App Center automatically created two environments for you: Staging and Production. This is great for testing out your changes before they reach your customers. Ideally, you would develop your changes, create a Staging CodePush release, test with a build of your app that is pointed at the Staging environment, and then promote that release to Production, where your customers can enjoy the update themselves.
Create scripts for your deployment commands
While going through the all of the set up steps, you probably got tired of typing in commands, or searching through your terminal history. There’s an easy way around that, so you don’t have to memorize a single thing (or have to tell others): create some scripts! In your package.json file, under the scripts property, you can define custom scripts like codepush-deploy-staging-ios, that will run a command for creating an iOS Staging deployment. I would highly recommend doing this for all of your apps and environments!
Conclusion
And thus concludes our journey of getting CodePush to work with React Native. We looked at what Visual Studio App Center is, how to get started with Analytics and CodePush, and some recommendations for going forward. Gone are the days where you have to submit to the App Store and Google Play Console for every single change. Happy Pushing!