React Native SDK
React Native SDK release notes
Release notes for @codemagic/react-native-patch. The other surfaces'
releases are on the Release Notes page.
npm install @codemagic/react-native-patch@latest
Reference: SDK reference · GitHub releases
0.8.0
19th November 2026
Adds a build step that records the native fingerprint and the embedded bundle's hash inside the app. See Recorded at build time.
Upgrade steps
Installing the package does not change your native project, so follow these steps before the next store build.
-
Update
cmpatchto 0.11.0 or later. -
Install the SDK:
npm install @codemagic/react-native-patch@latest -
Run
cmpatch wireagain in a bare project, ornpx expo prebuildin an Expo project. This adds the build metadata step to the native project. The step needs Node.js 20 or newer on the build machine.In a project that uses CocoaPods, wire also asks to run
pod install, becausePodfile.locknames the SDK version. In CI or a script, where wire cannot ask, pass the answers as flags:cmpatch wire --yes --allow-dirty --pod-install--allow-dirtyapplies the edits next to the uncommittedpackage.jsonfrom step 2. -
Commit the changes. In a CocoaPods project they include
ios/Podfile.lock, which is part of the fingerprint: a build from the old lockfile and a machine that runspod installcompute different fingerprints. -
Ship the result as a new binary version. The SDK's fingerprint engine gives the same native code a different fingerprint, so a release to a binary version that already has one is blocked as a mismatch. Keep releasing to those versions from a branch on the older SDK. See Disagreements.
If you skip step 3, the app builds and updates as before, and cmpatch doctor
warns that the step is missing. In a bare project, adding the step later
changes the fingerprint again.
Fixes
- Fixes a release build that failed with
Cannot read properties of undefined (reading 'getEnforcing')in an Expo Router app withweb.output: "server", the default in a new Expo SDK 58 app. The SDK now loads in a web bundle, wherewrap()returns the root unchanged.
Other changes
- Adds
@expo/fingerprint0.21.9 as a dependency.
See the SDK release.
0.7.0
17th November 2026
React Native SwiftPM mode
Ships a Package.swift, so an app converted with
npx react-native spm add can link the SDK. Before, spm add stopped on the
SDK with a mixed Swift and Objective-C sources error.
- Requires React Native 0.88 or later and the New Architecture. Expo's
experimental Swift Package Manager support needs
expo58.0.17 or later. - Run
npx react-native spmafter installing or upgrading the SDK, and on every fresh clone before a build. - Apps that use CocoaPods on React Native 0.73 or later build as before.
cmpatch wire handles both modes. See
React Native SwiftPM mode.
Fixes
- Fixes an Android crash on Expo SDK 58, with a missing
ExpoApplicationerror, when the app restarted to apply an update. The new React instance could start before the old one had shut down, which left native modules attached to the old runtime. The SDK now waits for the old instance to be destroyed before it recreates the Activity.
See the SDK release.
0.6.0
28th October 2026
Testing with the SDK fake
Ships a native-module fake for Jest and Vitest. Tests can run the real SDK and simulate OTA states without a native binary. Based on a contribution in codemagic-patch#38. See Testing your app.
Crash rollback
- On Android, a process the OS starts in the background (a headless JS task, an FCM data message) still boots the pending package, but no longer spends a launch attempt unless the user opens the app in that process. Idle processes reclaimed by the OS were the leading cause of rollbacks of packages the user never opened. A package that crashes only in background code is no longer rolled back by the budget.
- Lowers the default of
CodemagicPatchMaxLaunchAttemptsto 2 on Android and iOS, so a broken package rolls back on its third launch instead of its fourth. Set the value explicitly to keep 3.
Fixes
- Fixes Android release builds with resource shrinking removing the
CodemagicPatch*strings, which stopped the app from finding updates. On older SDKs, see Release published but app finds no update.
Other changes
- Logs a warning once on Android, under the
CodemagicPatchModuletag, whenCodemagicPatchDeploymentKeyis missing or blank.
See the SDK release.
0.5.1
19th October 2026
React Native 0.88 and Expo SDK 58
Supports React Native 0.88.0, tested with the New Architecture on Android and iOS. Supports Expo SDK 58, which uses React Native 0.88.0, tested on Android and iOS.
Fixes
- Fixes metrics uploads on a slow or unresponsive network holding up bundle
selection, update downloads,
sync(), and other SDK calls. On Android and iOS, metrics uploads now run separately from update operations.
Other changes
- Removes the unused
sdk_versionfield from metrics events. Servers still accept it from older SDKs, and existing metrics data is unchanged.
See the SDK release.
0.5.0
23rd September 2026 · Requires server 0.5.0 or newer
Patch.wrap
Adds Patch.wrap, which wraps your root component and runs an update check
after it mounts:
import * as Patch from "@codemagic/react-native-patch";
export default Patch.wrap(App);
The app renders without waiting for the check. Set
checkFrequency: CheckFrequency.ON_APP_RESUME to also check whenever the app
returns to the foreground. Other options are passed through to sync(), and
install behavior is unchanged. Mounting the wrapped root marks the running
update as healthy. If your app needs to finish an async startup step first,
call sync() after that step instead of using Patch.wrap.
CodemagicPatchMaxLaunchAttempts
Adds the optional CodemagicPatchMaxLaunchAttempts setting (Info.plist on
iOS, strings.xml on Android). It sets how many launches a pending update may
make without notifyAppReady() before it is rolled back. The default is still
3. In Expo projects, set it with the config plugin's maxLaunchAttempts option.
- Renames two lifecycle events, and requires server 0.5.0.
Installedis nowReady(the update is prepared for the next launch), andSuccessis nowApplied(the update is running and confirmed bynotifyAppReady()). Servers 0.4.x and earlier drop these events, so upgrade the server before shipping an app build with this SDK. - In development builds, a failed
sync()now logs a warning with the reason, even when nothing reads its result, as withPatch.wrap. Release builds do not log it, and a wrong deployment key or server path returns "no update" without the warning. - Concurrent
notifyAppReady()calls no longer report the same update as Applied more than once. - Fixes type errors in strict TypeScript apps on React Native 0.87.
See the SDK reference and SDK release.
0.4.0
14th September 2026
isNextVersionReady()
Adds isNextVersionReady(), which reports whether a different OTA package is
installed and waiting for the next reload. Use it to show an “Update ready”
prompt while the current bundle keeps running. It does not report a staged
return to the embedded bundle.
- Fixes returning to the embedded bundle so it honors the selected install mode, including next suspend, resume, or restart.
See the SDK reference and SDK release.
0.3.0
7th September 2026
Failure details
Failed installs now report diagnostic details that the dashboard displays: the
HTTP status, the origin or platform error message, and on Android 11+ the
previous process exit reason. Before, the dashboard showed only a network
count. See the server notes for the dashboard
side.
- A pending package now gets three consecutive launches to call
notifyAppReady()before the SDK rolls back and reportsFailed. This reduces false crash rollbacks from OS process kills, and a broken bundle is still rolled back. See Analytics and metrics.
See the SDK release.
0.2.0
22nd August 2026
getRunningBundleUpdateMetadata()
Adds getRunningBundleUpdateMetadata(), which returns label, packageHash,
and releaseNotes for the OTA release active in the current process, or
null when the app is still on the embedded store binary. Use it for an
in-app "About this build" screen or for QA.
import { getRunningBundleUpdateMetadata } from "@codemagic/react-native-patch";
const running = await getRunningBundleUpdateMetadata();
if (running) {
console.log(running.label, running.packageHash, running.releaseNotes);
}
The value does not change until the next reload. See SDK reference and the SDK release.