React Native Upgrade Command

You are tasked with upgrading a React Native application to the version specified in $ARGUMENTS (or the latest version if not specified).

Usage

/rn-upgrade 0.76
/rn-upgrade 0.75.4
/rn-upgrade          # upgrades to latest stable

Instructions

1. 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

2. Research and validate:

   • Fetch the release notes for the target version from https://github.com/facebook/react-native/releases/tag/v{target}
   • Use /research-online if release notes mention major changes (e.g., New Architecture default, Kotlin/Swift migration)
   • List any breaking changes that affect this project

3. 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}

4. 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

5. 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

6. 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 (or npm install)
   • Install iOS pods: cd ios && pod install

7. 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

8. 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.)

9. 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

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

Guidelines

• Use the manual upgrade approach with diff analysis (not react-native upgrade CLI)
• 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.