DEV Community: George Fean

Runtime Versions: The Compatibility Boundary for React Native OTA Updates

George Fean — Wed, 19 Aug 2026 23:50:20 +0000

A React Native application is not one artifact.

The binary users install from the App Store or Play Store contains native code, native dependencies, platform configuration, a JavaScript engine, and an embedded JavaScript bundle.

An OTA release replaces only part of that system: the JavaScript bundle and compatible bundled assets.

That creates the most important safety question in any React Native OTA system:

Can this new JavaScript safely execute inside the native binary already installed on the device?

A runtime version exists to answer that question.

In Bundle Drop, runtimeVersion names the native compatibility boundary. An OTA bundle is only eligible when its platform and runtime version match the installed binary. It is not a “newer than” comparison and it is not simply another app version.

App version and runtime version solve different problems

It is tempting to reuse the application version for everything.

For example:

App version: 4.2.0
Runtime version: 4.2.0

That may be convenient for a particular release strategy, but the two concepts are different.

The application version answers something like:

Which product release is this?

The runtime version answers:

Which native interface can this JavaScript safely run against?

Multiple JavaScript releases can therefore exist inside the same native runtime.

And two native app releases can sometimes share a runtime if their native compatibility surface is unchanged.

Bundle Drop records both kinds of identity separately; its CI result metadata, for example, includes the application version and runtimeVersion as distinct fields.

That separation matters because otherwise the OTA compatibility model becomes coupled to product-versioning decisions that may have nothing to do with native safety.

Keep the runtime when the native boundary did not change

Suppose your current configuration looks like this:

module.exports = {
  runtimeVersion: {
    ios: "4.2-native-1",
    android: "4.2-native-1",
  },
};

You fix some TypeScript logic.

Or change copy.

Or adjust styling.

Or add a screen built entirely from native capabilities that already exist in the installed binary.

Those changes do not necessarily create a new compatibility boundary.

The existing binaries already contain what the new JavaScript needs.

So the runtime can remain unchanged.

Bundle Drop’s current public model explicitly recommends keeping a platform’s runtime literal stable for OTA-compatible JavaScript and asset changes.

Bump the runtime when JavaScript can depend on new native state

Now imagine adding a new iOS native module.

The next JavaScript release imports that module.

Older iOS binaries cannot safely run the new bundle because the native module simply does not exist inside them.

Changing the OTA runtime label does not magically install the module.

The correct sequence is:

change the native code;
create a new iOS runtime line;
build and distribute a new iOS binary;
publish OTA updates that depend on the new native capability only to that runtime.

The old binary continues on its previous compatibility line.

This same logic applies to changes such as native dependencies, permissions, generated native configuration, JavaScript-engine changes, architecture changes, or Expo config-plugin output that materially changes the native projects.

A runtime version is a gate, not an upgrade mechanism.

iOS and Android do not have to move together

This is one of the most useful properties of a per-platform runtime model.

Suppose you add a native dependency only on iOS.

You might change:

runtimeVersion: {
  ios: "4.2-native-1",
  android: "4.2-native-1",
}

to:

runtimeVersion: {
  ios: "4.2-native-2",
  android: "4.2-native-1",
}

Android has not gained or lost any native capability.

There is no compatibility reason to force it onto a new runtime line.

Bundle Drop’s canonical runtime article explicitly models these as independent lanes: an iOS native change can advance iOS while Android continues resolving the previous Android runtime.

This is more than a configuration detail.

React Native teams frequently ship platform-specific native changes.

Forcing both platforms to advance every time one platform changes creates unnecessary runtime fragmentation and release bookkeeping.

Old and new binaries normally coexist

Publishing a new store binary does not mean every user installs it immediately.

Some users update quickly.

Some wait days or weeks.

Managed devices can lag even longer.

During that period, production can legitimately contain:

Older iOS binary
runtimeVersion = ios:4.2-native-1

Newer iOS binary
runtimeVersion = ios:4.2-native-2

Both binaries may continue checking the same production channel.

The important part is that each installation resolves only updates that belong to its own runtime line.

Bundle Drop’s public resource explicitly describes channels containing several runtime lines while installed binaries receive only the exact compatible platform/runtime combination.

This lets teams continue maintaining a safe OTA path for users who have not yet adopted the newest store release.

Runtime version and channel are different axes

Another common mistake is treating channels as compatibility boundaries.

They are not.

A channel answers:

Which release track should this app follow?

Examples might be:

develop
beta
production

The runtime answers:

Which native binaries can execute this update?

A production channel can therefore contain releases for multiple runtime lines.

Likewise, two binaries on the same runtime could follow different channels.

Bundle Drop documents these concepts separately because collapsing them creates awkward release models such as:

production-ios-v4-native2

where release track, platform and compatibility are all encoded into one string.

Keeping the axes independent produces a cleaner model:

Channel: production
Platform: ios
Runtime: 4.2-native-2

Each value answers one question.

A runtime bump should follow a native change, not compensate for uncertainty

It can be tempting to bump the runtime frequently “just to be safe.”

That is safe in one narrow sense: fewer binaries will be considered compatible.

But unnecessary runtime churn creates operational cost.

Every new runtime line creates another compatibility branch that may coexist in production.

Too coarse a boundary risks sending JavaScript to an incompatible binary.

Too fine a boundary creates unnecessary fragmentation.

The useful rule is:

Change the runtime when the native compatibility surface changed.

Do not use it merely as a release counter.

Expo introduces an authority question

Expo projects have another concept called runtimeVersion.

That means an OTA integration needs to be explicit about which value is authoritative rather than silently mixing two independent runtime calculations.

Bundle Drop’s default Expo setup uses the literal per-platform runtime values from bundle.drop.config.js, with those values embedded into the native build and used by uploads.

For advanced Expo workflows, the current public SDK also supports opting into Expo runtime authority. In that mode, Bundle Drop requires the runtime identity from the corresponding native build rather than guessing it during OTA publication; CI documentation describes using a matching local or EAS build receipt for that path.

The broader principle is useful even outside Bundle Drop:

one component should be authoritative for native compatibility.

If the build system and OTA publisher derive that boundary differently, you have created exactly the ambiguity the runtime version was meant to remove.

Runtime compatibility should be decided at release time

You do not want to discover a compatibility mistake because a production device crashed.

A useful release review asks:

Did native code change?
Did a native dependency change?
Did permissions or generated native configuration change?
Did the JavaScript engine or architecture change?
Did an Expo config-plugin change alter native output?
Did either platform change independently?

If the answer is yes, review that platform’s runtime before publishing the JavaScript release.

Bundle Drop’s setup and troubleshooting docs also surface runtime mismatches as a first-class delivery condition: an installation does not receive a bundle from a different runtime line.

That fail-closed behavior is important.

“No update available” is much safer than “run JavaScript against a native interface it was never built for.”

Runtime version is not enough by itself

Compatibility only answers whether a bundle can run.

It does not answer:

whether this is the correct release channel;
whether the installation belongs in a targeting cohort;
whether the staged-rollout percentage includes it;
whether the bundle passed integrity verification;
whether a previously installed update is healthy.

Those concerns need their own controls.

This is why production OTA systems usually have several independent dimensions:

Platform
Runtime compatibility
Channel
Targeting
Rollout state
Release identity
Health / recovery state

Runtime version is one of them, but it is arguably the first one.

If the native compatibility decision is wrong, the rest of the release controls cannot make the JavaScript safe.

A useful mental model

Think of a runtime version as a native contract identifier.

The installed binary says:

I provide native contract ios:4.2-native-1.

An OTA bundle says:

I require native contract ios:4.2-native-1.

If the contracts match, the release can continue through the rest of the eligibility process.

If they do not, the OTA bundle is not a candidate for that binary.

That model remains understandable whether the app has one store version or five active versions, whether iOS and Android move together or separately, and whether the release arrives through a development, beta, or production channel.

That is exactly what a good compatibility boundary should do.

The release rule to keep

OTA lets React Native teams move compatible JavaScript and assets independently from store binaries.

That independence only remains safe when the OTA system respects the native application underneath it.

Keep the runtime when the installed binaries already provide everything the update needs.

Create a new runtime line when the native interface changes.

Move only the platforms that actually changed.

And allow old and new runtime lines to coexist while users adopt the new store binary at their own pace.

Bundle Drop implements that model with literal per-platform runtime versions by default, plus an explicit Expo-authority option for teams that need it. The principle itself is provider-independent:

OTA compatibility should be explicit, stable and easy to explain during an incident.

Originally published on Bundle Drop Resources

Patch Delivery and Full-Bundle Reliability in React Native OTA

George Fean — Wed, 12 Aug 2026 08:21:05 +0000

Most OTA releases do not replace most of an application.

A production update might fix one conditional, adjust a request handler, or change a small group of bundled assets.

Yet with a full-bundle-only delivery model, every eligible device still downloads the complete JavaScript and asset payload.

That model is easy to reason about. It is also often wasteful.

Patch delivery solves that efficiency problem by transferring a representation of what changed instead of sending the entire release again.

But patches introduce another question:

What happens when the device cannot safely use the patch?

That is where OTA delivery becomes more interesting than simply calculating the smallest possible download.

A production system needs to optimize network transfer without making that optimization a requirement for reaching a valid release. That is the principle behind Bundle Drop’s hybrid approach: a patch can be the smaller route to a release, while the complete verified bundle remains available as the dependable route. (Bundle Drop)

Why patch delivery is useful

Imagine a large React Native application where a release changes only a few lines of JavaScript.

The generated production bundle still contains the rest of the application module graph, dependencies, framework code, and other unchanged content.

If the update system always sends complete bundles, the amount of data transferred is tied more closely to the size of the application than to the size of the change.

That matters because mobile networks are not uniform.

Users can be on metered connections, high-latency networks, unstable Wi-Fi, or background execution windows that disappear before a large download completes.

A smaller transfer generally spends less time exposed to those conditions and consumes less user bandwidth. (Bundle Drop)

The advantage compounds when a team ships frequently.

A sequence of small fixes does not need to mean repeatedly transferring the majority of the same JavaScript bundle to every device.

When a client has the correct starting state, a patch can make the transfer cost look much more like the release itself.

The patch has a dependency that a full bundle does not

A complete release bundle is self-contained from the client’s perspective.

If the platform and runtime compatibility rules match, the device can validate the artifact without reconstructing it from a previously installed OTA state.

A patch is different.

It describes a transition from an expected source state to a target state.

That means the source matters.

This sounds simple until you think about a real production fleet.

Some users skipped an earlier update.

Some installed the application recently and only have the bundle embedded in the App Store or Play Store binary.

Some were offline during a rollout.

Some received an earlier release and then recovered from it.

Others may have been in different rollout or targeting cohorts.

Production devices rarely form one perfect linear chain of versions. (Bundle Drop)

If a patch only works from version B to version C, a device currently running version A needs another route.

That should not automatically become an application error.

It can simply mean the optimized route is not appropriate for that device.

Treat patching as an optimization, not a release prerequisite

There are two obvious extremes.

The first is to always send complete bundles.

That gives every eligible device a self-contained artifact and keeps the delivery model simple.

The downside is repeated over-transfer.

The second extreme is to make patches mandatory.

That minimizes transfer size when the expected source state exists, but every patch prerequisite becomes part of deployment correctness.

Now you have to think about missing source versions, multiple patch paths, reconstruction failures, and devices whose local state does not match the expected chain.

A better model is to separate the destination from the transport.

The release is the complete verified result.

The patch is one possible way of getting there.

If the patch can safely produce that result, use it.

If it cannot, fetch the complete release instead. (Bundle Drop)

That gives the system an important invariant:

Every successful delivery path converges on the same verified release.

Release selection and transport are separate problems

Another useful distinction is between deciding which release a device should receive and deciding how that release should be transferred.

A device might first be evaluated against:

channel, platform, runtime compatibility, rollout percentage, targeting rules, and release state.

Only after the system selects an eligible release does patch availability matter.

Two devices can therefore be eligible for the same release but receive it differently.

One may already have a suitable source bundle and use an optimized patch.

Another may need the complete bundle.

Both should converge on the same target release.

Bundle Drop’s current upload documentation reflects that separation: uploads become versioned OTA bundles, patch optimization is prepared afterward, and eligible installations can use the full bundle while patch work is still being prepared. If patching is not efficient, the system deliberately uses the full bundle instead. (Bundle Drop)

Verification matters more than transfer size

A patch being small does not make it safe.

A successful HTTP response does not make it safe either.

The useful boundary is whether the intended complete target exists locally and has passed the validation required before staging.

A patch can download correctly and still fail to reconstruct the expected result.

A transfer can be interrupted.

Local data can be incomplete.

The device can run out of storage.

The application can be terminated midway through work.

Those are ordinary failure modes in mobile software.

The system should have a binary outcome:

the complete intended release is present and verified, or the current working bundle remains active.

There should not be a halfway state where partially reconstructed content becomes executable. (Bundle Drop)

This is also why transport logic should ideally stay below the application-facing API.

Product code should be able to ask for an update and receive a staged release without branching into separate business logic for “patch mode” and “full bundle mode.”

The transport is an implementation decision.

The release state is the application concern.

Full-bundle fallback does not mean ignoring errors

Fallback is not magic recovery.

If the device has no usable connection, lacks storage, or cannot validate the complete artifact either, the update still cannot be staged.

The correct behavior is to keep running the existing verified bundle and try again later according to the application’s update policy.

The purpose of the full bundle is narrower:

a device should not be stranded just because the optimized patch route is unavailable.

That distinction matters.

Transport fallback handles a delivery-path problem.

It does not fix a bad release.

If the target JavaScript itself is faulty, that becomes a rollback or recovery problem instead. The canonical Bundle Drop resource explicitly treats transport reliability and release correctness as separate concerns. (Bundle Drop)

Progressive rollouts make mixed device states normal

Percentage rollouts intentionally create different device states.

During a staged rollout, some installations have the candidate release while others still run the previous one.

Targeted release rules can create additional valid branches.

Server-side rollbacks can change future release selection.

Device-side recovery can move an installation back to an earlier verified bundle.

In other words, the fleet becomes heterogeneous by design.

That makes a delivery model that assumes every device is always exactly one release behind increasingly fragile.

Patch optimization can still work well in that environment, but only when it is allowed to be conditional.

Devices that have the expected starting state use the smaller route.

Devices with different histories use the complete bundle.

The rollout system can then focus on release health instead of maintaining one perfectly uniform transport chain. (Bundle Drop)

Why this matters operationally

It is tempting to evaluate an OTA system by the smallest patch it can produce.

That is not a very useful production metric on its own.

A better set of questions is:

Can every compatible and eligible installation reach the release?

What happens when the optimized path cannot be used?

Does the current working bundle remain active after a failed delivery?

Do patch and full-bundle paths converge on the same staged result?

Are old and unusual device histories tested before broad rollout?

Those questions are less exciting than “our update was only 30 KB,” but they are much closer to the real job of release engineering. The source article makes the same point: predictable reachability and safe activation matter more than a perfect efficiency ratio. (Bundle Drop)

Optimize both, force neither

Patch delivery and full-bundle delivery are sometimes treated like opposing architectures.

They do not have to be.

A smaller transfer is useful because most releases change only part of an application.

A complete release artifact is useful because production devices do not share one clean history.

The two solve different problems.

Patches optimize transport.

Full bundles preserve an independent route to the release.

Verification decides whether the result can be staged.

That is the model Bundle Drop currently uses for React Native and Expo OTA delivery: the public SDK describes hybrid transport as maintaining full-bundle integrity while supported devices download patch-sized changes. (GitHub)

The important idea is broader than any one platform:

Bandwidth optimization should not become a new condition for deployment correctness.

The original technical resource for this article is:

https://bundledrop.app/resources/patch-delivery-full-bundle-reliability

Life After CodePush: Choosing an OTA Update Strategy for React Native in 2026

George Fean — Tue, 04 Aug 2026 22:55:03 +0000

Microsoft retired the hosted Visual Studio App Center service on March 31, 2025. That included the managed service many React Native teams knew through CodePush, although Microsoft also released a self-hostable CodePush server.

The service retirement did not remove the underlying need. Teams still want to fix JavaScript bugs, adjust UI, update copy, and ship compatible asset changes without waiting for a new App Store or Play Store release.

But choosing a replacement is not just a matter of finding a familiar sync() call. An OTA system becomes part of your production runtime and your release process. The important questions are about compatibility, failure handling, rollout control, and how much of the system your team wants to operate.

What an OTA system actually has to manage

An OTA update is not simply a file download. It is a decision about which code a particular installed binary can safely execute.

Native and runtime compatibility

React Native lets you change JavaScript without rebuilding the native application, but only while that JavaScript remains compatible with the native code already on the device.

Adding a native module, changing permissions, upgrading React Native, switching important native configuration, or changing a JavaScript engine can require a new binary. A production OTA system therefore needs a compatibility boundary—often called a runtime version—and must refuse to deliver an update across that boundary.

This is one of the easiest details to overlook in a proof of concept and one of the most important details in production.

Channels and release tracks

Most teams need more than one stream of updates. You may want production, beta, QA, internal, or customer-specific tracks.

A channel is useful only if its relationship to builds and updates is explicit. Teams should know which installed binaries read from which channel, how an update moves between channels, and whether promoting a tested release preserves its identity.

Safe rollout strategies

Sending an update to every eligible device at once is fast, but it gives you very little time to react.

Percentage-based rollouts let you expose a release gradually. Targeted rollouts go further by limiting eligibility using properties such as plan, region, or an internal beta flag. These controls solve different problems: targeting defines who is eligible, while staging controls how much of that group receives the update.

Rollback and recovery

A dashboard rollback is helpful, but device-side recovery matters too. Consider what happens when an update crashes before the app can check the server again.

A robust design should define:

when an update is considered healthy;
how repeated launch failures are detected;
whether the device can return to a last-known-good bundle;
whether the embedded bundle remains a final fallback; and
how a failed update is prevented from being retried on the same device.

The worst time to discover that rollback depends on a successful JavaScript launch is after shipping JavaScript that cannot launch.

Integrity verification

The client should verify that the downloaded artifact is exactly the artifact the service intended to deliver. That normally means secure transport plus cryptographic hashes or signatures, validation before activation, and an atomic transition so a partial install never becomes the active version.

Integrity and compatibility are separate checks. A perfectly downloaded bundle can still be wrong for a device if it targets a different native runtime.

Download size and bandwidth

Some systems deliver a complete JavaScript bundle and asset set for every update. Others support patches or asset-level deltas.

Patch delivery can reduce download size when a change is small, but it introduces another failure path. Ask whether the client reconstructs and verifies the complete target state and whether it can fall back to a full update when a patch is missing, unsupported, or invalid.

Operational visibility

At minimum, teams need to identify which release is running when an error occurs. Useful signals include bundle identifiers or hashes, adoption, download and install failures, rollout state, and source maps tied to the exact update.

OTA tooling should complement your crash reporter, not hide update identity from it.

The main approaches available

There is no universal winner. The right choice depends on your application model, operational appetite, existing tooling, and risk tolerance.

Expo Updates and EAS Update

The names are easy to blur together, so it helps to separate them:

expo-updates is the client library that loads compatible updates.
EAS Update is Expo's hosted cloud service for publishing and serving those updates.
EAS Build is a separate service that produces app binaries.

EAS Update supports Expo projects using Continuous Native Generation and existing React Native projects that install expo-updates. It uses runtime versions for native compatibility, supports staged rollouts, provides deployment insights, and lets teams republish a previous stable update.

For teams already standardized on Expo tooling, that integration can be a strong advantage. Evaluate the workflow conventions, update behavior, and pricing model against your needs rather than treating "uses React Native" as the only requirement.

Other managed OTA providers

A managed provider can reduce the amount of infrastructure your team owns. The tradeoff is that you are adopting the provider's runtime model, release controls, pricing dimensions, and migration path.

Compare providers on concrete behavior rather than broad feature labels. "Rollback," for example, might mean republishing an older release, switching a server-side pointer, or performing automatic recovery on the device. Those are not operationally identical.

Self-hosted or custom infrastructure

Microsoft's App Center retirement guidance points CodePush users to a self-hostable server. Expo also documents self-hosting for the updates protocol. A custom system can offer maximum control over data, cost, and release policy.

That control comes with ownership. Your team becomes responsible for artifact storage, signing, availability, client compatibility, rollout state, observability, abuse prevention, and incident response. Running an update server is not the same as safely operating an OTA lifecycle.

Self-hosting is a reasonable choice when the constraints justify it and the team is prepared to maintain it.

Store-only releases

Choosing not to use OTA is also valid.

Store-only releases keep the delivery model simple and ensure every code change passes through the normal binary pipeline. The cost is slower delivery for small fixes and less control over when users install them.

For apps with infrequent releases, strict review requirements, or a small operational team, that tradeoff may be appropriate.

Questions to ask before choosing

A useful evaluation should be specific enough that two engineers can reach the same answer from the documentation or a test.

Does it support our actual project shape: Expo, Expo Prebuild/CNG, EAS Build, or bare React Native?
How is native compatibility represented, and who is responsible for changing the runtime version?
Does every update download a full bundle, or can the client fetch a smaller patch when only part of the application changes?
If patching fails, is there a verified full-bundle fallback?
Are percentage rollouts available? Can targeting rules use application-defined user properties?
What happens if an update repeatedly crashes before startup completes?
Can the device recover without successfully running the new JavaScript?
Are channels, promotions, and rollback operations auditable?
Can source maps and release identifiers be connected to the existing error tracker?
Is pricing tied to monthly active users, bandwidth, storage, builds, seats, or some combination?
Can artifacts and release history be exported if the team later migrates away?
Which changes still require a store build?

A small failure drill is often more revealing than another feature checklist: publish a deliberately broken update to a test channel, then observe how rollout, detection, rollback, and device recovery actually behave.

Why I built Bundle Drop

Disclosure: I am the creator of Bundle Drop.

I built Bundle Drop because I wanted another managed option with an explicit compatibility boundary and a recovery model that remains useful when an update fails early.

Its delivery model prepares a complete verified bundle and, when possible, a smaller patch. A device can download the patch when only part of the application changed instead of downloading the full update every time. The client reconstructs and verifies the complete target state before activation. If patch transport is unavailable or fails, it falls back to the signed full bundle.

Bundle Drop also provides channels, staged rollouts, and targeting based on application-defined user properties. On-device health checks can return a failing update to the previous verified bundle, or to the binary's embedded bundle when there is no earlier OTA version.

For Expo, the integration is designed for Prebuild/CNG projects and normal EAS Build workflows. EAS Build still creates the application binary; Bundle Drop handles the OTA layer after that binary is deployed. The same runtime-version model also supports bare React Native.

The service's plans are not priced by monthly active users. That was an intentional choice because I wanted teams to evaluate rollout and storage needs without treating user growth itself as an OTA cost.

The documentation describes the runtime and release model, and the Expo integration guide covers config-plugin setup, CNG, EAS Build, and runtime authority. Bundle Drop is one option among several, and I would still recommend testing its failure behavior against your own release requirements before choosing it.

Choose for recovery, not just installation

Installation is the beginning of an OTA system, not the hard part.

Before committing to a provider or a self-hosted design, write down your native compatibility rule, rollout process, health signal, rollback path, observability requirements, and exit strategy. Then test those rules with real release builds.

The best choice is the one your team can understand and operate during an incident—not merely the one with the shortest setup guide.

If you are evaluating the post-CodePush landscape, I would be interested in hearing which operational requirements have mattered most to your team.