React Native Nitro Geolocation

    Quick Start

    This guide walks you through installing and setting up React Native Nitro Geolocation in your React Native project.

    1. Installation

    Before installing the module, make sure your app uses React Native 0.75+ with the New Architecture and Nitro Modules enabled.

    # Install Nitro core and Geolocation module
yarn add react-native-nitro-modules react-native-nitro-geolocation

# or using npm
npm install react-native-nitro-modules react-native-nitro-geolocation

    After installation, rebuild your native app to ensure the new module is linked.

    cd ios && pod install

    Released npm builds try to use the matching GitHub Release prebuilts first: Android downloads the release AAR and reuses its native .so files, while iOS downloads the release XCFramework. If the prebuilt asset is unavailable, the native source build is used automatically. Android prebuilts are used only when the app's React Native and Nitro Modules major/minor versions match the release asset build. To force source builds, set:

    NITRO_GEOLOCATION_USE_PREBUILT=0

    This package requires native Nitro bindings. Expo Go is not supported. For Expo apps, use prebuild, a development build, or another custom native build flow; see the Expo development build guide.

    2. iOS Setup

    Permissions

    Add the following keys to your Info.plist:

    <key>NSLocationWhenInUseUsageDescription</key>
<string>This app requires access to your location while it's in use.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app requires access to your location at all times.</string>

    For background tracking, also enable the location background mode in UIBackgroundModes; see iOS background setup.

    3. Android Setup

    Add the following permissions to your android/app/src/main/AndroidManifest.xml:

    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    Optional (for background access):

    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

    Full background tracking uses a foreground service on Android. Add the full permission set from Android background setup when using react-native-nitro-geolocation/background, including Android 13+ POST_NOTIFICATIONS for the tracking notification.

    4. Get Your First Location

    Configure once at app startup. Ask for permission from a user action, then read one position.

    import {
  getCurrentPosition,
  requestPermission,
  setConfiguration
} from 'react-native-nitro-geolocation';

setConfiguration({
  authorizationLevel: 'whenInUse',
  locationProvider: 'auto'
});

async function handleUseMyLocation() {
  const status = await requestPermission();

  if (status === 'granted') {
    const position = await getCurrentPosition({
      accuracy: { android: 'high', ios: 'best' },
      timeout: 15000
    });
  }
}

    5. Android Accuracy Helpers (Optional)

    If Android needs a settings prompt or an explicit cached read, configure the provider in your startup setConfiguration() call and add the settings helpers from the Modern API reference.

    import {
  getLastKnownPosition,
  requestLocationSettings
} from 'react-native-nitro-geolocation';

await requestLocationSettings({
  accuracy: { android: 'high' }
});

const cached = await getLastKnownPosition({
  maximumAge: 60_000,
  accuracy: { android: 'balanced', ios: 'hundredMeters' }
});

    Next Steps