Upgrading React Native versions can be challenging due to tight coupling with native project templates, dependency lock-ins (like React versions), and platform-specific breaking changes (Xcode, Android Gradle Plugin). Follow these patterns to ensure safe, repeatable upgrades.
1. Pre-Upgrade Checklist
Check the Upgrade Helper: Always consult the React Native Upgrade Helper to see a diff of changes in native files (ios/ and android/) between your current version and target version.
Review peer dependencies: Ensure key community libraries (e.g., react-native-navigation, react-native-reanimated) are compatible with the target version.
Commit your state: Make sure your working directory is absolutely clean. Create a temporary branch chore/upgrade-react-native-[target-version].
2. Upgrade Execution Workflow
# 1. Update React Native and its matching React peer dependency
npm install react-native@0.X.Y react@Y.Y.Y --save
# 2. Run the React Native Community upgrade CLI tool
npx react-native upgrade
# 3. Clean local native cache directories
cd android && ./gradlew clean
cd ../ios && rm -rf Build Pods Podfile.lock && pod install
3. Resolving Android Build Issues
Gradle Alignment: Verify the Gradle wrapper version matches in android/gradle/wrapper/gradle-wrapper.properties and the Android Gradle Plugin version in android/build.gradle.
Namespace Error: Since React Native 0.71+, native packages must declare a namespace in their build.gradle rather than relying on package in AndroidManifest.xml.
Kotlin Standard Library: Align Kotlin standard library versions if libraries throw version conflict errors during assembly.
4. Resolving iOS Build Issues
Cocoapods Resolution: If pod install fails, run pod repo update to sync regional specs.
Xcode Compatibility: Upgrading to newer React Native versions might require updating Xcode to the latest SDK version.
Header Search Paths: Clear custom header search paths if they overwrite React Native core imports.
Check runtime logs for redboxes or warnings about deprecations or native module mismatches.
1---2name: upgrading-react-native3description: Upgrading React Native4---56# Upgrading React Native78## Overview910Upgrading React Native versions can be challenging due to tight coupling with native project templates, dependency lock-ins (like React versions), and platform-specific breaking changes (Xcode, Android Gradle Plugin). Follow these patterns to ensure safe, repeatable upgrades.1112## 1. Pre-Upgrade Checklist13141. **Check the Upgrade Helper**: Always consult the [React Native Upgrade Helper](https://reactnative.dev/upgrade-helper) to see a diff of changes in native files (`ios/` and `android/`) between your current version and target version.152. **Review peer dependencies**: Ensure key community libraries (e.g., `react-native-navigation`, `react-native-reanimated`) are compatible with the target version.163. **Commit your state**: Make sure your working directory is absolutely clean. Create a temporary branch `chore/upgrade-react-native-[target-version]`.1718## 2. Upgrade Execution Workflow1920```bash21# 1. Update React Native and its matching React peer dependency22npm install react-native@0.X.Y react@Y.Y.Y --save2324# 2. Run the React Native Community upgrade CLI tool25npx react-native upgrade2627# 3. Clean local native cache directories28cd android && ./gradlew clean29cd ../ios && rm -rf Build Pods Podfile.lock && pod install30```3132## 3. Resolving Android Build Issues3334- **Gradle Alignment**: Verify the Gradle wrapper version matches in `android/gradle/wrapper/gradle-wrapper.properties` and the Android Gradle Plugin version in `android/build.gradle`.35- **Namespace Error**: Since React Native 0.71+, native packages must declare a `namespace` in their `build.gradle` rather than relying on `package` in `AndroidManifest.xml`.36- **Kotlin Standard Library**: Align Kotlin standard library versions if libraries throw version conflict errors during assembly.3738## 4. Resolving iOS Build Issues3940- **Cocoapods Resolution**: If `pod install` fails, run `pod repo update` to sync regional specs.41- **Xcode Compatibility**: Upgrading to newer React Native versions might require updating Xcode to the latest SDK version.42- **Header Search Paths**: Clear custom header search paths if they overwrite React Native core imports.4344## 5. Verification Gate4546- Run **Metro bundler** with reset cache option:47 ```bash48 npx react-native start --reset-cache49 ```50- Build and run on simulator/emulator:51 ```bash52 # iOS53 npx react-native run-ios5455 # Android56 npx react-native run-android57 ```58- Check runtime logs for redboxes or warnings about deprecations or native module mismatches.
Run npx skillmds@latest add goharabbas321/upgrading-react-native in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Upgrading React Native It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
goharabbas321 (@goharabbas321) published this skill. Their other Agent Skills are listed on their SkillMD profile.
goharabbas321