CodePush install modes: IMMEDIATE or ON_NEXT_RESTART?

An over-the-air update is only useful if it reaches users — but restarting an app while someone is in the middle of checkout is a quick way to lose them. CodePush lets you choose when a downloaded update is applied. Here is how to pick.

The two modes you'll actually use

There is also ON_NEXT_RESUME, which applies the update when the app comes back from the background. It is a middle ground, but users can be surprised by a reload when they switch back to the app, so we rarely recommend it.

Our recommended setup

Let each release decide. Optional releases wait for the next start; releases you mark as mandatory install right away:

import CodePush from "@codeonair/code-push-react-native";

CodePush.sync({
  installMode: CodePush.InstallMode.ON_NEXT_RESTART,     // normal releases
  mandatoryInstallMode: CodePush.InstallMode.IMMEDIATE,  // releases marked mandatory
});

Call it once when your app starts. You don't need to wrap your root component — CodePush.sync() also confirms that the running update started correctly, which is what makes automatic rollback work.

Then choose per release from the CLI:

# a normal fix: users get it on their next launch
codeonair-codepush release-react shop-android -t 1.0

# an urgent fix: installs immediately
codeonair-codepush release-react shop-android -t 1.0 --mandatory

You can also flip a build to mandatory later from the dashboard, without releasing again.

Ship safely with staged rollouts

For anything bigger than a one-line fix, release to a slice of devices first:

codeonair-codepush release-react shop-ios -t 1.0 --rollout 20

Watch installs and rollbacks for that build in the dashboard, then raise the rollout to 100%.

What happens if an update crashes

The SDK keeps the previous bundle. If the new one crashes before CodePush.sync() confirms it, the next launch goes back to the previous bundle, the failure is reported in the dashboard, and that update is never offered to the device again. You can also roll back by hand at any time:

codeonair-codepush rollback shop-android

What CodePush can't change

Over-the-air updates cover your JavaScript bundle and its images and assets. New native modules, permissions or changes to native code still need a store release — and the stores allow JavaScript updates as long as they don't change the app's primary purpose.

In short: ON_NEXT_RESTART by default, IMMEDIATE for mandatory releases, and a 20% rollout for anything risky.