react-native-healthx

Unified cross-platform health data API for React Native. Access iOS HealthKit and Android Health Connect through a single, consistent API.

Features

• Unified API: Single API for both iOS and Android
• TypeScript First: Full TypeScript support with comprehensive types
• Sleep Data: Read sleep sessions, stages, and aggregated statistics
• Promise-based: Modern async/await API
• Platform-aware: Gracefully handles platform differences
• Expo Support: Config plugin for automatic native configuration

Platform Support

| Feature | iOS (HealthKit) | Android (Health Connect) | |---------|-----------------|--------------------------| | Read Sleep | Yes | Yes | | Write Sleep | No | Yes | | Sleep Stages | Yes (iOS 16+) | Yes | | Aggregation | Yes (JS) | Yes (Native) |

Installation

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

Setup

Expo (Recommended)

If you're using Expo, add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "react-native-healthx",
        {
          "healthSharePermission": "Allow $(PRODUCT_NAME) to read your sleep data",
          "healthUpdatePermission": "Allow $(PRODUCT_NAME) to save your sleep data"
        }
      ]
    ]
  }
}

Then run prebuild to generate native code:

npx expo prebuild

The plugin automatically configures:

• iOS: HealthKit entitlements and Info.plist permissions
• Android: Health Connect permissions and intent filters in AndroidManifest.xml

Manual Setup (Bare React Native)

1. Enable HealthKit capability in Xcode:

   • Open your project in Xcode
   • Select your target → Signing & Capabilities → + Capability → HealthKit

2. Add to ios/YourApp/Info.plist:

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

3. Install pods:

cd ios && pod install

1. Ensure minimum SDK is 26 in android/build.gradle:

minSdkVersion = 26

2. Add to android/app/src/main/AndroidManifest.xml:

<manifest>
    <!-- Health Connect Permissions -->
    <uses-permission android:name="android.permission.health.READ_SLEEP" />
    <uses-permission android:name="android.permission.health.WRITE_SLEEP" />

    <!-- Health Connect Query -->
    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>

    <application>
        <!-- Add intent filter to main activity -->
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
            </intent-filter>
        </activity>
    </application>
</manifest>

3. Health Connect app must be installed (comes pre-installed on Android 14+)

Quick Start

import HealthX from 'react-native-healthx';

// Initialize
await HealthX.initialize();

// Request permissions
const permissions = await HealthX.requestPermissions({
  sleep: { read: true, write: true }
});

// Get sleep sessions
const sessions = await HealthX.sleep.getSessions({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-01-31T23:59:59Z',
});

// Get aggregated statistics
const stats = await HealthX.sleep.aggregate({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-01-31T23:59:59Z',
  groupBy: 'day',
});

Example App

Check out the example app for a complete working demonstration of all features:

cd example
npm install

# iOS (requires physical device)
npx expo prebuild --platform ios
npx expo run:ios --device

# Android
npx expo prebuild --platform android
npx expo run:android

The example app demonstrates:

• Initialization and availability checking
• Permission request flow
• Reading sleep sessions with stages
• Sleep statistics aggregation
• Writing sleep data (Android only)

API Reference

Initialization

HealthX.initialize(): Promise<boolean>

Initialize the library. Must be called before accessing any health data.

HealthX.checkAvailability(): Promise<AvailabilityStatus>

Check if health data is available on this device.

Permissions

HealthX.requestPermissions(request): Promise<PermissionResult>

Request permissions for health data access.

const result = await HealthX.requestPermissions({
  sleep: { read: true, write: true }
});

HealthX.getPermissionStatus(): Promise<FullPermissionStatus>

Get current permission status for all data types.

Sleep Module

HealthX.sleep.getSessions(options): Promise<SleepSession[]>

Get sleep sessions within a time range.

const sessions = await HealthX.sleep.getSessions({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-01-31T23:59:59Z',
  limit: 30,
  ascending: false,
});

HealthX.sleep.getLatestSession(): Promise<SleepSession | null>

Get the most recent sleep session.

HealthX.sleep.writeSession(options): Promise<string> (Android only)

Write a new sleep session.

const id = await HealthX.sleep.writeSession({
  startTime: '2024-01-15T22:00:00Z',
  endTime: '2024-01-16T06:30:00Z',
  stages: [
    { type: 'LIGHT', startTime: '...', endTime: '...' },
    { type: 'DEEP', startTime: '...', endTime: '...' },
    { type: 'REM', startTime: '...', endTime: '...' },
  ],
  title: 'Good night',
  notes: 'Slept well',
});

HealthX.sleep.deleteSession(id): Promise<boolean> (Android only)

Delete a sleep session by ID.

HealthX.sleep.aggregate(options): Promise<SleepAggregateResult>

Get aggregated sleep statistics.

const stats = await HealthX.sleep.aggregate({
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-01-31T23:59:59Z',
  groupBy: 'day', // 'hour' | 'day' | 'week' | 'month'
});

// Result:
// {
//   data: [
//     {
//       periodStart: '2024-01-01T00:00:00Z',
//       periodEnd: '2024-01-02T00:00:00Z',
//       totalDuration: 28800, // 8 hours in seconds
//       sessionCount: 1,
//       stageBreakdown: {
//         LIGHT: 10800,
//         DEEP: 7200,
//         REM: 5400,
//         AWAKE: 1800,
//       }
//     },
//     // ... more days
//   ],
//   sources: ['Apple Watch', 'Health']
// }

Types

SleepSession

interface SleepSession {
  metadata: {
    id: string;
    source: {
      name: string;
      bundleId: string;
    };
  };
  startTime: string;  // ISO 8601
  endTime: string;    // ISO 8601
  duration: number;   // seconds
  stages: SleepStage[];
  title?: string;
  notes?: string;
}

SleepStage

interface SleepStage {
  type: SleepStageType;
  startTime: string;
  endTime: string;
  duration: number;
}

type SleepStageType =
  | 'UNKNOWN'
  | 'AWAKE'
  | 'IN_BED'
  | 'SLEEPING'
  | 'LIGHT'
  | 'DEEP'
  | 'REM'
  | 'OUT_OF_BED';

Platform Differences

Sleep Stage Mapping

| Unified Type | iOS HealthKit | Android Health Connect | |--------------|---------------|------------------------| | UNKNOWN | UNKNOWN | UNKNOWN (0) | | AWAKE | AWAKE | AWAKE (1) | | IN_BED | INBED | - | | SLEEPING | ASLEEP | SLEEPING (2) | | LIGHT | CORE | LIGHT (4) | | DEEP | DEEP | DEEP (5) | | REM | REM | REM (6) | | OUT_OF_BED | - | OUT_OF_BED (3) |

Write Support

• iOS: Sleep data write is not supported by HealthKit for third-party apps
• Android: Full read/write support via Health Connect

Aggregation

• iOS: Calculated in JavaScript from raw samples
• Android: Native aggregation support via Health Connect

Roadmap

• [x] Sleep data (read)
• [x] Sleep data (write - Android)
• [x] Aggregation (native Android, JS fallback iOS)
• [x] Expo config plugin
• [ ] Steps data
• [ ] Heart rate data
• [ ] Workout data
• [ ] Background observers

Documentation

For detailed documentation, visit react-native-healthx.github.io

Contributing

See CONTRIBUTING.md for details on how to contribute.

License

MIT - See LICENSE for details.

Credits

This library is inspired by and builds upon:

• react-native-health (iOS)
• react-native-health-connect (Android)