Community Migration

Community Geolocation Migration

Use a two-phase migration:

1. Bootstrap safely to /compat so the app stops depending on @react-native-community/geolocation.
2. Refactor from /compat to the recommended API shape.

Do not start by hand-converting every callback call site. First make the mechanical package/import migration small and reversible, verify it, then do the semantic API refactor.

Workflow

1. Inspect the target app root and check the worktree state.
2. Resolve scripts/migrate-to-compat.mjs relative to this SKILL.md.
3. Run a dry run from the target app root:

   node <skill-dir>/scripts/migrate-to-compat.mjs --root <app-root> --dry-run

4. If the dry run is expected, run it for real:

   node <skill-dir>/scripts/migrate-to-compat.mjs --root <app-root>

   The script detects packageManager or lockfiles, installs missing react-native-nitro-modules and react-native-nitro-geolocation, rewrites @react-native-community/geolocation import sources to react-native-nitro-geolocation/compat, removes @react-native-community/geolocation, and prints package-manager-specific validation commands that exist in the app's package.json.
5. Run the printed validation commands. Do not hardcode yarn, npm, pnpm, or bun; use the detected package manager and only scripts that exist.
6. Refresh the public 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

   Read llms.txt first as the docs index. Use llms-full.txt only when you need exact API names, option semantics, or examples for the API, Compat API, quick start, or platform setup. If the app already pins an older react-native-nitro-geolocation version, confirm an API exists in node_modules/react-native-nitro-geolocation or the installed package types before using docs-only APIs.
7. Find remaining community geolocation usage:

   rg "@react-native-community/geolocation|react-native-nitro-geolocation/compat|setRNConfiguration|requestAuthorization|watchPosition|clearWatch|stopObserving|navigator\\.geolocation"

   Treat navigator.geolocation as a manual-review compatibility site, not as the primary migration scope.
8. Inspect each call site before refactoring. Identify whether it is in a React function component, class component, hook, service module, background task, or test.
9. Replace compat imports with named imports from react-native-nitro-geolocation. Remove Geolocation default-object usage when the migrated file no longer needs it.
10. Convert one-shot and permission APIs to async/await or explicit Promise chains. Preserve existing loading, state, and error behavior.
11. Migrate watches to useWatchPosition only where React hook rules allow it. Use watchPosition plus unwatch for non-component code, class components, callbacks, conditionals, and services.
12. Flag unsupported or semantic changes in comments or the final report instead of guessing.
13. Run the target app's relevant detected validation commands again. If validating an actual migrated app flow on device, use agent-device when available.

Docs Reference

Use these docs endpoints as the source of truth during the API refactor:

• https://react-native-nitro-geolocation.pages.dev/llms.txt - concise index of available docs pages.
• https://react-native-nitro-geolocation.pages.dev/llms-full.txt - complete rendered docs content for agent consumption.

Prefer llms.txt for navigation and llms-full.txt for exact API details. Do not paste or load the full docs into the final answer; use them to check facts before editing. If network is unavailable, fall back to local package docs, README files, and TypeScript declarations in the installed package.

Best Practice Target

The final migration is not just "no type errors." Prefer this target state:

• No app runtime imports from @react-native-community/geolocation, navigator.geolocation, or react-native-nitro-geolocation/compat. Keep /compat only in deliberate compatibility examples, tests, or migration fallback code the user explicitly wants to preserve.
• Configure once near app startup with setConfiguration(). Do not leave setRNConfiguration() or skipPermissionRequests in migrated runtime code.
• Use explicit permission flow. Use checkPermission() only to read status without prompting; call requestPermission() from a user-understandable app moment before location work needs permission.
• Use Promise APIs for one-shot work. Prefer getCurrentPosition() when the app needs a fresh position, and getLastKnownPosition() only for cache-first UI where stale data is acceptable.
• Use lifecycle-safe watches. In function components or custom hooks, prefer useWatchPosition({ enabled }); outside hook-safe code, use watchPosition() with scoped unwatch(token) cleanup.
• Use explicit accuracy presets instead of enableHighAccuracy. Preserve existing timeout, distance, interval, and cache semantics unless the old code was clearly relying on deprecated defaults.
• Keep permission, provider/settings, and watch cleanup behavior visible in the code. Do not hide prompts or global cleanup in utility functions unless that is already the app's architecture.
• Use typed errors where handling is specific. Match on LocationErrorCodes for permission denied, timeout, settings-not-satisfied, or provider/setup failures instead of parsing error messages.

Selection Criteria

Apply these criteria at each call site, in this order:

1. Preserve user-visible behavior first: same trigger, same loading state, same success/error UI, same cleanup timing.
2. Respect React rules: never introduce hooks in classes, callbacks, conditionals, loops, services, or non-React modules.
3. Prefer the narrowest lifecycle: hook-managed watch for component state, token-managed watch for services, one-shot Promise for button/request flows.
4. Prefer explicit user consent: do not convert old implicit permission behavior into an app-start permission prompt.
5. Prefer battery-aware defaults: only request high accuracy, frequent intervals, background updates, or settings dialogs when the old code or app feature justifies it.
6. Prefer type-safe function names at module boundaries: avoid passing a Geolocation object through app code after refactoring.

Use this API choice table: