Upgrading React Native

title: Upgrade Helper Core Workflow impact: HIGH tags: react-native, upgrade-helper, rn-diff-purge, ios, android

Skill: Upgrade Helper Core Workflow

Reliable, framework-agnostic workflow for React Native upgrades using Upgrade Helper and rn-diff-purge.

Run shared environment checks first in upgrading-react-native.md under Prerequisites (All Upgrade Paths).

Quick Commands

npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest
curl -L "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES"
curl -L -o /tmp/rn-diff-<current_version>..<target_version>.diff "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff"
grep -n "^diff --git" /tmp/rn-diff-<current_version>..<target_version>.diff

Upgrade Helper API (Inline Reference)

• List supported versions:

  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES

• Fetch raw unified diff:

  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff

• GitHub compare view:

  • https://github.com/react-native-community/rn-diff-purge/compare/release/<current_version>..release/<target_version>

• Upgrade Helper UI:

  • https://react-native-community.github.io/upgrade-helper/?from=<current_version>&to=<target_version>

• Path mapping note:

  • Diff paths are prefixed with RnDiffApp/; remap to your app paths and package names.

Inputs

• APP_DIR: app package path (. for single-package repos)

• current_version: current React Native version

• target_version: target React Native version (latest by default)

Reliable Workflow

1. Detect app and versions.

   • Read react-native from APP_DIR/package.json.

   • Resolve target via npm view react-native dist-tags.latest unless user provides one.

2. Validate target_version exists.

   • Check RELEASES from rn-diff-purge and confirm target_version is listed.

   • If missing, stop and ask user to choose one of available versions.

3. Collect canonical sources.

   • Upgrade Helper URL.

   • rn-diff-purge raw diff.

4. Fetch diff with fallback.

   • Try exact raw diff: <current_version>..<target_version>.

   • If 404, try nearest available patch versions and report what was attempted.

   • If no available pair works, stop and ask user for target adjustment.

5. Build dependency baseline from rn-diff-purge first.

   • Start with the RnDiffApp/package.json diff for the exact version pair.

   • Do not manually install RN packages one-by-one before this baseline is captured.

6. Publish a short execution plan before edits.

   • Include ordered phases: dependency baseline, one-pass install, native/tooling merges, verification.

   • If dependency migrations are ambiguous, ask for user confirmation before modifying package choices.

7. Run dependency risk planning.

   • Use upgrading-dependencies.md.

   • Fold approved migrations into the same dependency update pass.

8. Apply dependency updates in one pass.

   • Update APP_DIR/package.json (and lockfile) from the baseline plus approved migrations.

   • Run exactly one install command with the repo's package manager (npm install, yarn install, pnpm install, or bun install).

   • Avoid piecemeal installs such as repeated npm install <pkg> unless explicitly requested.

9. Build a change checklist from diff.

   • Group by JS/TS, iOS, Android, tooling.

   • Skip template-only UI (App.tsx) unless explicitly requested.

   • Skip template-only dependencies (@react-native/new-app-screen) unless they exist in the app.

10. Apply diff safely.

• Treat RnDiffApp as placeholder; remap app/package names.

• Merge, do not overwrite project-specific customizations.

11. Sync native deps.

• Run iOS pods in APP_DIR/ios.

12. Validate and gate completion.

• iOS build passes.

• Android build passes.

• tests/typecheck/lint pass or failures are documented with next actions.

• If react was upgraded, run react.md.

• If target_version >= 0.81 and tests fail due to missing modules, add proper mocks.

  • Example (BackHandler mock removal): https://github.com/facebook/react-native/issues/52667#issuecomment-3094788618

• Run upgrade-verification.md before closing the upgrade.

Stop Conditions

• Missing react-native dependency in target package.

• Diff source unavailable and no fallback available.

• Unresolved native merge conflicts in iOS/Android entry files.

Reliability Rules

• Keep operations version-pair scoped (current_version -> target_version).

• Prefer official sources over ad-hoc guides.

• Record every manual deviation from Upgrade Helper.

• Do not run Expo-specific commands here.

Common Pitfalls

• Upgrading an Expo project with only RN CLI steps: apply the Expo layer (expo-sdk-upgrade.md).

• Skipping the Upgrade Helper: leads to missed native config changes.

• Treating RnDiffApp paths as literal project paths.

• Copying the entire template wholesale: use the diff as a guide and merge only needed changes.

• Using the wrong changelog: 0.7x changes live in CHANGELOG-0.7x.md.

• Running the wrong package manager: always match the repo lockfile.

• Forgetting CocoaPods: iOS builds will fail without pod install.

• Not updating Android Gradle wrapper binary: update android/gradle/wrapper/gradle-wrapper.jar for the target RN version. Source template:

  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/<target_version>/RnDiffApp/android/gradle/wrapper/gradle-wrapper.jar

• Flipper artifacts lingering after removal in v0.74: remove ReactNativeFlipper.kt and FLIPPER_VERSION when the target RN version drops Flipper.

• Skipping platform rebuilds after Pod/Gradle changes.

Related Skills

• upgrading-react-native.md - Routing and mode selection

• upgrading-dependencies.md - Dependency compatibility and migration plan

• expo-sdk-upgrade.md - Expo-only layer on top of core workflow

• react.md - React and React 19 alignment

• upgrade-verification.md - Post-upgrade validation, including agent-device-assisted checks

• monorepo-singlerepo-targeting.md - Repo/app selection and command scoping