Migrate from ROOK SDK 4.x to 5.x

ROOK SDK 4.x and 5.x are two architecture tracks published under the same npm package name:

Before	After
React Native 0.73	React Native 0.83
Classic Native Modules bridge	New Architecture and TurboModules
react-native-rook-sdk@^4	react-native-rook-sdk@^5
Current reference version: 4.1.1	Current reference version: 5.2.0

The migration is useful because it makes the architecture boundary explicit. Most ROOK hooks and the RookSyncGate integration remain familiar, but the native binary, code generation, direct module access, and a few permission method names change.

Upgrade the application architecture first

Version 5.x is the TurboModule line. Do not update only the ROOK dependency in a React Native 0.73 classic-architecture application. First migrate the client application to React Native 0.83 and enable the New Architecture, confirm that the app builds, and then move ROOK to 5.x.

1. Prepare the migration

Before changing dependencies:

1. Create a migration branch and record a working iOS and Android build.
2. Search the application for getRookModule, NativeEventEmitter, and the renamed permission methods listed below.
3. Record the enabled Apple Health, Health Connect, and Samsung Health permissions.
4. Confirm that the client can test authentication, permission requests, a manual sync, background sync, and local data reads.

If the application cannot move to React Native 0.83 yet, remain on react-native-rook-sdk@^4.

2. Upgrade React Native

Upgrade the client application from React Native 0.73 to 0.83 using the React Native upgrade process. Enable the New Architecture for iOS and Android and verify a build without changing ROOK's major version in the same step.

The 5.x development toolchain uses Node.js 22, JDK 17, CocoaPods, and Xcode 26.0. The consuming application must also satisfy the platform requirements of React Native 0.83 and the ROOK native dependencies.

3. Change the ROOK dependency

Update the dependency while keeping the package name unchanged:

{
  "dependencies": {
-   "react-native-rook-sdk": "^4.1.1"
+   "react-native-rook-sdk": "^5.2.0"
  }
}

Then reinstall JavaScript dependencies, install iOS pods, and rebuild both native applications:

npm install
npx pod-install

On Android, regenerate the native build after dependency installation. Do not reuse an APK, app bundle, or iOS build produced with 4.x.

note

ROOK contains native code. Use a bare React Native application or a custom development build; Expo Go cannot load either SDK track.

4. Keep the shared integration

RookSyncGate and the supported hooks remain imported from the same package. In most applications, this configuration does not need an architecture-specific rewrite:

import { RookSyncGate } from "react-native-rook-sdk";

export default function App() {
  return (
    <RookSyncGate
      environment="sandbox"
      clientUUID="YOUR_CLIENT_UUID"
      secret="YOUR_SECRET"
      enableLogs={false}
      enableBackgroundSync={false}
    >
      <Application />
    </RookSyncGate>
  );
}

Continue to use the public hooks for configuration, permissions, synchronization, and local data:

• useRookConfiguration
• useRookPermissions
• useRookSync
• useRookData
• useRookVariables
• useRookAppleHealth, useRookHealthConnect, and useRookSamsungHealth

5. Replace direct native-module access

In 4.x, advanced integrations obtain the classic native module with getRookModule():

import { getRookModule } from "react-native-rook-sdk";

const rookSdk = getRookModule();

In 5.x, getRookModule is removed. The generated TurboModule is exported as RookSdk:

import { RookSdk } from "react-native-rook-sdk";

Prefer the public hooks whenever a hook covers the operation. Direct calls to RookSdk couple the application to the native specification and should be limited to APIs that intentionally expose the module, such as the event emitter described in Listening to notifications.

6. Update renamed permission methods

The permission hook remains useRookPermissions, but these public method names change in 5.x:

4.x method	5.x method
requestWriteNutritionPermission	requestAppleWriteNutritionPermission
requestDisableBatteryOptimizations	requestUnrestrictedBatteryUsage
requiresOemAutoStartSetup	isAutoStartSettingRequired
openOemAutoStartSetup	openAutoStartSettings

Example:

const permissions = useRookPermissions();

-await permissions.requestWriteNutritionPermission();
+await permissions.requestAppleWriteNutritionPermission();

-const required = await permissions.requiresOemAutoStartSetup();
+const required = await permissions.isAutoStartSettingRequired();

Version 5.2 also exposes checkHistoryReadStatus() for the Health Connect history-read permission. Review the current permission enums when migrating: the 5.x native SDKs include additional Apple Health and Samsung Health data types, but applications should request only the data they use.

7. Update notification listeners

4.x uses React Native's NativeEventEmitter with getRookModule(). In 5.x, subscribe to the typed TurboModule event:

import { RookSdk } from "react-native-rook-sdk";

const subscription = RookSdk.onRookMessage((message) => {
  console.log(message.type, message.value, message.message);
});

subscription.remove();

See Listening to notifications for lifecycle-safe examples for both versions.

8. Validate before release

Test the following on physical iOS and Android devices:

• RookSyncGate becomes ready with the expected bundle ID or package name.
• User ID creation, update, and removal still work.
• Apple Health, Health Connect, and Samsung Health availability checks return the expected state.
• Each permission flow requests only the permissions declared by the application.
• Manual summary and event synchronization succeeds.
• Background synchronization starts only after user consent.
• Notification subscriptions are removed when their component unmounts.
• Local summaries, events, steps, calories, and heart-rate reads used by the application still deserialize correctly.

Run TypeScript checks after the dependency update. The 5.x types are generated from the TurboModule specification, so direct native calls or type imports that were not part of the supported hook surface may require changes even when their runtime behavior is equivalent.

Rollback

If the client must roll back the application architecture, restore both parts of the pairing: React Native 0.73 with react-native-rook-sdk@^4. Do not run the 5.x TurboModule package in a classic-architecture build.