Migrate from EAS Update

An Expo app leaves EAS Update by replacing expo-updates with @hotcodepush/expo-ota-updates at its next store release. The store build that carries the new SDK is the switch, and the binaries before it keep taking EAS updates until their users move. What differs, side by side, is on the site's EAS Update alternative page.

HotCodePush serves no EAS-compatible endpoint, so expo-updates cannot be pointed at it. The minimum versions are on Supported versions. An app on a newer Expo SDK than the SDK supports waits until that page lists it.

A bare React Native app on expo-updates starts at the React Native SDK's Installation page instead.

AI-assisted migration (recommended)Copy Anchor Link

Install the HotCodePush skills:

npx skills add hotcodepush-team/skills

Then paste the prompt into your coding agent:

Migrate this app from EAS Update to HotCodePush: install the skills with `npx skills add hotcodepush-team/skills`, then run the hotcodepush-migrate skill, following https://hotcodepush.com/docs/migrate/eas-update.

The agent removes expo-updates, runs init, maps channels, the signing key, config keys and SDK calls, and reports a checklist for the store release. It never touches EAS Update, and the first release waits for the store build. Agent skills explains what the agent does.

PrerequisitesCopy Anchor Link

• You have a HotCodePush account and an organization. npx hotcodepush init creates both, as the quickstart shows.
• The app is an Expo app that runs in a development build or a release build, never Expo Go.
• You have the private key file your EAS updates were signed with, if code signing was on. Sign your bundles explains what the key does here.
• A store release lies ahead, and Node.js is on every build machine, since the build step runs the CLI from an Xcode phase and a Gradle task.

StepsCopy Anchor Link

If you already removed expo-updates and ran init, skip to step 4.

1. Freeze a branch for the old buildsCopy Anchor Link

git branch eas-update-fleet

A bundle built from the migrated code imports a native module the old binaries lack. Hotfixes for them come from a branch that keeps the old client.

2. Remove expo-updatesCopy Anchor Link

npm uninstall expo-updates

Remove the updates block and runtimeVersion from the app config, and every expo-updates import per the SDK calls below. Keep extra.eas.projectId while EAS Build makes your binaries. Remove channel from each build profile in eas.json, since step 5 replaces it.

The prebuild refuses a project that lists expo-updates unless updates.enabled is false.

3. Run initCopy Anchor Link

npx hotcodepush init

init signs you in, picks or creates the organization and the app with its production channel, installs @hotcodepush/expo-ota-updates and writes hotcodepush.json. It adds the package to plugins in app.json or app.config.json. A project whose app config is code adds the entry itself.

It asks whether to generate a signing key: answer no if you bring the EAS key, which step 4 adds. Decline the first release too. Pin the CLI with npm install --save-dev hotcodepush: every native build runs it.

The config plugin wires the build step at npx expo prebuild. hotcodepush.json takes over from updates.url, runtimeVersion and the expo-channel-name header: appId and channel are the whole file. The Expo SDK's Configuration page lists every other key.

4. Add your signing keyCopy Anchor Link

Skip this step if your EAS updates were not signed. EAS code signing generated an RSA key pair of 2,048 bits in PEM files, which signing-key add takes as it is:

npx hotcodepush signing-key add --private-key-path ../keys/private-key.pem

It registers the public key with the app and appends it to publicKeys in hotcodepush.json. The build step writes the list into the binary, which is what updates.codeSigningCertificate did. The private key stays where it is: every upload names it with --private-key-path, or CI sets the file's content as HOTCODEPUSH_SIGNING_KEY.

5. Create the channels your EAS channels hadCopy Anchor Link

production exists. Each further EAS channel becomes one here:

npx hotcodepush channel create --name staging --discoverable

--discoverable lets the app switch to the channel by name with setChannel({ name }), as Channels describes. Without it the channel is reachable by its id alone.

A build profile that followed staging sets HOTCODEPUSH_CHANNEL under env in eas.json, as Set up environments and tenants shows.

6. Prebuild and ship the store releaseCopy Anchor Link

npx expo prebuild --clean

Then build the release as before. The build step runs binary create inside the build and registers it, so the machine, EAS Build included, needs HOTCODEPUSH_TOKEN in the build's environment or npx hotcodepush login. Under CI a store build without a token fails, and npx hotcodepush binary list shows the registered builds.

A development build takes no updates: verify in a release build, then run npx hotcodepush doctor.

7. Release from your pipelineCopy Anchor Link

npx hotcodepush release create --bundle-version "$(git rev-parse --short HEAD)" --yes

With HOTCODEPUSH_TOKEN and, for a signing app, HOTCODEPUSH_SIGNING_KEY in the environment, this is the whole pipeline step. The upload runs expo export:embed per platform where it runs, so the EXPO_PUBLIC_* values an EAS environment gave eas update must be in the job's environment. Ship every commit is the pipeline this line sits in.

Open the app on a device that runs the new store build: the release applies within about a minute (How an update reaches a device). If nothing happens, see Troubleshooting.

8. Run both until the fleet movesCopy Anchor Link

A binary carries one client: an EAS update never reaches a HotCodePush build, nor the reverse. Hotfixes for the old builds come from the branch of step 1 with eas update, and their runtime version must match exactly. The Binaries page and binary list show each new build's devices.

CLI commandsCopy Anchor Link

A release is numbered per channel and, on Expo, exists per platform: one release create makes two, one per expo export:embed output. The CLI reference lists every command, release and its flags on the release page.

SDK callsCopy Anchor Link

The Expo SDK's API page has every method, event and type. Choose an apply strategy compares the strategies fallbackToCacheTimeout maps to.

Before and afterCopy Anchor Link

The updates block and runtimeVersion leave the app config, and the plugin entry arrives:

{
  "expo": {
    "runtimeVersion": { "policy": "appVersion" }, 
    "updates": { 
      "url": "https://u.expo.dev/<projectId>", 
      "checkAutomatically": "ON_LOAD", 
      "fallbackToCacheTimeout": 0
    }, 
    "plugins": ["@hotcodepush/expo-ota-updates"], 
    "extra": { "eas": { "projectId": "<projectId>" } }
  }
}

hotcodepush.json takes the address and the channel:

{
  "appId": "<your app id>",
  "channel": "production"
}

production needs nothing in eas.json, as hotcodepush.json names it. Another profile sets its channel through the environment instead of the channel key:

{
  "build": {
    "staging": {
      "channel": "staging"
      "env": { "HOTCODEPUSH_CHANNEL": "staging" } 
    }
  }
}

What differsCopy Anchor Link

• Addresses: updates.url and projectId become appId, which is public, and a channel is addressed by name in the build and by an unguessable id at runtime.
• The fingerprint replaces the runtime version: it rides on every release, so a release never lands on a build whose native code differs. Nothing is bumped, and a --binary-version range over the store version narrows it. See Compatibility.
• A rollout belongs to a release, not a branch: nothing blocks the next publish, and a newer release supersedes the rollout inside its bucket. A device keeps the release it has, and auto-pause halts one whose failure rate climbs. See Roll out gradually.
• Rollback is a release: release rollback --to-release <number> publishes an earlier bundle as a new release, mandatory by default, once per platform's number. A full revoke, release revoke --all, returns the channel's devices to the embedded bundle across every native layer.
• The readiness gate has no off switch: a release that has not rendered within readyTimeoutSeconds, 10 by default, is rolled back and never tried there again. The report feeds auto-pause.
• Mandatory updates exist: release create --mandatory applies at once under mandatoryApplyStrategy: immediate.
• Code signing is on every plan.

Next stepsCopy Anchor Link

• Ship every commit has the pipeline that releases every merge with the one CLI line, named by its commit.
• Test with preview channels gives every pull request an expiring channel and a QR code for testers, replacing the development build's preview.
• Roll out gradually: start a release at a small percentage, let it progress and let auto-pause stop a bad one.
• Expo SDK reference documents every hotcodepush.json key, method, event, type and reason of the SDK you installed.