Service Migration

Geolocation Service Migration

Migrate directly to react-native-nitro-geolocation.

Do not use react-native-nitro-geolocation/compat. Do not create intermediate compat imports. Do not preserve Geolocation default-object usage unless the user explicitly asks for a compatibility fallback.

Workflow

1. Inspect package.json, lockfiles, and the worktree state.
2. Confirm react-native-geolocation-service is installed or imported.
3. Install react-native-nitro-modules and react-native-nitro-geolocation.
4. Refresh docs context when network is available:

   curl -fsSL https://react-native-nitro-geolocation.pages.dev/llms.txt
   curl -fsSL https://react-native-nitro-geolocation.pages.dev/llms-full.txt

   Use llms.txt as the index and llms-full.txt only for exact API names, option semantics, or examples. If the target app pins an older installed version, confirm APIs against that package's local types.
5. Search all service usages:

   rg "react-native-geolocation-service|Geolocation\\.|requestAuthorization|showLocationDialog|forceRequestLocation|forceLocationManager|mocked|provider|PLAY_SERVICE_NOT_AVAILABLE|SETTINGS_NOT_SATISFIED|INTERNAL_ERROR|PermissionsAndroid"

6. Insert or update one app-startup setConfiguration() call. Normal react-native-geolocation-service migrations should use locationProvider: "playServices". Use "android" only when the legacy app intentionally used forceLocationManager: true.
7. Rewrite imports directly to named imports from react-native-nitro-geolocation.
8. Convert one-shot location calls to Promise chains first. Use async/await only when the surrounding function is already async or clearly safe to make async.
9. Convert watches to low-level watchPosition plus unwatch first.
10. Upgrade to useWatchPosition only for hook-safe React function components or custom hooks.
11. Convert explicit Android settings-dialog behavior from showLocationDialog: true to a requestLocationSettings() flow.
12. Remove react-native-geolocation-service.
13. Run detected validation commands.
14. Report semantic changes and manual-review sites.

Bundled Script

Resolve scripts/migrate-geolocation-service.mjs relative to this SKILL.md.

Run inventory first:

node <skill-dir>/scripts/migrate-geolocation-service.mjs --root <app-root> --inventory-only

Dry-run the direct API transform:

node <skill-dir>/scripts/migrate-geolocation-service.mjs --root <app-root> --dry-run

Optionally add startup configuration when the app startup file is obvious:

node <skill-dir>/scripts/migrate-geolocation-service.mjs \
  --root <app-root> \
  --startup-file <app-root>/src/App.tsx

The script is assistance, not a blind migration. It performs package-manager detection, dependency install/remove commands, AST-based import/callsite rewrites when Babel parser tooling is available, and a manual-review report. If the target project lacks Babel parser/generator dependencies, rerun with --allow-tool-install to install temporary codemod dependencies outside the app.

Hard Rules

• Never import from react-native-nitro-geolocation/compat.
• Never rewrite to /compat as an intermediate step.
• Prefer direct named imports.
• Configure locationProvider: "playServices" for normal react-native-geolocation-service migrations.
• Use locationProvider: "android" only when legacy code used forceLocationManager: true or the app explicitly requires Android LocationManager.
• Convert enableHighAccuracy: true to accuracy: { android: "high", ios: "best" } unless an explicit accuracy object already exists.
• Preserve explicit accuracy, timeout, maximumAge, distanceFilter, interval, fastestInterval, useSignificantChanges, and showsBackgroundLocationIndicator.
• Convert showLocationDialog: true to an explicit requestLocationSettings() flow.
• Do not auto-convert forceRequestLocation; report it.
• Do not introduce React hooks unless the file is a function component or custom hook and the call is at hook-safe top level.
• Use low-level watchPosition plus unwatch as the first safe target.
• Replace numeric error-code checks with LocationErrorCodes where possible.
• Do not remove PermissionsAndroid code unless it is clearly only for location permission and replaced by requestPermission().