How Turbopush Works

What are OTA Updates?

Over-The-Air (OTA) updates let you push new code directly to users' devices without going through the App Store or Google Play review process. Instead of submitting a new binary and waiting days for approval, you deploy changes and users receive them automatically—often within minutes.

React Native apps are uniquely suited for OTA updates because they consist of two distinct layers:

• Native shell — compiled code (Swift, Kotlin, Objective-C, Java) that runs on the device
• JavaScript bundle — your React components, business logic, and UI code

The JavaScript bundle is loaded at runtime by the native shell. Turbopush replaces this bundle on-device with a newer version without touching the native layer.

What Can and Cannot Be Updated OTA

How an Update Reaches a Device

1. Release — You run turbopush release-react or turbopush release-expo. The CLI bundles your JS code and uploads it to Turbopush servers.
2. Check — When the app launches (or resumes, depending on your config), the Turbopush SDK checks the API for a newer release compatible with the app's current binary version.
3. Download — If an update is available and the device is eligible (based on rollout percentage), it downloads silently in the background.
4. Install — The update is applied according to the configured installMode: immediately, on next restart, or on next resume.
5. Rollback — If the new bundle crashes on startup, the SDK automatically reverts to the previous working version.

Key Concepts

Apps and Deployments

An app in Turbopush represents a single platform build of your React Native project. Because iOS and Android bundles have different contents, you create one app per platform:

MyApp-iOS     ← iOS deployments
MyApp-Android ← Android deployments

Each app has deployments — named release channels. Every app starts with Staging and Production. You can create additional deployments (e.g. Beta) for more granular control.

Releases and Labels

A release is a versioned JavaScript bundle uploaded to a deployment. Releases are immutable — you cannot edit their code after publishing. Each release gets an auto-incremented label (v1, v2, v3, ...).

Each release has two version constraints:

• Target binary version — The native app version(s) this release is compatible with. Supports semver ranges (e.g. >=1.2.0 <2.0.0).
• Deployment — Which channel (Staging, Production, etc.) the release belongs to.

Mandatory vs Optional Updates

• Optional (default) — Users download the update silently and it applies on next restart.
• Mandatory — The update is installed and the app restarts immediately, regardless of installMode. Use this for critical bug fixes.

Rollout Percentage

Instead of releasing to 100% of users at once, you can target a percentage:

turbopush release-react myapp-ios ios --rollout 10

This sends the update to a random 10% of eligible devices. Once you're confident the release is stable, increase the percentage with turbopush patch.

Promoting Releases

The recommended workflow is to release to Staging, test, then promote to Production. Promotion copies the exact same bundle — no repackaging, no risk of differences between environments:

turbopush promote myapp-ios Staging Production

Rollback

If a release causes issues, rollback creates a new release using the code from the previous version:

turbopush rollback myapp-ios Production

Users on the broken version receive the rollback update automatically. The release history is preserved — rollback adds a new entry rather than deleting anything.

Install Modes

Control when an update is applied using installMode in your SDK configuration:

Automatic Rollback Safety

If a downloaded update causes the app to crash on startup, the Turbopush SDK detects this and automatically reverts to the previous bundle. The server records the rollback as a metric, visible in turbopush deployment ls and in the Turbopush dashboard.