Skill: Upgrading React Native

May 25, 2026 ยท View on GitHub

Router for React Native upgrade workflows. Start with core Upgrade Helper instructions, then apply focused add-ons by project shape.

Prerequisites (All Upgrade Paths)

  • Ensure the repo is clean or on a dedicated upgrade branch.
  • Know which package manager the repo uses (npm, yarn, pnpm, bun).
  • Use Node.js 20.19.4+, Java 17, and Xcode 16.4+ (with Command Line Tools), following https://reactnative.dev/docs/set-up-your-environment.
    • Optional: use Xcodes to manage Xcode versions.
  • Verify active versions before upgrading: node -v, java -version.
  • Verify Android Studio is installed.
  • For iOS, verify Xcode CLI toolchain is in sync (common pitfall after Xcode upgrades):
    • Check:
      • xcode-select --print-path
      • xcodebuild -version
      • xcrun --sdk iphoneos --show-sdk-version
    • If mismatch is suspected, re-point and initialize:
      • sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
      • sudo xcodebuild -runFirstLaunch

Quick Start

  1. Run the Prerequisites (All Upgrade Paths) checklist.
  2. Set APP_DIR to the app folder (. for single-app repos).
  3. Use monorepo-singlerepo-targeting.md if you need help choosing APP_DIR.
  4. Run upgrade-helper-core.md first to anchor changes to rn-diff-purge.
  5. Publish a short plan (ordered phases) before making versioned edits.
  6. Run upgrading-dependencies.md to assess risky packages and migrations.
  7. Apply dependency updates in one pass and run a single install with the repo package manager.
  8. Run react.md when react is upgraded.
  9. Add expo-sdk-upgrade.md only if expo is present in APP_DIR/package.json.
  10. Finish with upgrade-verification.md.

Decision Map