This page is for developers with an Expo app on EAS Update. You will get a plan for your app, the safe edits applied with backups, and the order of the remaining steps.
This guide moves an Expo app that uses expo-updates (EAS Update) to Shipvo over-the-air updates. shipvo migrate --plan (packages/cli/src/migrate.ts) prints the plan for your app. It only reads; it changes no files. shipvo migrate --apply makes the safe edits for you (see below). You do the other steps by hand.
Facts about expo-updates are from the Expo EAS Update docs.
Why shipvo init stops
Two update systems in one build would fight over the bundle. shipvo init refuses an app with expo-updates and changes nothing. Remove expo-updates first, then run init.
See the plan
npx shipvo migrate --plan
npx shipvo migrate --plan --jsonOutput as printed (not edited), from a copy of apps/tide-and-tackle with expo-updates, an updates key and a runtimeVersion key added (the sample app itself has none, so on the unchanged app it prints "Nothing to migrate"):
Found expo-updates (EAS Update):
- package.json dependencies: expo-updates@~58.0.0
- app.json plugins: expo-updates
- app.json: updates: {"url":"https://u.expo.dev/x"}
- app.json: runtimeVersion: {"policy":"appVersion"}
Steps, in this order:
1. Commit your work. Installed apps keep using EAS Update until a new store build ships, so do not stop publishing to EAS yet.
2. Remove expo-updates from package.json (npm remove expo-updates).
3. Remove the expo-updates entry from plugins, and the updates and runtimeVersion keys, from the app config.
4. Remove calls to the expo-updates API (for example Updates.checkForUpdateAsync) from your code.
5. Run shipvo init. It adds @shipvo/runtime, the config plugin, a signing key, shipvo.json, the sim/publish/rollback scripts and a publish workflow. It never overwrites a file.
6. Back up the signing seed (shipvo keys export). If you lose it, installed apps will not accept another update.
7. Build and submit a new store build. Only this build uses Shipvo; older binaries keep using EAS Update.
8. Run shipvo publish --dry-run, then shipvo publish for the first Shipvo release once the new build is on devices.
No files were changed. Details: docs/migrate-from-eas-update.mdIt lists each entry it found:
expo-updatesindependenciesordevDependenciesofpackage.jsonexpo-updatesinpluginsofapp.json- the
updatesandruntimeVersionkeys (alsoios.runtimeVersionandandroid.runtimeVersion) inapp.json
With app.config.js or app.config.ts it cannot read the config. It tells you to check those entries by hand.
In an app with neither expo-updates nor CodePush it exits 0 and says there is nothing to migrate.
Apply the safe edits
npx shipvo migrate --apply
npx shipvo migrate --apply --json--apply removes exactly the entries --plan lists, and nothing else: the expo-updates dependency, the expo-updates plugin entry, and the updates and runtimeVersion keys in app.json. Before it writes, it copies each changed file to .shipvo/migrate-backup/.
- It refuses a dirty git tree. Commit or stash first, or pass
--force. - It does not edit
app.config.jsorapp.config.ts, your code, or the lockfile. Run your package manager's install afterwards. - It does not run
shipvo init. It prints that as the next step. - A second run exits 0 and says there is nothing left to do.
Order of steps
- Commit your work. Keep publishing to EAS Update for now. Binaries already on phones keep using EAS Update until a new store build ships.
- Remove
expo-updatesfrompackage.jsonwith your package manager. - Remove the
expo-updatesplugin entry and theupdatesandruntimeVersionkeys from the app config. - Remove calls to the
expo-updatesAPI from your code. - Run
shipvo init. It adds@shipvo/runtime, the config plugin, a signing key,shipvo.json, scripts and a publish workflow. It never overwrites a file. - Back up the signing seed with
shipvo keys export. If you lose it, installed apps will not accept another update. See new-machine.md. - Build and submit a new store build. Only this build uses Shipvo.
- Run
shipvo publish --dry-run, thenshipvo publish.
What maps to what
| EAS Update | Shipvo |
|---|---|
eas update | shipvo publish |
| Channels and branches | Cohorts (bands): --bands b0,b1,b2 |
eas update:rollback | shipvo rollback --to <release> |
runtimeVersion | shellMajor in shipvo.json. The shell also declares its Hermes bytecode version and native modules; shipvo publish checks a release against them |
| Code signing certificate | Ed25519 key made by shipvo init |
First publish and first applied OTA
After shipvo migrate --apply and shipvo init --yes on that copy, init printed all doctor checks as PASS and the next steps: rebuild the native app once (npx expo prebuild, then npx expo run:android), then npx shipvo publish --dry-run.
How the rest maps
- Percentage rollouts: use cohort bands (
--bands) to stage a release. - Release status:
shipvo status, and the control plane admin at/app/<id>/adminfor content, orders and the owner API (see getting-started.md). - Channels and branches: group devices with bands.
Troubleshooting
shipvo initrefuses to run:expo-updatesis still in the app. Runshipvo migrate --planand remove every entry it lists.migrate --applysays the git tree is not clean (dirty_tree): commit or stash your work and run it again.--forceapplies anyway. Backups are in.shipvo/migrate-backup/.- The plan says to check the config by hand: your app uses
app.config.jsorapp.config.ts, whichmigratedoes not read or edit. Remove theexpo-updatesplugin,updatesandruntimeVersionthere yourself. shipvo migrate needs --plan ... or --apply: no mode flag. Add--planor--apply, one at a time.- Lockfile still lists
expo-updates:--applydoes not touch the lockfile. Run your package manager's install. - Phones still get EAS updates: installed apps keep the old update system until a new store build ships. That is expected. Only the new build uses Shipvo.
Next steps
- Getting started: what
shipvo initandshipvo publishdo. - New machine and key backup: back up the signing seed now.
- Key rotation: change the signing key later without a store build.
- Migrate from CodePush and CLI guide.