Skip to main content

iOS Setup

Manual setup for bare React Native projects without Expo.

Prerequisites​

  • React Native 0.70+
  • Xcode 14+
  • iOS 13.0+ deployment target

Installation​

npm install react-native-healthx
# or
yarn add react-native-healthx

Install pods:

cd ios && pod install

Enable HealthKit Capability​

  1. Open your project in Xcode
  2. Select your project in the navigator
  3. Select your app target
  4. Go to Signing & Capabilities tab
  5. Click + Capability
  6. Search for and add HealthKit
info

After adding the capability, you should see "HealthKit" listed under Signing & Capabilities with a checkmark.

Configure Info.plist​

Add the required usage descriptions to ios/YourApp/Info.plist:

Info.plist
<dict>
  <!-- ... other entries ... -->

  <key>NSHealthShareUsageDescription</key>
  <string>We need access to your health data to provide sleep insights.</string>

  <key>NSHealthUpdateUsageDescription</key>
  <string>We need to save your health data.</string>
</dict>
Customize Messages

Replace the placeholder text with descriptions that explain why your app needs access to health data. Apple reviews these messages during app review.

Verify Entitlements​

The HealthKit entitlements should be automatically added. Verify in ios/YourApp/YourApp.entitlements:

YourApp.entitlements
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.developer.healthkit</key>
  <true/>
  <key>com.apple.developer.healthkit.access</key>
  <array/>
</dict>
</plist>

Build and Run​

npx react-native run-ios

Testing​

Simulator Limitations

HealthKit is not available in the iOS Simulator. You must test on a physical device.

To test on a device:

  1. Connect your iPhone
  2. Select your device in Xcode
  3. Build and run

You can add test data in the Health app on your device:

  1. Open the Health app
  2. Go to Browse → Sleep
  3. Tap "Add Data"

Platform Limitations​

Sleep Data Write​

iOS HealthKit does not allow third-party apps to write sleep analysis data. The writeSession() method will throw an error on iOS.

if (HealthX.supportsWrite()) {
  await HealthX.sleep.writeSession({ ... });
} else {
  console.log('Write not supported on this platform');
}

Sleep Stages​

Detailed sleep stages (CORE, DEEP, REM, AWAKE) are only available on iOS 16 and later. On older versions, you'll only see IN_BED and ASLEEP stages.