Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 71 ยท Shipping

Over-the-Air Updates and Release Strategy

Ship JavaScript fixes without store review using EAS Update: runtime versions, channels, rollbacks, staged rollouts and what the store rules allow.

Store review can take hours or days, and every fix needs a new build that users must download. For a typo, a broken button or a wrong API address, that is painfully slow. React Native has a special advantage here: most of your app is JavaScript and assets, and those can be replaced on the phone without a store release. This is called an over-the-air (OTA) update.

Expo's service for this is EAS Update with the expo-updates library. This lesson explains how it works, why the runtime version is the most important setting, how channels and rollouts let you release carefully, how to roll back, and where the limits are (native code, and the store rules).

Read-only and stand-in. Updates are downloaded from Expo's servers by a real app, so the commands and config are shown in plain blocks. The TryIts are stand-ins that imitate the decision a phone makes ("which update may I run?") and a percentage rollout. Command names and flags evolve, so run eas update --help and read the current docs before relying on a specific option.

What can and cannot be updated

A React Native app has two layers:

  • Native layer: the compiled binary from the store: Hermes, React Native itself, native libraries (camera, notifications, maps), permissions and app.json settings that end up in native files. Changing it needs a new build and a store release.
  • JavaScript layer: your components, logic, styles and bundled assets (images, fonts), packaged as a bundle. This layer can be swapped by an OTA update.

So an update can fix a bug in a screen, change copy, tweak a layout or alter a request. It cannot add a new native library, change a permission, upgrade the React Native version or edit native code. Run an update that calls a native module the installed binary does not contain, and the app crashes at that call. This is the reason for the runtime version.

Setting it up

Terminal
npx expo install expo-updates
eas update:configure

The configure step adds the update URL for your project and a runtime version to your app config:

JSON
{
  "expo": {
    "version": "2.4.0",
    "runtimeVersion": { "policy": "appVersion" },
    "updates": {
      "url": "https://u.expo.dev/<your-project-id>"
    }
  }
}

Builds made with a profile that has a channel (see Builds with EAS and App Store Submission) will look for updates on that channel. After that, publishing is one command:

Terminal
eas update --channel production --message "Fix crash on empty cart"

By default the app checks for an update when it launches, downloads it in the background and runs it the next time it starts. This is deliberate: swapping code under a screen the user is looking at would be jarring. You can change that behavior, for example to download and reload on demand:

TSX
import * as Updates from 'expo-updates';

export async function checkNow() {
  const result = await Updates.checkForUpdateAsync();
  if (result.isAvailable) {
    await Updates.fetchUpdateAsync();
    await Updates.reloadAsync(); // restart the app with the new bundle
  }
}

Use that sparingly: restarting the app unprompted loses what the user was doing. A common pattern is to download silently and show a small "Update ready, restart" message.

Runtime versions: the compatibility contract

The runtime version is a string that says "this binary has this exact set of native code". An update is tagged with the runtime version it was built for, and a phone only accepts updates whose runtime version equals the one baked into its binary.

flowchart LR
    U["Update tagged runtime 2.4.0"] --> A["Phone with binary 2.4.0"]
    U -. "not delivered" .-> B["Phone with binary 2.3.0"]
    A --> C["Runs new JavaScript"]
    B --> D["Keeps its current bundle"]

Only phones with a matching runtime version receive the update.

Your job is to change the runtime version whenever the native layer changes, and keep it the same when only JavaScript changes. Expo gives you policies so you do not do this by hand:

  • appVersion: the runtime version is your app version. Simple, but you must bump version when native code changes.
  • fingerprint: Expo hashes the native parts of your project (native dependencies, config, plugins) and uses the hash. Any native change produces a new runtime version automatically, which is the safest option.
  • A fixed string you manage yourself, if you want full control.

If you forget this and publish a JavaScript update that needs a new native library to old binaries, it can crash them. With a correct runtime version it is simply not delivered to them.

Channels and branches

Updates are published to a branch (a named stream of updates, much like a Git branch), and builds listen to a channel. A channel points at one branch, and you can repoint it.

  • Builds made with the preview profile listen to the preview channel, builds made with production listen to production.
  • You publish a risky change to the preview channel first, test it on real devices, and then publish the same change to production.

This gives you the same staging-to-production flow as a web deploy, with two safety rails: the runtime version keeps updates away from incompatible binaries, and the channel keeps experiments away from real users.

Rollouts and rollbacks

A bug that reaches 100% of your users at once is the worst case. Two tools limit it:

  • Gradual rollout: serve an update to a percentage of users first (for example 10%), watch crash reports and analytics, then widen to 100%. EAS supports rolling out between two branches on a channel; the exact command is eas channel:rollout, so check its help output for the current flags.
  • Rollback: if an update is bad, you can republish an older update, or roll back so that devices go back to the bundle embedded in the binary (eas update:rollback). Phones pick the change up the next time they check, so a rollback is fast but not instant: someone who already downloaded the bad update runs it until the next launch check.

Prepare for failure before it happens: ship crash reporting first (the next lesson, Crash Reporting and Analytics), because a rollout is only safe if you can see whether it is going wrong. expo-updates also falls back to the previous working bundle if a new one fails to load at startup, but it cannot protect you from a bug that appears later, deep inside a screen.

What the stores allow

Apple and Google both allow apps to download JavaScript and assets that are run by the system's JavaScript engine, with limits. The rules are written by the stores and change over time, so read the current guidelines. In general:

  • An update must not change the primary purpose of the app or add a different kind of product than the one that was reviewed.
  • It must not be used to dodge review for features that need it (for example turning on prohibited content), to download executable native code, or to be deceptive.
  • Bug fixes, small content and UI changes and A/B tests are the ordinary, expected use.

When in doubt, ship a new store build for big changes and use OTA for the small, fast ones. You also still need store releases for native changes, new permissions, and React Native or Expo SDK upgrades.

What OTA can touch

JavaScript Screens, logic, requests.
Assets Images, fonts, JSON files.
Not native Libraries, permissions, RN version.
1 / 2

Stand-in: which update does the phone run?

The function below imitates the choice a device makes. It keeps only updates whose runtime version and channel match, picks the newest, and honors a rollback entry by returning to the embedded bundle. This is the idea, not the real expo-updates protocol.

JS Update picker: runtime version and channel

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Update a4 exists, but nobody gets it: no installed binary has runtime version 2.5.0 yet. That is the runtime version protecting old binaries from code written for a newer native layer. After the rollback entry is published, only the 2.4.0 production devices change behavior.

Stand-in: a percentage rollout

How does a rollout choose 25% of users? A simple idea is to turn each device into a stable bucket from 0 to 99 and give the update to buckets below the percentage. Stable matters: a device must not flip in and out of the rollout between launches. The slider below uses a small hash to show the effect (at the starting 25% it gives the update to 4 of the 20 devices). EAS has its own mechanism; this is only the principle.

Rollout percentage slider

Drag the slider up: green devices stay green and new ones join, because each device keeps its bucket. That property is what lets you widen a rollout safely.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which change can be shipped as an over-the-air update?

    OTA updates replace JavaScript and assets. Native libraries, permissions and the React Native version live in the binary and need a new store build.
  2. 2. What does the runtime version protect against?

    An update is only delivered to binaries with the same runtime version, so code that needs new native modules never reaches old binaries.
  3. 3. By default, when does the new update start running after it is downloaded?

    By default the app downloads in the background and runs the update on the next start. You can call reloadAsync yourself for an immediate restart.
  4. 4. Why is a staged rollout valuable?

    Only a share of users get the change first, so a bug affects fewer people and you can stop or roll back.
  5. 5. Which is a safe use of OTA updates under the store rules?

    Small fixes and content or UI changes within the reviewed app are the normal use. Changing the app's purpose or evading review is not allowed.

Summary

  • OTA updates replace the JavaScript bundle and assets; native code, permissions and the React Native version still need a store build.
  • expo-updates checks on launch and, by default, runs a downloaded update on the next start; reloadAsync restarts at once.
  • The runtime version is a compatibility contract: change it when native code changes (a fingerprint policy automates this).
  • Channels connect builds to branches, so you can test on preview before production.
  • Use staged rollouts and rollbacks, and watch crash reports while rolling out.
  • Stay within the store rules: fixes and small changes are fine, changing the app's purpose is not.

Next, make sure you can see problems at all in Crash Reporting and Analytics.