Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท EAS Build and Updates

Over-the-Air Updates with EAS Update

Ship JavaScript fixes to Expo apps without a store review: expo-updates, channels and branches, runtimeVersion policies, rollbacks, update checks in code and safe practices.

A store release takes hours or days, and users update when they feel like it. But a typo, a broken button or a wrong API path is just JavaScript, and your app's JavaScript is a bundle of files. EAS Update lets the installed app download a newer bundle straight from Expo's servers, the next time it starts. No review, no waiting, no reinstall.

This is powerful and has one hard rule: an update may only change JavaScript and assets. The native code in the installed binary cannot change. So every update must be compatible with the native binary it lands on. Expo calls that compatibility the runtime version.

What runs on this site. Updates need real builds and Expo's servers, so commands and config are read-only. The runnable stand-ins implement the matching rules (runtime version and channel) and a rollout in plain JavaScript.

What goes where

flowchart LR
  subgraph Binary["Installed binary (store build)"]
    N["Native code and libraries"]
    J1["Embedded JS bundle v1"]
  end
  S["EAS Update server"] -->|"newer JS, same runtimeVersion"| J2["Downloaded JS bundle v2"]
  J2 --> Binary

The update replaces the JavaScript bundle. The native code stays.

You can update: components, logic, styles, images and fonts bundled with the app. You cannot update: a new native library, new permissions, changed app.json native settings (icon, splash, bundle id), or a new Expo SDK version. Those need a new build.

Setup

Terminal
npx expo install expo-updates
eas update:configure

This adds config like the following (app.json):

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

and a channel to each build profile in eas.json ("channel": "production"). Rebuild once so the binary knows its channel and runtime version.

Runtime versions

The runtime version is a label of the native layer. An update is delivered only to binaries with the same runtime version string. Policies:

Policy Runtime version is... Good for
appVersion your version (1.2.0) simple apps; you must bump version whenever native code changes
fingerprint a hash of your native code and config safest: changes automatically when native things change
fixed string whatever you write ("1") full manual control

fingerprint removes the biggest human error: forgetting to bump the version after adding a native library, then shipping JavaScript that calls a module the old binary does not have, which crashes the app on launch. With fingerprint, eas update simply will not target old binaries.

Channels and branches

  • A branch is a stream of updates, like a git branch (main, fix-login).
  • A channel is a name baked into a build (production, preview). A channel points to one branch. You can repoint it without rebuilding.
Terminal
eas update --channel preview --message "Fix crash on empty list"
eas update --branch main --message "New onboarding copy"
eas channel:edit production --branch main     # point production at main

Typical flow: publish to preview, test with the preview build, then promote the same update to production (eas update:republish), so what you tested is exactly what ships.

Node.js Which update does a device receive? (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice u3 never reaches the 1.0.0 binary even though it is newer: runtime versions must match exactly.

When does the app update?

By default expo-updates checks for an update when the app launches, downloads it in the background, and applies it on the next launch. So a user may need to open the app twice to see a change. You have two levers:

JSX
// app.json: how long to wait for a fresh update at startup (milliseconds)
"updates": { "fallbackToCacheTimeout": 0 }   // never wait; use cache and download in the background

or check from code and decide the experience yourself:

JSX
import * as Updates from 'expo-updates';
import { useEffect } from 'react';

export function useUpdateOnLaunch() {
  const { isUpdateAvailable, isUpdatePending } = Updates.useUpdates();

  useEffect(() => {
    if (isUpdatePending) Updates.reloadAsync(); // the new bundle is downloaded: restart into it
  }, [isUpdatePending]);

  return isUpdateAvailable;
}

// or manually, e.g. from a "Check for updates" button:
async function checkNow() {
  const result = await Updates.checkForUpdateAsync();
  if (result.isAvailable) {
    await Updates.fetchUpdateAsync();
    await Updates.reloadAsync();
  }
}

Be considerate: restarting an app while the user is typing is rude. Prefer showing a small "Update ready, restart" banner, or reloading at a calm moment (app returns to foreground).

Rollbacks and safety

A bad update can break everyone at once, so plan for it:

  • Roll back: eas update:rollback republishes a previous update (or tells devices to go back to the embedded bundle).
  • Automatic safety net: expo-updates falls back to the previous working bundle if the new one crashes on launch (within its launch-time check), but do not rely on it.
  • Roll out gradually: eas update --rollout-percentage 10, watch crash reports, raise it later.
  • Test the preview channel with a real preview build first.
  • Keep updates small and reversible; no data migrations that old code cannot read.
Node.js Deterministic percentage rollout

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Store rules

Apple and Google allow OTA updates of JavaScript as long as the app's purpose does not change and you do not circumvent review (for example, turning a quiz app into a gambling app by update). Use OTA for fixes and improvements, not to sneak in features that need review.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What can an EAS Update change?

    Only the JavaScript bundle and assets are replaced. Native changes need a new build.
  2. 2. When is an update delivered to a device?

    Both the channel mapping and an exact runtime version match are required.
  3. 3. What is the main advantage of the fingerprint runtime policy?

    The runtime version is a hash of native inputs, so incompatible updates cannot reach old binaries.
  4. 4. By default, when does a downloaded update become visible?

    It downloads at launch and applies on the next one unless you reload from code.

Summary

  • EAS Update replaces only the JavaScript bundle and assets of an installed app.
  • The runtime version guards compatibility; prefer the fingerprint policy.
  • Builds have a channel, a channel points to a branch, and you can repoint it without rebuilding.
  • By default updates apply on the next launch; use expo-updates APIs for a custom experience.
  • Roll out gradually, test on preview first and know how to roll back.

Next: Testing Expo apps with Jest