This guide is for a developer who ships a React Native app with react-native-code-push and wants Shipvo over-the-air (OTA) updates instead. You will end with a signed release on a staged rollout and a one-command rollback. It takes seven steps. Every command and flag below comes from packages/cli (src/help.ts, src/init.ts, src/publish.ts). The dry-run output was captured by running the CLI on the sample app in this repo.
Run shipvo migrate --plan in your app first. It is read-only. It lists what it finds with file and line (the react-native-code-push dependency, codePush() and CodePush.sync calls, CodePushDeploymentKey and CodePushPublicKey in Info.plist and strings.xml, and appcenter codepush commands in package.json and CI files) and prints the steps in order. --json returns the same data.
shipvo migrate --apply makes the code edits for you (see shipvo migrate --apply): it swaps the codePush() wrapper and CodePush.sync calls for @shipvo/runtime calls, removes the native keys, and swaps the dependency in package.json. It does not run the package manager, does not edit appcenter codepush scripts or CI files (it prints them as manual steps), and refuses a dirty git tree unless you pass --force. Review the diff with git diff. It does not edit native bootstrap code. Files such as MainApplication.java, MainApplication.kt, AppDelegate.m, AppDelegate.mm, AppDelegate.swift, settings.gradle, app/build.gradle and the Podfile often still call CodePush (for example CodePush.getJSBundleFile() or [CodePush bundleURL]). Change those by hand, or the native build fails once the dependency is gone. --apply lists every such file with its line under the manual steps. You still create the Shipvo config (Step 1) and ship one new store build.
--rollout <n> has no direct equivalent. Shipvo uses cohort bands (--bands, then shipvo promote).
What maps to what
CodePush facts are from the react-native-code-push README and its docs folder.
| CodePush | Shipvo | Notes |
|---|---|---|
Deployment key (CodePushDeploymentKey in Info.plist or strings.xml) | appId and controlPlane in shipvo.json, passed to the @shipvo/runtime plugin in app.json | There is no per-environment secret key in the app. The shell trusts one control plane URL and one public key. |
appcenter codepush release-react | shipvo publish | Builds the bundle, signs it, publishes it. |
--rollout 25 | --bands b0,b1,b2 | Shipvo releases to cohorts (bands), not a free percentage. The default is all three, b0,b1,b2. |
appcenter codepush rollback | shipvo rollback --to <release> | Republishes an earlier release as a new release number. |
Code signing (CodePushPublicKey, --privateKeyPath) | Ed25519 key made by shipvo init, public key pinned in the shell | Signing is always on. The seed is in .shipvo/seed.txt or SHIPVO_SIGNING_SEED. |
| Client-side rollback after a crash | Crash-loop revert | After three failed boots the runtime goes back to the last good bundle. Measured in spike-results.md. |
Before you start
- Node 22.
- An Expo-based React Native app.
shipvo publishrunsnpx expo export, and the runtime ships as an Expo config plugin. - A control plane: the hosted one (
shipvo login, thenshipvo app create) or your own (self-hosting.md).
Step 1. Create a Shipvo config
shipvo init <dir> creates a new app. It refuses to write into a folder that exists, so it cannot change your app in place. Run it in a scratch folder and copy what you need:
npx -y @shipvo/cli init shipvo-scratch --app-id myshop --name "My Shop"From shipvo-scratch take:
shipvo.jsonto the root of your app.- The
@shipvo/runtimeentry from thepluginslist inapp.json. It holdsbaseUrl,publicKey,appIdandshellMajor. .shipvo/seed.txt, your signing seed. It is git-ignored. Back it up (shipvo keys export) and keep a copy offline. If you lose it, installed apps will not accept another update. See new-machine.md.
Other init flags: --control-plane URL, --public-key B64 (use an existing key, then no seed is made), --bundle-id.
Then install the runtime and CLI in your app:
npm install @shipvo/runtime @shipvo/device
npm install --save-dev @shipvo/cliStep 2. Swap the update code
In the same release, remove react-native-code-push and call the Shipvo runtime so no build has two update mechanisms. The sample code in the file App.tsx that init writes shows the calls: Runtime.markHealthy() once the first screen renders, and Runtime.checkForUpdate(true) to look for a release. Copy that pattern.
Remove the CodePush deployment key and public key from Info.plist and strings.xml. shipvo migrate --apply does steps like these for single-line calls.
Step 3. Check the setup
npx shipvo doctorEach line starts with PASS or FAIL. A FAIL line ends with the fix.
Step 4. Dry run
npx shipvo publish --dry-run --out .shipvo/dry-runThis builds and signs a release and writes files locally. It sends nothing. --out defaults to .shipvo/dry-run. A dry run builds no patches. Unknown flags are errors, so a typo like --dryrun cannot start a real publish.
Output from the sample app (apps/tide-and-tackle, with a throwaway key; the Metro progress lines are left out):
native modules this release requires: none found
dry run: nothing is sent anywhere; files go to /tmp/agent/dry. No patches are built offline. Release is 1 (pass --release N to match the control plane).
...
Exported: dist-ota
patches: none
...
Exported: dist-web
Dry run complete. Nothing was sent.
Release: 1
Size: 1.79 MB
Files: /tmp/agent/dry
Full bundles are fine for a first release. Small patches matter once you have older releases to compare against.The pointer files are under p/<appId>/<shell major>/<band>. Check one with shipvo verify <pointer> [public-key-b64].
Step 5. Ship the store build
Build and submit one new binary with the Shipvo plugin and your public key in it. Users on the old CodePush build keep running their last CodePush bundle. They get Shipvo updates only after they install this binary. Shipvo updates reach every build that contains the Shipvo runtime.
Step 6. Publish
npx shipvo publish --bands b0Watch crash rates, then widen the same release:
npx shipvo promotepromote copies the release on b0 to b1 and b2 with a new signature. It does not rebuild, so the release you watched is the one everyone gets. It refuses a halted release or one with reported reverts unless you pass --force. Use --to b1 to widen one band at a time, --platform android|ios|all, and --dry-run to preview. Running shipvo publish again would build a new release number instead.
Useful flags: --platform android|ios|all (default android), --release N, --min-shell X.Y.Z, --max-bases N. Run shipvo publish --help for the full list.
For speed numbers, see spike-results.md. Those were measured on one phone and apply only to that setup.
Step 7. Roll back
npx shipvo rollback --to 3 --dry-run # preview
npx shipvo rollback --to 3This signs the code of release 3 as the next release number and publishes it to the bands you name (default all). It needs the control plane, so the preview reads from it too. --bands and --platform work as in publish. If your app saves data on the phone and a newer release changed its layout, set stateVersion first: see Rollbacks and stored data.
How Shipvo differs from CodePush
- Your signing seed stays with you. Every release is signed, and installed apps check the signature.
- Rollout goes by cohort (
b0,b1,b2). You choose which cohorts get a release with--bands. - Binary compatibility is set with
--min-shelland the native module check inpublish. - Apps receive updates through
@shipvo/runtime, which Step 2 adds. publishcallsexpo exportto build the bundle, so the project is an Expo project.- You start with release 1 on Shipvo. Your CodePush history stays in App Center.
Troubleshooting
Git tree is not clean (N changed path(s)). Commit or stash first, or pass --force.shipvo migrate --applywill not edit a dirty tree. Commit or stash, then run it again. With--force, backups of each edited file go in a backup folder, so you can undo.<dir> already existsfromshipvo init.initnever writes into an existing folder. Run it in a new scratch folder as in Step 1 and copy the files across.- The native build fails after
--apply. A native file still calls CodePush, for exampleCodePush.getJSBundleFile()or[CodePush bundleURL].--applylists each file and line under its manual steps. Change them by hand. shipvo doctorprints a FAIL line. The line ends with the fix. Make that change and rundoctoragain until every line says PASS.shipvo publishfails on a project that is not Expo.publishrunsnpx expo export, so the project needs Expo installed.- Users on the old build get no Shipvo update. They need the new store binary from Step 5. Ship the Step 5 store build first; every build with the runtime then updates over the air.
- Installed apps refuse updates after you changed machines. The signing seed is missing or different. Restore it with
shipvo keys import(new-machine.md).
Next steps
- Build your first app
- Ship a fix, widen it and roll it back
- The CLI guide for every
publish,promoteandrollbackoption - Back up your signing seed
- Rollbacks and stored data
- Self-hosting the control plane
- Glossary