Docs
BlogChangelogStar us on GitHub
HomeGuidesExpo ServicesReferenceLearn
ArchiveExpo SnackDiscord and forumsNewsletter

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Migrate from CodePush

Edit page

A guide to help migrate from CodePush to Expo Update.

This guide explains how to transition a React Native project that uses CodePush to use Expo Update which offers many advantages. It assumes that you're using the default React Native project structure. For assistance with migrating brownfield native apps to Expo Update, see Using Expo Update in an existing native app.

To learn more about the differences between CodePush and Expo Update, see Conceptual differences between CodePush and Expo Update and the What to do without CodePush post on the Expo Blog.

1

Ensure your app is using the latest Expo SDK version

To migrate from CodePush to Expo Update, we recommend that you use the latest Expo SDK version. Instructions are not available for older Expo SDK and React Native version. While you may be able to migrate successfully by adapting the instructions as needed for the older Expo SDK and React Native version that your app uses, additional hands-on support for integrating with older versions can only be provided for enterprise customers (contact us).

2

Uninstall CodePush

To avoid conflicts and unexpected behavior, it's recommended to uninstall CodePush if you're using Expo Update. This is because your app could periodically fetch updates from both services, leading to issues, especially if you're using different configurations for each service.

Remove the CodePush SDK from your project by uninstalling the react-native-code-push package:

Terminal
- npm uninstall react-native-code-push

You'll also need to remove CodePush references from JS and native code. See this GitHub comment for more detailed instructions.

3

Add an expo key to your app.json

Ensure that your project has an app.json file with an expo object. If you don't have anything specific to configure in your app.json file yet, you can create a minimal file with an empty expo object like this:

app.json
{
  "expo": {
    //... any other existing keys you have
  }
}

4

Follow the "Getting Started" guide

The instructions in the Expo Update Getting Started guide will guide you through setting up Expo Update in your project.

5

Resubmit your app

Since you have changed the update provider from CodePush to Expo Update, you will need to rebuild your app and submit the new build to the respective app stores (Google Play Store and Apple App Store) to ensure the update mechanism works as expected for your end-users.

Follow the respective store guidelines for submitting a new build of your application:

After successfully submitting your app, users will be able to download and use the latest build with Expo Update integration. If your app is not updating as expected, validate your configuration.

Common questions

How do I release mandatory/critical updates with Expo Update?

CodePush CLI has a --mandatory flag that allows you to release mandatory updates. You can build this functionality with Expo Update but there is no specific flag for it.

Learn more about mandatory/critical updates.

How do I include a message in an update?

CodePush CLI has a --description flag that allows you to include a message in an update. You can build this functionality with Expo Update using the extra field in your app config.

Refer the --message flag in this example: expo/UpdatesAPIDemo.

How do I switch the 'deployment' that is being used at runtime, similar to the sync() function in CodePush?

This is possible using Updates.setUpdateURLAndRequestHeadersOverride(). Learn more in the Override update configuration at runtime guide.

How do I handle different environments (such as staging and production) with Expo Update?

With Expo Update, you can use channels and branches to manage different environments and rollouts. See how to manage branches and channels with EAS CLI.

How do I roll back updates with Expo Update?

You can roll back updates using eas update:rollback. Learn more in the Rollback to a previous update guide.

How do I gradually roll out updates with Expo Update?

Expo Update supports various strategies for gradually rolling out updates, so you can pick which approach best fits your needs. See the rollouts guide.

How can I have direct control over when an update is downloaded and applied?

Learn more about different strategies for downloading and applying updates in the Downloading updates guide, such as checking for updates while the app is running or even when backgrounded with Updates.checkForUpdateAsync().

Does Expo Update support end-to-end code signing?

Yes, Expo Update supports end-to-end code signing. It is available for Production and Enterprise plan subscribers. Learn more in the Code signing guide.

What else should I know about?
  • Expo Orbit: The macOS, Windows, and Linux desktop launcher app. You can launch updates directly from the website with it in one click, among other features.
  • You can monitor the adoption of updates from the Expo website. See monitoring adoption of updates. You can also roll out and roll back updates from the website.
  • You can use Expo Update to achieve a web-like preview workflow. See how to preview updates.
  • Each update and build created with Expo Services is associated with a fingerprint. You can diff these fingerprints through the website UI or with eas fingerprint:compare to see what changed in the native runtime of your app between your builds and updates, to understand build/update compatibility, and guide your decision about when to bump the runtimeVersion.

Conceptual differences between CodePush and Expo Update

CodePush and Expo Update are both services that allow you to send hotfixes to the JavaScript code of your app, but they take slightly different approaches, and so you may need to adapt your release process when moving to Expo Update.

Differences in how updates are organized within streams

CodePush has single streams of updates for deployments. What this means is that you can point a build to a deployment, and it will pull updates from that. If you want to change the deployment that is targeted by a build, you can do this at runtime through a JavaScript API.

Expo Update has multiple streams of updates — one that corresponds to your source control branches (called branches), and another called channels, which point to branches. The mapping between channels and branches is handled on the server side, and a channel can point to different branches for each runtime version (additionally, more advanced logic may be expressed, such as to support incremental rollouts). Builds are not directly associated with branches, but rather with channels. Each build points to a single channel by default. The reason for this is that it ensures that certain branches (for example: development, staging) don't automatically go out to production, so your preview updates don't go to your production users. This helps you separate the two main uses of Expo Update: previews and production hotfixes.

Differences in how updates are selected at runtime

A key distinction between CodePush and Expo Update that can impact your release process is that with CodePush, the client controls the target update deployment at runtime, and with Expo Update, the default path is controlled on the server side, by mapping channels to branches. In the default Expo Update flow, a build requests updates for its configured channel, and Expo Update returns the latest compatible update from the branch mapped to that channel.

The ability to control the target deployment at runtime is commonly used with CodePush in staging environments to allow non-technical stakeholders to test features from a single build on Google Play Beta and TestFlight. With Expo Update, you can achieve the same with channel surfing. This allows you to switch update channels in non-development builds at runtime. Development builds can also load updates from any compatible channel and are a good fit for developer-focused testing.