Documentation
react-native-release-health
Vendor-neutral OTA rollout health for React Native: tag every session with the active update, put fresh updates on probation, detect crash-looping rollouts on the device, and recommend or trigger rollback, exported to your own endpoint or Sentry.
OTA updates ship JavaScript straight to production. When one of them is broken, nothing in the default stack notices: the update applies, the app crashes on launch, the user relaunches, it crashes again. Your crash reporter sees a spike but cannot tell you which update caused it or whether the fix is to roll back. Your OTA dashboard shows the download count going up and nothing else. The delivery pipelines are excellent; the feedback loop about whether a rollout actually works on devices is missing.
react-native-release-health closes that loop on the device, per update id, and works with your
OTA vendor rather than against it.
This is a
0.xbeta. The API is stable enough to build on, but it may still change before1.0. Pin a version and read the changelog when you upgrade.
ReleaseHealth.init({
adapter: expoUpdatesAdapter(),
sinks: [httpSink({ url: 'https://telemetry.example.com/release-health' })],
});
// Call this once your first screen is genuinely interactive.
ReleaseHealth.markHealthy();Start with Getting started, or jump to a package or the API from the sidebar.
How it works
- Every launch is tagged with the active update id and native build.
- A freshly applied update goes on probation. Your app calls
markHealthy()once its first screen is genuinely interactive. - No
markHealthy()within the timeout makes the update suspect. A crash or abnormal exit followed by a relaunch counts against it; hitting the crash-loop threshold makes it failed. - A failed update fires
rollback_recommended(androllback_executed, when the adapter supports client rollback and you opted in withautoRollback). - Every step is exported as a typed event stream to any sink: your own HTTP endpoint, Sentry tags
and breadcrumbs, or anything that implements the two-method
Sinkinterface.
What is in the box
| Package | Purpose |
|---|---|
react-native-release-health | Core: native build info, persisted launch flags, the clean-exit heuristic, and the health engine |
@release-health/adapter-expo-updates | Adapter for expo-updates (EAS Update). Recommendation-only: expo-updates has no client rollback API |
@release-health/adapter-hot-updater | Adapter for hot-updater, including client-side rollback() and autoRollback |
@release-health/sink-http | Batching HTTP sink: posts the event stream as JSON to any endpoint |
@release-health/sink-sentry | Sentry sink: tags every Sentry event with ota.update_id and ota.status, plus breadcrumbs |
Adapters and sinks are peer-based and duck-typed: none of them hard-depend on the vendor SDK, and every one degrades to a safe no-op with a single actionable warning instead of crashing the host app.
Compared to the alternatives
| Delivers updates | On-device health verdict | Rollback loop | Vendor-neutral | |
|---|---|---|---|---|
| EAS Update / expo-updates | yes | no | server-side, manual | no |
| hot-updater | yes | first-launch native crash guard | server-side console | no |
| Sentry release health | no | crash-free session rates, per release | no | yes |
| react-native-release-health | no, on purpose | probation, crash-loop, per update id | recommends; executes where the vendor allows | yes |
The delivery vendors are good at delivery, and Sentry is good at crash truth. This library is the missing piece between them: the on-device judgment of whether the rollout you just shipped is healthy, expressed per update id, with a rollback recommendation you can automate.
Compatibility
| Area | Supported |
|---|---|
| React Native | 0.76 or newer, New Architecture only (TurboModule, bridgeless). Developed against 0.83 |
| Platforms | iOS and Android |
| Expo | Yes. No config plugin needed for the core module; the example apps are Expo SDK 55 dev clients |
| expo-updates | 55.0.0 or newer (adapter peer) |
| @hot-updater/react-native | 0.35.0 or newer (adapter peer) |
| @sentry/react-native | 7.0.0 or newer (sink peer) |
| Node | Legacy architecture is not supported |
Out of scope
No update delivery, no hosted dashboard, no symbolication. Delivery belongs to your OTA vendor, and crash stack traces belong to your crash reporter. This library is the on-device verdict in between, exported through sinks so you can aggregate it wherever you already look. Read Limitations before you trust it in production.
The source lives at github.com/release-health/react-native-release-health under the MIT license.