DEV Community: Sunny Luo

Migrating from CodePush to react-native-update: a step-by-step guide

Sunny Luo — Thu, 22 Oct 2026 08:51:01 +0000

Disclosure: I maintain react-native-update, an open-source OTA SDK for React Native, and the hosted service behind it, Cresc. This guide is written for teams that have already decided to leave CodePush. If you're still deciding, I list the other options honestly at the end.

App Center was retired on March 31, 2025, and the react-native-code-push repository is now archived. If your app still calls codePush.sync(), those checks have nowhere to go: the app keeps running whatever bundle it has and stops getting updates.

This guide moves a React Native app from CodePush to react-native-update. Your release workflow stays the same: ship JS and asset changes without a store review, roll out gradually, and roll back if something breaks. On a typical RN 0.7x+ app the code changes take an afternoon.

1. How the concepts map

Most of the work is translating concepts, so here's the cheat sheet first:

CodePush	react-native-update	Notes
App Center app (`owner/MyApp-iOS`)	App per platform (`cresc createApp --platform ios`)	Same idea: one app record per platform
Deployment key in `Info.plist` / `strings.xml`	`appKey` in `update.json`	`update.json` is generated by the CLI; commit it
`Staging` deployment	Test via QR code / deep link before binding	Scan a QR in the dashboard to load an unreleased version on a test device
`Production` deployment	Binding a version to native package(s)	Users get an update only once it's bound to their native version
`--target-binary-version "~1.1.0"`	`--packageVersionRange "~1.1.0"`	Both semver ranges
`--rollout 25`	`--rollout 25`	Same name. Bumping to 100 promotes to full
`appcenter codepush release-react`	`cresc bundle --platform ios`	Builds, publishes and (optionally) binds in one step
`codePush(options)(App)`	`<UpdateProvider client={...}>`
`checkFrequency: ON_APP_START / ON_APP_RESUME / MANUAL`	`checkStrategy: "onAppStart" / "onAppResume" / null`	`"both"` (the default) does both
`installMode: ON_NEXT_RESTART`	`updateStrategy: "silentAndLater"`
`installMode: IMMEDIATE`	`updateStrategy: "silentAndNow"`
`updateDialog: true`	`updateStrategy: "alwaysAlert"`
`codePush.notifyAppReady()`	`markSuccess()` (automatic by default)	Unmarked updates roll back on next launch
`appcenter codepush rollback`	Pause, then re-bind the previous version	Dashboard or `cresc update`

The biggest difference: there are no deployments. A published version does nothing until you bind it to one or more native versions, optionally at a rollout percentage. You do your testing before binding, using the QR code.

2. Swap the packages

npm uninstall react-native-code-push
npm i react-native-update
npm i -g react-native-update-cli
cd ios && pod install

On RN 0.60+ autolinking handles the native module. Then delete the CodePush config:

ios/<App>/Info.plist: remove CodePushDeploymentKey (and CodePushServerURL if you self-hosted)
android/app/src/main/res/values/strings.xml: remove CodePushDeploymentKey
android/app/build.gradle / settings.gradle: remove any manual codepush.gradle / :react-native-code-push lines if you added them for an old RN version

3. Point the native bundle URL at the new SDK

This is the same hook CodePush used, with a different provider.

iOS, Objective-C (AppDelegate.mm):

- #import <CodePush/CodePush.h>
+ #import "RCTPushy.h"

  - (NSURL *)bundleURL
  {
  #if DEBUG
    return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
  #else
-   return [CodePush bundleURL];
+   return [RCTPushy bundleURL];
  #endif
  }

On RN < 0.74 the method is sourceURLForBridge: instead of bundleURL; the change is the same.

RN 0.88+: the iOS template moved to the UIScene life cycle, so bundleURL() now lives in SceneDelegate.swift instead of AppDelegate. Make the change below there. If you upgraded to 0.88 with the Upgrade Helper and moved the entry point, carry RCTPushy.bundleURL() over too, or Release builds keep loading the embedded bundle and updates never apply.

iOS, Swift (AppDelegate.swift, or SceneDelegate.swift on RN 0.88+):

+ import react_native_update

  override func bundleURL() -> URL? {
  #if DEBUG
    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
  #else
-   CodePush.bundleURL()
+   RCTPushy.bundleURL()
  #endif
  }

Android, Kotlin, RN ‚â§ 0.81 (MainApplication.kt):

- import com.microsoft.codepush.react.CodePush
+ import cn.reactnative.modules.update.UpdateContext

  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
-       override fun getJSBundleFile(): String = CodePush.getJSBundleFile()
+       override fun getJSBundleFile(): String? =
+           UpdateContext.getBundleUrl(this@MainApplication)
        // ...
      }

Android, Kotlin, RN 0.82+ uses ReactHost, so pass the path as a parameter:

override val reactHost: ReactHost by lazy {
  getDefaultReactHost(
    context = applicationContext,
    packageList = PackageList(this).packages,
    jsBundleFilePath = UpdateContext.getBundleUrl(this),
  )
}

Two Android details that bite people:

If you use react-native-screens (react-navigation does), register RNScreensFragmentFactory in MainActivity.onCreate. Without it you can get a blank screen after an OTA restart.
Set crunchPngs false in the release build type. PNG crunching makes binary diffs unpredictable and the patches bigger.

Expo (SDK 50+, after npx expo prebuild): with Expo 48+ and react-native-update ‚â• 10.28.2 the bundle URL is configured automatically, so you can skip this section. Don't keep expo-updates installed alongside it, because the two conflict.

4. Replace the JS wrapper

Create the app records once. This writes update.json, which holds the appKey for each platform:

cresc login
cresc createApp --platform ios
cresc createApp --platform android

Then swap the wrapper. A typical CodePush setup:

import codePush from "react-native-code-push";

const codePushOptions = {
  checkFrequency: codePush.CheckFrequency.ON_APP_RESUME,
  installMode: codePush.InstallMode.ON_NEXT_RESTART,
};

export default codePush(codePushOptions)(App);

becomes:

import { Platform } from "react-native";
import { Cresc, UpdateProvider } from "react-native-update";
import updateConfig from "./update.json";

const client = new Cresc({
  appKey: updateConfig[Platform.OS].appKey,
  checkStrategy: "onAppResume",
  updateStrategy: "silentAndLater",
});

export default function Root() {
  return (
    <UpdateProvider client={client}>
      <App />
    </UpdateProvider>
  );
}

If you had a custom update dialog built on codePush.sync() callbacks, set updateStrategy: null and drive your UI from the useUpdate() hook:

import { useUpdate } from "react-native-update";

function UpdateBanner() {
  const { updateInfo, downloadUpdate, switchVersion, switchVersionLater, progress } =
    useUpdate();

  if (!updateInfo?.update) return null;
  // updateInfo.name / description / metaInfo come from the published version.
  // `if (await downloadUpdate()) await switchVersion()`: it resolves to false
  // when the download didn't complete, so check it before offering a restart.
  // progress.received / progress.total drive a progress bar.
  // ...
}

Mandatory updates (CodePush's -m) don't have a dedicated flag. Either use updateStrategy: "silentAndNow", or publish with --metaInfo '{"mandatory":true}' and branch on JSON.parse(updateInfo.metaInfo) in your own UI (metaInfo arrives as a string). There's a worked example in the docs.

This covers the common options. For the rest (ON_NEXT_RESUME, disallowRestart, getUpdateMetadata, clearUpdates, restartApp and the App Center CLI commands), see the full CodePush API mapping.

Rollback safety: what replaces `notifyAppReady()`

CodePush rolled back an update if notifyAppReady() wasn't called after it launched. react-native-update works the same way through markSuccess(), but the provider calls it for you 1 second after mount (autoMarkSuccess: true by default). If the new bundle crashes before that, the next launch rolls back to the previous version and reports a rollback event.

If your app does critical work after the first frame (navigation restore, remote config), mark success later instead:

const client = new Cresc({
  appKey,
  autoMarkSuccessDelayMs: 5000,
  // or return false to skip marking this launch:
  healthCheck: async () => remoteConfigLoaded(),
});

5. Upload the native baseline

This step has no CodePush equivalent, and it's what makes the patches small. Updates are shipped as binary diffs against the exact build users have installed, so upload the same artifact you send to the stores:

cresc uploadIpa build/MyApp.ipa
cresc uploadApk android/app/build/outputs/apk/release/app-release.apk
# or, if you distribute an AAB:
cresc uploadAab android/app/build/outputs/bundle/release/app-release.aab

The native version (CFBundleShortVersionString / versionName) becomes the package version that your --packageVersionRange targets. Bump it on every native rebuild. Two different builds with the same version number still work, but you lose diff reuse and the patches get bigger.

6. Publish from CI

Create an API key in the dashboard (Write permission is enough), store it as CRESC_API_TOKEN, and run the CLI. It detects CI's missing TTY and runs non-interactively; --no-interactive makes that explicit. Passing a native range and a rollout publishes and binds in one step:

# .github/workflows/ota.yml
name: OTA release
on:
  workflow_dispatch:
    inputs:
      rollout:
        description: "Rollout percentage"
        default: "10"

jobs:
  publish:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci && npm i -g react-native-update-cli
      - name: Bundle, publish and bind
        env:
          CRESC_API_TOKEN: ${{ secrets.CRESC_API_TOKEN }}
        run: |
          cresc bundle --platform ${{ matrix.platform }} \
            --name "${GITHUB_SHA::7}" \
            --description "OTA release ${GITHUB_SHA::7}" \
            --packageVersionRange ">=2.0.0 <3.0.0" \
            --rollout ${{ inputs.rollout }} \
            --no-interactive

The CodePush equivalent was roughly appcenter codepush release-react -a owner/MyApp-iOS -d Production -t ">=2.0.0 <3.0.0" --rollout 10.

Two behaviors you get without extra configuration:

On Hermes apps, the CLI compiles each release against an earlier bytecode of the same app and applies a Hermes-aware transform before diffing. In our benchmark a one-line fix ships as a 3.4 KB patch, where a plain bsdiff of the same change is 93.7 KB.
The source map is archived with each version, so JS crashes from that release show up symbolicated in the dashboard.

7. Test, roll out, roll back

Before binding, enable "Use Deep Link" in the dashboard for your app's URL scheme and scan the version's QR code on a test device. That loads the exact unreleased bundle, which replaces what you used Staging for. (The Android activity needs launchMode="singleTask" and an intent filter for the scheme.)
Bind at a low percentage. Buckets are a stable hash of the device ID, so the same users stay in the canary as you widen it. Each native version can have one canary and one full release at the same time.
Watch the version's health in the dashboard: download failures, patch failures, rollbacks and symbolicated JS errors.
Promote by raising the rollout to 100, which replaces the previous full release.
If it's bad, pause the native package's updates and re-bind the previous version, or revert in git and publish a new version. Devices that crashed on launch have already rolled themselves back.
If JS is dead on some devices (white screen, crash before the update check runs), publish the fix with Force Boot. Since 10.52.1 the SDK runs a native cold-start check that doesn't depend on JS, so those devices can still pull the fix.

8. The transition period

Users on old binaries keep their last CodePush bundle. Nothing breaks, but they won't get updates until they install the new store build. Prioritize getting the first react-native-update build out.
You can't send an OTA to CodePush users. The migration needs one native release. Plan it like any store submission.
If you self-hosted a CodePush server, you can keep it running for old binaries while new binaries use react-native-update. The two don't interact.
Once nobody is on the old binaries, delete the App Center tokens from CI and remove the CodePush server.

Other options, honestly

Self-host CodePush. Before App Center retired, Microsoft open-sourced a standalone CodePush server. If you'd rather run your own infrastructure and keep the existing SDK, this is the smallest code change. Note that the server and the client SDK are both archived now, so you take on hosting and maintaining both.
Expo Updates (EAS Update). A great fit if you already use EAS for builds. It ships full bundles instead of diffs and bills by update MAU and bandwidth, which matters at scale.
react-native-update / Cresc. Hermes-aware binary diffs, staged rollouts, automatic rollback and built-in crash symbolication. The SDK, CLI and admin dashboard are open source and there's a free tier.

Questions about a specific setup (brownfield, monorepo, custom bundle names) are welcome in the comments.

Why Hermes bytecode defeats binary diffing — and how we got a one-line OTA hotfix down to 3.4 KB

Sunny Luo — Thu, 08 Oct 2026 10:55:23 +0000

Disclosure: I maintain react-native-update, the open-source SDK behind Cresc, an OTA update service for React Native. The benchmark code and data are public, and the technique applies to anyone shipping Hermes bundles.

If you ship React Native over-the-air updates, you've probably assumed binary diffing solves the bandwidth problem: compute a bsdiff between the old and new bundle, send the patch, done. With plain JS bundles that's mostly true. With Hermes bytecode it isn't, and the reason is interesting.

We measured on real release bundles of a React Native 0.86 app (Hermes HBC v98, with common dependencies like Paper, SVG, Sentry and CameraKit; ~1.5 MB gzipped):

Release scenario	Full bundle (gzip)	Classic bsdiff	Hermes-aware diff
One-line text change	1,544.6 KB	93.7 KB	3.4 KB (28× smaller)
Small feature (+1 component, ~60 LOC)	1,555.8 KB	411.6 KB	50.2 KB (8.2× smaller)
Medium feature (+2 screens, ~300 LOC)	1,604.7 KB	551.6 KB	97.8 KB (5.6× smaller)

A one-line change producing a 94 KB bsdiff patch is the giveaway: something is amplifying tiny source edits into large binary changes.

Problem 1: the string table is re-sorted on every compile

Hermes stores strings in a table and refers to them by ID throughout the bytecode. On every compile it sorts that table by identifier frequency, so a one-line change perturbs the frequencies and renumbers dozens or hundreds of string IDs. Every instruction that references a shifted ID changes too.

Result: two builds that differ by one line of JS end up differing in bytes all over the file. A generic diff algorithm sees thousands of scattered edits.

Fix: Hermes has a delta mode (hermesc -base-bytecode=<base>). Compiling every release against the root bytecode of its version chain pins existing string IDs in place, so only code that actually changed shows up in the diff.

A free 21%: move debug info out

Hermes embeds debug info in the bytecode by default. Compiling with -output-source-map moves it into an external .map, which shrinks the bytecode by about 21% before any diffing happens. You keep the map for symbolicating crashes; it just doesn't ship in every patch.

Problem 2: offset tables amplify every insertion

Hermes bytecode is full of tables that store absolute offsets: function headers, string storage, and so on. Insert a few bytes near the start and every offset after that point changes. Again, a tiny edit becomes a wide diff.

Fix: before diffing, apply a reversible transform that delta-encodes the offset fields (wrapping subtraction), so a global shift collapses into a single-point change. The client applies the patch and then runs the inverse transform to get the exact target bytecode. On top of the first two layers, this cuts patches by a further 9–36%.

The three layers are independent and their gains stack. They matter most for small changes, which is exactly the hotfix case OTA exists for.

Making it safe

Clever transforms are only worth it if they never brick an app:

Bit-exact round trip: every patch is checked so that inverseTransform(patch(transform(old))) == new, byte for byte.
Instruction-level equivalence: delta-mode builds are disassembled and compared with plain builds instruction by instruction. On any mismatch the delta build is discarded and the plain build ships. (Benchmarking this turned up a verifier bug that wrongly flagged UIntSwitchImm jump tables and silently threw away valid delta builds. That's fixed now.)
No Hermes-specific client code: the table layout descriptors ship inside the patch metadata, so the client's patcher is version-agnostic, and supporting a new Hermes version is a CLI-side config change.

Reproduce it

The benchmark harness and raw data are here: https://github.com/sunnylqm/hbc-diff-benchmark. I'd love to see numbers from other apps, especially large ones. If your results differ, open an issue.

Using it

The diffing is built into react-native-update (open source, around since 2016) and the hosted service Cresc. There's a free tier, and teams moving off CodePush can use the migration checklist.

Questions about Hermes internals or OTA pipelines are welcome in the comments.