React Native Upgrade Command
Upgrade the application to the requested React Native version or Expo SDK target. Determine the project's workflow before resolving an omitted target to the latest stable release.
Usage
/rn-upgrade 0.76
/rn-upgrade 0.75.4
/rn-upgrade expo <SDK target>
/rn-upgrade # upgrades to latest stable
Gotchas
- The rn-diff-purge diff reflects a pristine RN template only. Custom native code (modified
MainApplication.kt,AppDelegate.swift) may be silently overwritten because it's not in the diff. - Standalone RN multi-version jumps (e.g., 0.73 → 0.76) require building and testing at each intermediate version. Expo upgrade sequences follow the SDK release notes instead.
Instructions
Choose the upgrade path
Inspect the app workspace's package.json, lockfile, app config, scripts, and native-project
documentation. An expo dependency means Expo compatibility must be checked even in an
app with manually maintained native projects; directory presence alone does not identify
the workflow.
- Expo present: read Expo SDK upgrades and follow that workflow instead of the standalone React Native steps, troubleshooting, and guidelines below. Expo determines the compatible React and React Native versions. An explicit RN target must first be mapped to a supported Expo SDK; do not independently bump RN to latest.
- No Expo dependency: follow the standalone workflow below. Do not add Expo as part of a React Native upgrade.
Standalone React Native
Determine versions:
- Check the current React Native version in package.json
- If $ARGUMENTS is not specified, fetch the latest stable version from https://github.com/facebook/react-native/releases
- Record: current version = X, target version = Y
Research and validate:
- Fetch the release notes for the target version from https://github.com/facebook/react-native/releases/tag/v{target}
- Use
research-techif release notes mention major changes (e.g., New Architecture default, Kotlin/Swift migration) - List any breaking changes that affect this project
Fetch the upgrade diff:
- Construct the diff URL:
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/{current}..{target}.diff - Fetch and analyze the diff to understand all required changes
- If the diff is unavailable, fall back to the Upgrade Helper UI: https://react-native-community.github.io/upgrade-helper/?from={current}&to={target}
- Construct the diff URL:
Check dependency compatibility:
- List all third-party native modules from package.json
- For each critical dependency, check its GitHub repo releases/changelog for target RN version support:
- Firebase: https://github.com/invertase/react-native-firebase/releases
- Navigation: https://github.com/react-navigation/react-navigation/releases
- Reanimated: https://github.com/software-mansion/react-native-reanimated/releases
- Gesture Handler: https://github.com/software-mansion/react-native-gesture-handler/releases
- Custom native modules in the project
- Flag any library that hasn't released a compatible version yet and recommend: pin, fork, or find alternative
Plan the upgrade:
- Create a task list with TaskCreate, broken into phases:
- Phase 1: Dependency updates (package.json)
- Phase 2: Android native changes (MainApplication, Gradle, gradle.properties)
- Phase 3: iOS native changes (AppDelegate, Podfile, Info.plist, .pbxproj)
- Phase 4: Library-specific migrations
- Phase 5: Install dependencies and pods
- Use EnterPlanMode to present the plan to the user for approval before making changes
- Create a task list with TaskCreate, broken into phases:
Execute the upgrade:
- Update package.json with new React Native and React versions
- Update all @react-native/* packages to match the target version
- Apply native code changes from the diff, preserving:
- Custom package names/bundle identifiers
- Third-party SDK integrations (e.g., Firebase, analytics, crash reporting)
- Custom build configurations
- Existing native modules
- Update Gradle wrapper if required by the diff
- Enable/configure New Architecture if required
- Install dependencies:
yarn install(ornpm install) - Install iOS pods:
cd ios && pod install
Important considerations:
- ALWAYS preserve custom native code integrations
- Replace template package names (e.g., com.helloworld) with the project's actual package names
- Check for react-native-fast-image compatibility (may need @d11/react-native-fast-image fork)
- Update related dependencies if needed (e.g., react-native-bootsplash, react-native-safe-area-context)
- Never skip steps without user confirmation
Post-upgrade checklist:
- Provide a testing checklist including:
- Clean builds for both platforms (
cd android && ./gradlew clean, Xcode clean build folder) - New Architecture verification (if enabled)
- Third-party integrations testing
- Navigation and animations
- Device-specific features (camera, location, notifications, etc.)
- Clean builds for both platforms (
- Provide a testing checklist including:
Documentation:
- Summarize all changes made
- List any manual follow-up actions required
- Note any dependencies that still need updates
- Provide links to relevant release notes
Examples
Expo app with generated or maintained native projects:
rn-upgrade expo
Reads the Expo reference, resolves compatible dependency versions, and establishes native
project ownership before choosing regeneration or manual migration. Existing ios/ and
android/ directories do not imply they are disposable.
Single version upgrade:
/rn-upgrade 0.76
Upgrades from current version (e.g., 0.75.3) to 0.76. Fetches the diff from rn-diff-purge, checks dependency compatibility, plans changes, and executes after approval.
Multi-version jump:
/rn-upgrade 0.76
When current version is 0.73 or older, the skill upgrades incrementally: 0.73 -> 0.74 -> 0.75 -> 0.76, one major version at a time, validating builds between each jump.
Troubleshooting
| Problem | Solution |
|---|---|
pod install fails with version conflicts |
Run cd ios && pod repo update && pod install. If still failing, delete Podfile.lock and Pods/ then retry. |
| Gradle build fails after upgrade | Clear caches: cd android && ./gradlew clean. Check that gradle-wrapper.properties matches the version from the diff. |
| Metro bundler can't resolve modules | Clear Metro cache: npx react-native start --reset-cache. Also delete node_modules and reinstall. |
| Xcode build fails with "framework not found" | Run cd ios && pod deintegrate && pod install. If using use_frameworks!, check compatibility with native modules. |
| New Architecture bridge errors | Verify all native modules support the New Architecture. Check newArchEnabled in gradle.properties (Android) and Podfile flags (iOS). |
| Diff URL returns 404 | The exact patch version may not exist in rn-diff-purge. Use the nearest available version or the Upgrade Helper UI. |
Guidelines
- Use the manual upgrade approach with diff analysis (not
react-native upgradeCLI) - Upgrade incrementally (one major version at a time) when jumping multiple versions
- Enable New Architecture in current version before upgrading if it's required in target
- Clear all caches after upgrade (Metro, Gradle, Pods, Derived Data)
- Test thoroughly on both iOS and Android before considering upgrade complete
Resources
- Upgrade Helper: https://react-native-community.github.io/upgrade-helper/
- RN Diff Purge: https://github.com/react-native-community/rn-diff-purge
- React Native Docs: https://reactnative.dev/docs/upgrading
- React Native Releases: https://github.com/facebook/react-native/releases
Start by determining the current and target versions, then proceed with research and planning before making any changes.