Skip to main content
Upgrading React Native requires careful attention to breaking changes, native dependencies, and platform-specific updates. This guide walks you through the upgrade process.

Before You Upgrade

Check Compatibility

  1. Review the CHANGELOG
  2. Check your dependencies for React Native compatibility
  3. Test in a separate branch
  4. 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

The React Native Upgrade Helper shows exactly what changed between versions.
  1. Visit the Upgrade Helper website
  2. Select your current and target versions
  3. Follow the diff for each file
  4. Apply changes manually

Method 2: Automated Upgrade

This command:
  • Updates package.json dependencies
  • Attempts to merge native file changes
  • May require manual conflict resolution
Automated upgrades can create merge conflicts. Always review changes before committing.

Upgrade Process

Step 1: Update Dependencies

Update package.json:
Install dependencies:

Step 2: Update iOS Dependencies

Navigate to iOS directory:
If you encounter CocoaPods errors, try: pod deintegrate && pod install

Step 3: Update Android Dependencies

Update android/build.gradle:

Step 4: Clear Caches

Step 5: Test the App

Breaking Changes by Version

v0.84.0

React Native 0.84.0 includes significant breaking changes.

Node.js Version Requirement

Migration:

Hermes V1 Default Engine

To disable Hermes (not recommended): iOS - ios/Podfile:
Android - android/gradle.properties:

Legacy Architecture Removed

The legacy architecture is removed by default. You must use the New Architecture or stay on older versions.

TurboModules Changes

Removed APIs

v0.83.x

Android Gradle Changes

v0.76.x

New Architecture Stabilization

iOS:
Android:

Common Issues

Solutions:
  1. Clear all caches:
  2. Update Xcode and Android Studio to latest versions
  3. Check minimum iOS deployment target:
  4. Rebuild native dependencies:
Solutions:
  1. Update CocoaPods:
  2. Deintegrate and reinstall:
  3. Update repository:
  4. Clear CocoaPods cache:
Solutions:
  1. Update Gradle wrapper:
  2. Update Android Gradle Plugin in android/build.gradle:
  3. Sync Gradle files in Android Studio
  4. Invalidate caches and restart Android Studio
Solutions:
  1. Check library’s React Native version support
  2. Update the library:
  3. Check library’s GitHub for compatibility issues
  4. Consider alternatives if library is abandoned
  5. Patch the library temporarily:

Platform-Specific Updates

iOS

Xcode Version

Check required Xcode version in release notes:

Deployment Target

Update minimum iOS version in ios/Podfile:

Info.plist Changes

Check for new required permissions or configurations:

Android

SDK Versions

Update SDK versions in android/build.gradle:

Gradle Version

Update Gradle in android/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

  1. Incremental upgrades: Don’t skip multiple major versions
  2. Test thoroughly: Run full test suite after upgrade
  3. Update dependencies: Keep third-party libraries current
  4. Read changelogs: Understand what changed and why
  5. Use TypeScript: Catch breaking changes at compile time
  6. Monitor performance: Check for performance regressions
  7. 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