Background GPS tracking and geofencing for React Native, built on the New Architecture.
A TurboModule for the React Native New Architecture. Drives a foreground service on Android and CLLocationManager on iOS, persists every fix to Room and Core Data, and ships native geofencing plus crash recovery so trips survive process death.
- Background tracking with configurable accuracy and distance filter
- Native geofencing (GeofencingClient on Android, CLCircularRegion on iOS)
- Persistent location storage (Room on Android, Core Data on iOS)
- Crash recovery via WorkManager and significant location monitoring
- React hooks:
useBackgroundLocation,useLocationPermissions,useLocationUpdates,useLocationTracking - Expo config plugin for managed workflows
| Requirement | Version |
|---|---|
| React Native | >=0.73 (New Architecture required) |
| iOS | >=16.0 |
| Android minSdk | 24 |
yarn add @gabriel-sisjr/react-native-background-location
cd ios && pod installAutolinking handles Android manifest merging and iOS pod registration. Bare iOS apps must still add NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSLocationAlwaysUsageDescription, and a UIBackgroundModes entry containing location to their Info.plist. See the iOS setup guide for full details.
npx expo install @gabriel-sisjr/react-native-background-location expo-build-propertiesThen add to your app.json plugins array:
{
"expo": {
"plugins": [
"@gabriel-sisjr/react-native-background-location",
["expo-build-properties", { "ios": { "deploymentTarget": "16.0" } }]
]
}
}npx expo prebuild --cleanThe plugin injects Android permissions, iOS Info.plist usage strings, and UIBackgroundModes automatically.
import {
startTracking,
useLocationUpdates,
} from '@gabriel-sisjr/react-native-background-location';
function App() {
const { locations } = useLocationUpdates();
return (
<Button
title="Start"
onPress={() => startTracking({ tripId: 'trip-1', distanceFilter: 10 })}
/>
);
}See the documentation site for the full hook reference and the permission flow that must run before tracking starts.
MIT — see LICENSE.