The practical cordova-plugin-health alternative for a Capacitor app is @capgo/capacitor-health. It maps cordova.plugins.health callback queries to promise based Health calls on HealthKit and Health Connect with typed HealthDataType values in definitions.ts. This guide covers npm facts, install steps, usage, and an API map for your Cordova to Capacitor move.
Why leave cordova-plugin-health in Capacitor
cordova-plugin-health on npm is version 3.3.2. The registry modified timestamp is 27 October 2026. The source lives at dariosalvi78/cordova-plugin-health. The README documents:
cordova.plugins.health.isAvailable()requestAuthorization(datatypes, success, error)with read/write scopesquery(),queryAggregated(),store(),delete()- Android Health Connect permissions declared manually in
AndroidManifest.xml - Mandatory
privacypolicy.htmlfor Health Connect on Android - Version 3+ drops Google Fit in favor of Health Connect
In a Capacitor codebase the Cordova plugin still means cordova plugin add variables, manual manifest edits that Capacitor may not merge automatically, and string based datatype names in www/ios/health.js.
@capgo/capacitor-health latest on npm is 8.13.0 with a modified date of 14 November 2026. src/definitions.ts documents isAvailable(), requestAuthorization(), checkAuthorization(), readSamples(), saveSample(), queryAggregated(), queryWorkouts(), openHealthConnectSettings(), and showPrivacyPolicy(). Capgo ships fixes on an open source cadence where a human still reviews, tests and merges 50+ pull requests daily.
Install
bun add @capgo/capacitor-health
bunx cap sync
iOS: Enable the HealthKit capability and set NSHealthShareUsageDescription and NSHealthUpdateUsageDescription in Info.plist.
Android: Add Health Connect permissions for each HealthDataType you read or write, plus android.permission.health.READ_HEALTH_DATA_HISTORY when you need more than roughly 30 days of history via requestHistoryAccess: true in AuthorizationOptions per definitions.ts.
Usage example
import { Health } from '@capgo/capacitor-health';
export async function readTodaySteps() {
const { available } = await Health.isAvailable();
if (!available) return [];
await Health.requestAuthorization({
read: ['steps'],
write: [],
});
const { samples } = await Health.readSamples({
dataType: 'steps',
startDate: new Date(Date.now() - 86400000).toISOString(),
endDate: new Date().toISOString(),
limit: 500,
});
return samples;
}
Migrating from Cordova to Capacitor
// Before (Cordova)
cordova.plugins.health.requestAuthorization(
['steps', 'distance'],
() => {
cordova.plugins.health.query(
{ startDate: start, endDate: end, dataType: 'steps' },
(data) => console.log(data),
console.error,
);
},
console.error,
);
// After (Capacitor)
import { Health } from '@capgo/capacitor-health';
await Health.requestAuthorization({ read: ['steps', 'distance'] });
const { samples } = await Health.readSamples({
dataType: 'steps',
startDate: start.toISOString(),
endDate: end.toISOString(),
});
console.log(samples);
API mapping table
cordova-plugin-health (cordova.plugins.health) |
@capgo/capacitor-health |
|---|---|
isAvailable(success, error) |
isAvailable() returns AvailabilityResult |
requestAuthorization(datatypes, success, error) |
requestAuthorization({ read, write, requestHistoryAccess? }) |
isAuthorized(datatypes, success, error) |
checkAuthorization({ read, write }) |
query(opts, success, error) |
readSamples({ dataType, startDate, endDate, limit, ascending }) |
queryAggregated(opts, success, error) |
queryAggregated({ dataType, startDate, endDate, bucket, aggregation }) |
store(opts, success, error) |
saveSample({ dataType, value, unit?, startDate, endDate, metadata? }) |
delete(opts, success, error) |
Use platform specific delete flows in docs where exposed |
openHealthSettings() |
openHealthConnectSettings() (Android) |
launchPrivacyPolicy() (Android) |
showPrivacyPolicy() |
Cordova string datatypes like heart_rate |
Typed HealthDataType like heartRate |
| Callback errors | Promise rejection |
| Cordova plugin install | bun add @capgo/capacitor-health plus bunx cap sync |
Links and next steps
- Plugin docs: https://capgo.app/docs/plugins/health/
- Marketing page: /plugins/capacitor-health/
- npm: https://www.npmjs.com/package/@capgo/capacitor-health
- GitHub: https://github.com/Cap-go/capacitor-health/
- Cordova upstream: https://github.com/dariosalvi78/cordova-plugin-health
Health permissions live in the native binary. Plan a store build after you add types or entitlements. Use Capgo Build. For Google Fit sunset context see Google Fit to Health Connect migration. For the full platform move, read the Cordova to Capacitor migration guide.