React Native Nitro Geolocation
  • v2

      • Choose your path

      You are reading the 2.0 release-candidate documentation. Use this page to pick one path; you do not need to read every guide before starting.

      I want to…Start hereOutcome
      Add foreground location to a new appInstall and get a locationA foreground-only screen that renders coordinates
      Upgrade Nitro Geolocation 1.xUpgrade from 1.xAll seven 2.0 breaking changes reviewed and tested
      Replace @react-native-community/geolocationCommunity migration/compat first, then optionally adopt direct functions and hooks
      Replace react-native-geolocation-serviceService migrationNamed imports from the package
      Use an Expo appExpo development buildsA custom native build; Expo Go is not supported
      Track when the app is not activeBackground LocationNative background tracking with platform-specific setup
      Evaluate the RC for releaseRelease readinessTested-stack, RC-policy, and ship-checklist review
      Diagnose an existing integrationTroubleshootingA readiness snapshot and a useful issue report

      Choose an API surface

      The package has three intentionally separate entry points.

      SurfaceImportBest forPlatform boundary
      Functions and hooksreact-native-nitro-geolocationNew foreground code, Promise APIs, typed readiness, React watchesNative and web foreground
      Compatibility APIreact-native-nitro-geolocation/compatA controlled migration from the core community callback APINative and web foreground
      Background APIreact-native-nitro-geolocation/backgroundTracking, geofencing, persistence, Headless JS, and native syncNative only; web imports return unsupported results

      /compat preserves the core callback methods and numeric error contract. It is a migration-friendly API-shape path, not a promise that every legacy global, default, or platform-specific option behaves identically. Review the compatibility matrix before shipping.

      Check the support boundary

      • React Native 0.75 or newer with New Architecture and Nitro Modules is required for native apps.
      • Bare React Native and Expo development/custom native builds are supported. Expo Go is not supported.
      • CocoaPods is the recommended production iOS dependency path. React Native 0.87.x SwiftPM-only projects have an experimental precompiled integration; use the exact compatibility matrix in the Swift Package Manager guide.
      • Both foreground APIs support browser builds through navigator.geolocation. Background Location is native-only.
      • Android and iOS share public contracts but retain documented OS behavior and reliability limits.

      The peer range describes where installation is allowed; it is broader than the single reference combination continuously exercised by this repository. See Release readiness for the declared and tested scopes.

      RC expectations

      Install an exact RC when reproducing or approving behavior:

      yarn add react-native-nitro-modules@0.35.10 react-native-nitro-geolocation@2.0.0-rc.5

      Release candidates may still receive contract fixes before 2.0 stable. Do not silently follow the moving @rc tag in a production lockfile. Keep a tested 1.x rollback branch until the upgrade checklist and release checklist pass in your app.

      Next action

      For a new integration, continue to Install and get a location. For any existing Nitro Geolocation 1.x app, start with Upgrade from 1.x before opening the API reference.