React Native Nitro Geolocation

    Agent Context Map

    Use this map when you need code context for geolocation behavior but do not need to read generated Nitro files, full app bundles, or every scenario screen.

    Start Here for This Task

    Pick the smallest entry point that matches your change:

    TaskRead firstThen read
    Public foreground API behaviorpackages/react-native-nitro-geolocation/src/api/packages/react-native-nitro-geolocation/src/NitroGeolocation.nitro.ts, then platform files below
    Community compatibility behaviorpackages/react-native-nitro-geolocation/src/compat/packages/react-native-nitro-geolocation/src/NitroGeolocationCompat.nitro.ts
    Background API shapepackages/react-native-nitro-geolocation/src/background/index.tspackages/react-native-nitro-geolocation/src/background/NitroBackgroundLocation.nitro.ts
    Android foreground native bugpackages/react-native-nitro-geolocation/android/src/main/java/com/margelo/nitro/nitrogeolocation/NitroGeolocation.ktNearby Android helper for the specific feature
    Android background native bugpackages/react-native-nitro-geolocation/android/src/main/java/com/margelo/nitro/nitrogeolocation/NitroBackgroundLocation.ktpackages/react-native-nitro-geolocation/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/
    iOS foreground native bugpackages/react-native-nitro-geolocation/ios/NitroGeolocation.swiftNearby iOS helper for the specific feature
    iOS background native bugpackages/react-native-nitro-geolocation/ios/NitroBackgroundLocation.swiftIOSBackgroundLocationDelegate.swift, IOSBackgroundMotion.swift, IOSBackgroundHttpSync.swift
    E2E failureMatching examples/v0.81.1/.maestro/*.yaml fileMatching examples/v0.81.1/src/screens/*Screen.tsx file
    E2E shared UI or selectorsexamples/v0.81.1/src/screens/scenario/examples/v0.81.1/src/App.tsx for route names

    Avoid these until needed:

    • packages/react-native-nitro-geolocation/nitrogen/generated/**: generated bindings. Read only to debug codegen output.
    • docs/doc_build/**: generated documentation output.
    • examples/*/node_modules/**: installed dependencies.
    • Full scenario screen sweeps. Use the E2E map below to open only the failing flow and its screen.

    Native Responsibility Map

    Shared TypeScript Layer

    AreaResponsibilityMain files
    Modern foreground APIPublic wrappers for current position, watch, permission, provider, geocoding, heading, settings, and availability APIs.src/api/, src/NitroGeolocation.nitro.ts
    Community compatibility API@react-native-community/geolocation-style callbacks and configuration.src/compat/, src/NitroGeolocationCompat.nitro.ts
    Background APIPublic background exports, listener narrowing, storage methods, geofence helpers, activity recognition helpers, HTTP sync helper, and task registration.src/background/index.ts, src/background/task.ts, src/background/types.ts, src/background/NitroBackgroundLocation.nitro.ts
    Web fallbackBrowser geolocation behavior and web E2E support.src/web/, src/index.web.tsx, src/background/index.web.ts

    Android Foreground

    ResponsibilityMain files
    Nitro foreground module entry pointandroid/src/main/java/com/margelo/nitro/nitrogeolocation/NitroGeolocation.kt
    Compatibility module entry pointandroid/src/main/java/com/margelo/nitro/nitrogeolocation/NitroGeolocationCompat.kt
    One-shot current positionGetCurrentPosition.kt, AndroidFusedRequestFactory.kt
    Position watchWatchPosition.kt, AndroidFusedRequestFactory.kt
    PermissionsRequestAuthorization.kt
    Options and conversionAndroidGeolocationOptions.kt, AndroidGeolocationConversions.kt, LocationValues.kt
    Provider/settings/statusAndroidLocationSettings.kt, AndroidGeolocationErrors.kt
    HeadingAndroidHeadingManager.kt

    Android Background

    ResponsibilityMain files
    Nitro background module entry pointandroid/src/main/java/com/margelo/nitro/nitrogeolocation/NitroBackgroundLocation.kt
    Background orchestrationandroid/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundLocationController.kt
    Foreground service trackingNitroBackgroundLocationService.kt, NitroBackgroundNotificationFactory.kt
    Location delivery from system callbacksNitroLocationUpdateReceiver.kt
    Event fan-out to JS listenersNitroBackgroundEventHub.kt
    Native persistenceNitroBackgroundStore.kt, AndroidBackgroundSerialization.kt
    Background permission contractAndroidBackgroundPermissions.kt
    GeofencingNitroGeofenceReceiver.kt
    Android Headless JSNitroBackgroundHeadlessTaskService.kt
    Start on bootNitroBootReceiver.kt
    Activity recognitionNitroActivityRecognitionReceiver.kt
    HTTP syncAndroidBackgroundHttpSync.kt

    iOS Foreground

    ResponsibilityMain files
    Nitro foreground module entry pointios/NitroGeolocation.swift
    Compatibility module entry pointios/NitroGeolocationCompat.swift
    Core Location manager and delegateios/LocationManager.swift, ios/IOSGeolocationDelegate.swift
    Options and conversionios/IOSGeolocationOptions.swift, ios/IOSGeolocationConversions.swift
    Error mappingios/IOSGeolocationErrors.swift
    Mock/provider metadataios/CLLocation+GeolocationMetadata.swift

    iOS Background

    ResponsibilityMain files
    Nitro background module, storage, status, geofences, and Core Location start/stopios/NitroBackgroundLocation.swift
    Background Core Location delegateios/IOSBackgroundLocationDelegate.swift
    Activity recognition conversionios/IOSBackgroundMotion.swift
    Native HTTP syncios/IOSBackgroundHttpSync.swift
    Persistence serializationios/IOSBackgroundSerialization.swift

    E2E Scenario File Map

    All native E2E flows live in examples/v0.81.1/.maestro/. Route names and deep links live in examples/v0.81.1/src/App.tsx. Shared selectors, result blocks, permission helpers, and location assertions live in examples/v0.81.1/src/screens/scenario/.

    FlowMaestro fileApp screen
    Master native smoke suiteall-tests.yamlMultiple screens
    Permission check/requestpermission-check.yamlPermissionCheckScreen.tsx
    Current positioncurrent-position.yamlCurrentPositionScreen.tsx
    Watch positionwatch-position.yamlWatchPositionScreen.tsx
    Location simulationlocation-simulation.yamlLocationSimulationScreen.tsx
    Accuracy presetsaccuracy-presets.yamlAccuracyPresetsScreen.tsx
    Last known positionlast-known-position.yamlLastKnownPositionScreen.tsx
    Geocoding and reverse geocodinggeocoding.yamlGeocodingScreen.tsx
    Location availabilitylocation-availability.yamlLocationAvailabilityScreen.tsx
    Heading dispatcherheading.yamlHeadingScreen.tsx
    Android headingheading-android.yamlHeadingScreen.tsx
    iOS headingheading-ios.yamlHeadingScreen.tsx
    Android request optionsandroid-request-options.yamlAndroidRequestOptionsScreen.tsx
    Android provider selectionandroid-provider-selection.yamlAndroidRequestOptionsScreen.tsx
    Android provider settingsprovider-settings.yaml, provider-settings-not-ready.yamlProviderSettingsScreen.tsx
    iOS location tuningios-location-tuning.yamlIOSLocationTuningScreen.tsx
    iOS accuracy authorizationios-accuracy-authorization.yamlIOSAccuracyAuthorizationScreen.tsx
    iOS release bridge optionsios-release-options-bridge.yamlIOSReleaseOptionsBridgeScreen.tsx
    Issue 67 coarse Android locationissue-67-android-coarse-location.yamlIssue67Screen.tsx
    Background API smokebackground-e2e.yamlBackgroundE2EScreen.tsx
    Android long-run backgroundbackground-long-run-android.yamlLongRunBackgroundE2EScreen.tsx, backgroundLongRunTask.ts
    Android long-run reboot armingbackground-long-run-android-arm-reboot.yamlLongRunBackgroundE2EScreen.tsx
    Android long-run reboot proofbackground-long-run-android-reboot.yamlLongRunBackgroundE2EScreen.tsx, backgroundLongRunTask.ts
    iOS long-run backgroundbackground-long-run-ios.yamlLongRunBackgroundE2EScreen.tsx
    Mocked metadata Android truemocked-metadata-android-true.yamlMockedMetadataScreen.tsx
    Mocked metadata Android falsemocked-metadata-android-false.yamlMockedMetadataScreen.tsx
    Mocked metadata iOS truemocked-metadata-ios-true.yamlMockedMetadataScreen.tsx
    Mocked metadata iOS falsemocked-metadata-ios-false.yamlMockedMetadataScreen.tsx
    API errorsapi-errors.yamlApiErrorsScreen.tsx
    Community compatibility APIcompat-api.yamlCompatScreen.tsx
    Web E2E available pathweb-e2e.yamlWebE2EScreen.tsx, examples/web-e2e/
    Web E2E unavailable pathweb-e2e-unavailable.yamlWebE2EScreen.tsx, examples/web-e2e/

    E2E Command Map

    Run from repo root with the matching workspace script:

    TargetCommand
    Android native smoke suiteyarn workspace react-native-nitro-geolocation-example test:e2e:android
    iOS native smoke suiteyarn workspace react-native-nitro-geolocation-example test:e2e:ios
    Android long-run backgroundyarn workspace react-native-nitro-geolocation-example test:e2e:background-long-run:android
    Android long-run background with rebootRUN_REBOOT=1 yarn workspace react-native-nitro-geolocation-example test:e2e:background-long-run:android
    iOS long-run backgroundyarn workspace react-native-nitro-geolocation-example test:e2e:background-long-run:ios
    Android web E2Eyarn workspace react-native-nitro-geolocation-example test:e2e:web:android
    iOS web E2Eyarn workspace react-native-nitro-geolocation-example test:e2e:web:ios

    Android all-tests.yaml can include live provider-selection checks through android-provider-selection.yaml when RUN_ANDROID_PROVIDER_SELECTION=1 is set.