Before You Upgrade
Check Compatibility
- Review the CHANGELOG
- Check your dependencies for React Native compatibility
- Test in a separate branch
- Ensure you have backups or version control
Version Support
React Native follows a release cycle with:- Major versions: Breaking changes, new features
- Minor versions: New features, deprecations
- Patch versions: Bug fixes
Upgrade Methods
Method 1: React Native Upgrade Helper (Recommended)
The React Native Upgrade Helper shows exactly what changed between versions.- Visit the Upgrade Helper website
- Select your current and target versions
- Follow the diff for each file
- Apply changes manually
Method 2: Automated Upgrade
- Updates
package.jsondependencies - Attempts to merge native file changes
- May require manual conflict resolution
Upgrade Process
Step 1: Update Dependencies
Updatepackage.json:
Step 2: Update iOS Dependencies
Navigate to iOS directory:Step 3: Update Android Dependencies
Updateandroid/build.gradle:
Step 4: Clear Caches
Step 5: Test the App
Breaking Changes by Version
v0.84.0
Node.js Version Requirement
Hermes V1 Default Engine
ios/Podfile:
android/gradle.properties:
Legacy Architecture Removed
TurboModules Changes
Removed APIs
v0.83.x
Android Gradle Changes
v0.76.x
New Architecture Stabilization
Common Issues
Build failures after upgrade
Build failures after upgrade
Solutions:
-
Clear all caches:
- Update Xcode and Android Studio to latest versions
-
Check minimum iOS deployment target:
-
Rebuild native dependencies:
CocoaPods errors
CocoaPods errors
Solutions:
-
Update CocoaPods:
-
Deintegrate and reinstall:
-
Update repository:
-
Clear CocoaPods cache:
Android Gradle sync failed
Android Gradle sync failed
Solutions:
-
Update Gradle wrapper:
-
Update Android Gradle Plugin in
android/build.gradle: - Sync Gradle files in Android Studio
- Invalidate caches and restart Android Studio
Third-party library compatibility
Third-party library compatibility
Solutions:
- Check library’s React Native version support
-
Update the library:
- Check library’s GitHub for compatibility issues
- Consider alternatives if library is abandoned
-
Patch the library temporarily:
Platform-Specific Updates
iOS
Xcode Version
Check required Xcode version in release notes:Deployment Target
Update minimum iOS version inios/Podfile:
Info.plist Changes
Check for new required permissions or configurations:Android
SDK Versions
Update SDK versions inandroid/build.gradle:
Gradle Version
Update Gradle inandroid/gradle/wrapper/gradle-wrapper.properties:
AndroidManifest.xml
Add new required permissions or configurations:Testing After Upgrade
Manual Testing Checklist
- App launches successfully
- Navigation works correctly
- Network requests complete
- Animations are smooth
- Forms and inputs work
- Images and assets load
- Push notifications work
- Deep links function
- Permissions are requested
- Crashes are handled gracefully
Automated Testing
Rollback Plan
If the upgrade fails:Git Rollback
Version Pinning
Pin to specific working version:Best Practices
- Incremental upgrades: Don’t skip multiple major versions
- Test thoroughly: Run full test suite after upgrade
- Update dependencies: Keep third-party libraries current
- Read changelogs: Understand what changed and why
- Use TypeScript: Catch breaking changes at compile time
- Monitor performance: Check for performance regressions
- Update CI/CD: Ensure build pipelines work with new version
Next Steps
TypeScript
Set up TypeScript for better upgrade safety
Troubleshooting
Solve common upgrade issues