React Native module for CodePush
Visual Studio App Center was retired on March 31, 2025, except for its Analytics and Diagnostics features. You can learn more about the retirement and the Analytics and Diagnostics extension here. CodePush, along with other App Center features, was also retired on March 31, 2025. Consequently, we are archiving this repository.
[!WARNING] React Native CodePush won't support new Architecture. In order to use this plugin on React Native versions starting from 0.76 you will need to opt out from new architecture.
Note: This README is only relevant to the latest version of our plugin. If you are using an older version, please switch to the relevant tag on our GitHub repo to view the docs for that particular version.
This plugin provides client-side integration for the CodePush service, allowing you to easily add a dynamic update experience to your React Native app(s).
A React Native app is composed of JavaScript files and any accompanying images, which are bundled together by the metro bundler and distributed as part of a platform-specific binary (i.e. an .ipa or .apk file). Once the app is released, updating either the JavaScript code (e.g. making bug fixes, adding new features) or image assets, requires you to recompile and redistribute the entire binary, which of course, includes any review time associated with the store(s) you are publishing to.
The CodePush plugin helps get product improvements in front of your end users instantly, by keeping your JavaScript and images synchronized with updates you release to the CodePush server. This way, your app gets the benefits of an offline mobile experience, as well as the "web-like" agility of side-loading updates as soon as they are available. It's a win-win!
In order to ensure that your end users always have a functioning version of your app, the CodePush plugin maintains a copy of the previous update, so that in the event that you accidentally push an update which includes a crash, it can automatically roll back. This way, you can rest assured that your newfound release agility won't result in users becoming blocked before you have a chance to roll back on the server. It's a win-win-win!
Note: Any product changes which touch native code (e.g. modifying your AppDelegate.m/MainActivity.java file, adding a new plugin) cannot be distributed via CodePush, and therefore, must be updated via the appropriate store(s).
We try our best to maintain backwards compatibility of our plugin with previous versions of React Native, but due to the nature of the platform, and the existence of breaking changes between releases, it is possible that you need to use a specific version of the CodePush plugin in order to support the exact version of React Native you are using. The following table outlines which CodePush plugin versions officially support the respective React Native versions:
| React Native version(s) | Supporting CodePush version(s) |
|---|---|
| <0.14 | Unsupported |
| v0.14 | v1.3 (introduced Android support) |
| v0.15-v0.18 | v1.4-v1.6 (introduced iOS asset support) |
| v0.19-v0.28 | v1.7-v1.17 (introduced Android asset support) |
| v0.29-v0.30 | v1.13-v1.17 (RN refactored native hosting code) |
| v0.31-v0.33 | v1.14.6-v1.17 (RN refactored native hosting code) |
| v0.34-v0.35 | v1.15-v1.17 (RN refactored native hosting code) |
| v0.36-v0.39 | v1.16-v1.17 (RN refactored resume handler) |
| v0.40-v0.42 | v1.17 (RN refactored iOS header files) |
| v0.43-v0.44 | v2.0+ (RN refactored uimanager dependencies) |
| v0.45 | v3.0+ (RN refactored instance manager code) |
| v0.46 | v4.0+ (RN refactored js bundle loader code) |
| v0.46-v0.53 | v5.1+ (RN removed unused registration of JS modules) |
| v0.54-v0.55 | v5.3+ (Android Gradle Plugin 3.x integration) |
| v0.56-v0.58 | v5.4+ (RN upgraded versions for Android tools) |
| v0.59 | v5.6+ (RN refactored js bundle loader code) |
| v0.60-v0.61 | v6.0+ (RN migrated to Autolinking) |
| v0.62-v0.64 | v6.2+ (RN removed LiveReload) |
| v0.65-v0.70 | v7.0+ (RN updated iPhone-target-version) |
| v0.71 | v8.0+ (RN moved to react-native-gradle-plugin) |
NOTE: react-native-code-push versions lower than v5.7.0 will stop working in the near future. You can find more information in our documentation.
We work hard to respond to new RN releases, but they do occasionally break us. We will update this chart with each RN release, so that users can check to see what our "official" support is.
When using the React Native assets system (i.e. using the require("./foo.png") syntax), the following list represents the set of core components (and props) that support having their referenced images and videos updated via CodePush:
| Component | Prop(s) |
|---|---|
Image |
source |
MapView.Marker (Requires react-native-maps >=O.3.2) |
image |
ProgressViewIOS |
progressImage, trackImage |
TabBarIOS.Item |
icon, selectedIcon |
ToolbarAndroid (React Native 0.21.0+) |
actions[].icon, logo, overflowIcon |
Video |
source |
The following list represents the set of components (and props) that don't currently support their assets being updated via CodePush, due to their dependency on static images and videos (i.e. using the { uri: "foo" } syntax):
| Component | Prop(s) |
|---|---|
SliderIOS |
maximumTrackImage, minimumTrackImage, thumbImage, trackImage |
Video |
source |
As new core components are released, which support referencing assets, we'll update this list to ensure users know what exactly they can expect to update using CodePush.
Note: CodePush only works with Video components when using require in the source prop. For example:
<Video source={require("./foo.mp4")} />
Once you've followed the general-purpose "getting started" instructions for setting up your CodePush account, you can start CodePush-ifying your React Native app by running the following command from within your app's root directory:
npm install --save react-native-code-push
As with all other React Native plugins, the integration experience is different for iOS and Android, so perform the following setup steps depending on which platform(s) you are targeting. Note, if you are targeting both platforms it is recommended to create separate CodePush applications for each platform.
If you want to see how other projects have integrated with CodePush, you can check out the excellent example apps provided by the community. Additionally, if you'd like to quickly familiarize yourself with CodePush + React Native, you can check out the awesome getting started videos produced by Bilal Budhani and/or Deepak Sisodiya .
NOTE: This guide assumes you have used the react-native init command to initialize your React Native project. As of March 2017, the command create-react-native-app can also be used to initialize a React Native project. If using this command, please run npm run eject in your project's home directory to get a project very similar to what react-native init would have created.
Then continue with installing the native module
With the CodePush plugin downloaded and linked, and your app asking CodePush where to get the right JS bundle from, the only thing left is to add the necessary code to your app to control the following policies:
When (and how often) to check for an update? (for example app start, in response to clicking a button in a settings page, periodically at some fixed interval)
When an update is available, how to present it to the end user?
The simplest way to do this is to "CodePush-ify" your app's root component. To do so, you can choose one of the following two options:
Option 1: Wrap your root component with the codePush higher-order component:
For class component
import codePush from "react-native-code-push";
class MyApp extends Component {
}
MyApp = codePush(MyApp);
For functional component
import codePush from "react-native-code-push";
let MyApp: () => React$Node = () => {
}
MyApp = codePush(MyApp);
Option 2: Use the ES7 decorator syntax:
*NOTE: Decorators are not yet supported in Babel 6.x pending proposal up
No open issues yet, or sync has not completed.