Skip to main content

Getting Started

Get up and running with react-native-healthx in minutes.

Installation​

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

Setup​

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:

npx expo prebuild

The plugin automatically configures:

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

Bare React Native Projects​

See the platform-specific setup guides:

Basic Usage​

import HealthX from 'react-native-healthx';

async function getMyHealth() {
  // 1. Initialize
  await HealthX.initialize();

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

  console.log('Permissions granted:', permissions);

  // 3. Get sleep data
  const now = new Date();
  const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);

  const sessions = await HealthX.sleep.getSessions({
    startDate: weekAgo.toISOString(),
    endDate: now.toISOString(),
  });

  // 4. Process data
  for (const session of sessions) {
    const hours = session.duration / 3600;
    console.log(`Sleep on ${session.startTime}: ${hours.toFixed(1)} hours`);

    // Show stage breakdown
    for (const stage of session.stages) {
      console.log(`  ${stage.type}: ${stage.duration / 60} minutes`);
    }
  }
}

Example App​

We provide a complete example app that demonstrates all features of the library. It's the best way to see HealthX in action.

# Clone the repository
git clone https://github.com/joelmarquez90/react-native-healthx.git
cd react-native-healthx/example

# Install dependencies
npm install

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

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

The example app demonstrates:

  • Initialization: Check availability and initialize HealthX
  • Permissions: Request and verify health data permissions
  • Sleep Sessions: Read sleep data with detailed stages (AWAKE, LIGHT, DEEP, REM)
  • Statistics: View aggregated sleep statistics
  • Write Data: Write sleep sessions (Android only)
tip

The example app includes a real-time log viewer so you can see exactly what's happening with each API call.

Next Steps​