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

npx react-native 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:
{
  "dependencies": {
    "react": "19.2.3",
    "react-native": "0.84.0"
  }
}
Install dependencies:
npm install

Step 2: Update iOS Dependencies

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

Step 3: Update Android Dependencies

Update android/build.gradle:
buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 24
        compileSdkVersion = 35
        targetSdkVersion = 35
        ndkVersion = "26.1.10909125"
    }
}

Step 4: Clear Caches

# Clear Metro bundler cache
npx react-native start --reset-cache

# Clear iOS build
rm -rf ios/build

# Clear Android build
cd android && ./gradlew clean && cd ..

# Clear node modules
rm -rf node_modules && npm install

Step 5: Test the App

# iOS
npx react-native run-ios

# Android
npx react-native run-android

Breaking Changes by Version

v0.84.0

React Native 0.84.0 includes significant breaking changes.

Node.js Version Requirement

# Minimum Node.js version
node --version  # Must be v22.11+
Migration:
# Using nvm
nvm install 22
nvm use 22

Hermes V1 Default Engine

// Hermes is now the default JavaScript engine
// No action needed unless you want to disable it
To disable Hermes (not recommended): iOS - ios/Podfile:
:hermes_enabled => false
Android - android/gradle.properties:
hermesEnabled=false

Legacy Architecture Removed

The legacy architecture is removed by default. You must use the New Architecture or stay on older versions.
# iOS - ios/Podfile
# This is now the default, no action needed
:fabric_enabled => true
# Android - android/gradle.properties
newArchEnabled=true

TurboModules Changes

// TurboCxxModule and CxxModule removed
// Migrate to TurboModules

// Before:
class MyModule : public facebook::xplat::module::CxxModule {
  // ...
};

// After: Use TurboModules with Codegen

Removed APIs

// XHRInterceptor - Deprecated
// Use Chrome DevTools Protocol Network domain instead

// Before:
import {XHRInterceptor} from 'react-native/Libraries/Network/XHRInterceptor';

// After: Use CDP or other debugging tools

v0.83.x

Android Gradle Changes

// android/build.gradle
buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 23  // Increased from 21
        compileSdkVersion = 34
        targetSdkVersion = 34
    }
}

v0.76.x

New Architecture Stabilization

// Enable New Architecture (Fabric + TurboModules)
iOS:
# ios/Podfile
use_frameworks! :linkage => :static
:fabric_enabled => true
Android:
# android/gradle.properties
newArchEnabled=true

Common Issues

Solutions:
  1. Clear all caches:
    rm -rf node_modules ios/Pods ios/build android/build
    npm install && cd ios && pod install
    
  2. Update Xcode and Android Studio to latest versions
  3. Check minimum iOS deployment target:
    # ios/Podfile
    platform :ios, '13.4'  # Update to minimum required
    
  4. Rebuild native dependencies:
    npx react-native clean
    
Solutions:
  1. Update CocoaPods:
    sudo gem install cocoapods
    
  2. Deintegrate and reinstall:
    cd ios
    pod deintegrate
    pod install
    
  3. Update repository:
    pod repo update
    
  4. Clear CocoaPods cache:
    pod cache clean --all
    
Solutions:
  1. Update Gradle wrapper:
    cd android
    ./gradlew wrapper --gradle-version=8.3
    
  2. Update Android Gradle Plugin in android/build.gradle:
    classpath("com.android.tools.build:gradle:8.1.0")
    
  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:
    npm update library-name
    
  3. Check library’s GitHub for compatibility issues
  4. Consider alternatives if library is abandoned
  5. Patch the library temporarily:
    npx patch-package library-name
    

Platform-Specific Updates

iOS

Xcode Version

Check required Xcode version in release notes:
# Check current Xcode version
xcodebuild -version

Deployment Target

Update minimum iOS version in ios/Podfile:
platform :ios, '13.4'  # Or higher as required

Info.plist Changes

Check for new required permissions or configurations:
<!-- ios/YourApp/Info.plist -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Your description</string>

Android

SDK Versions

Update SDK versions in android/build.gradle:
compileSdkVersion = 35
targetSdkVersion = 35
minSdkVersion = 24  // Check minimum required

Gradle Version

Update Gradle in android/gradle/wrapper/gradle-wrapper.properties:
distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip

AndroidManifest.xml

Add new required permissions or configurations:
<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

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

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

Rollback Plan

If the upgrade fails:

Git Rollback

# Discard all changes
git reset --hard HEAD

# Or rollback to specific commit
git reset --hard <commit-hash>

# Reinstall dependencies
rm -rf node_modules
npm install
cd ios && pod install

Version Pinning

Pin to specific working version:
{
  "dependencies": {
    "react-native": "0.83.2"  // Specific version, not ^0.83.2
  },
  "resolutions": {
    "react-native": "0.83.2"
  }
}

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

Build docs developers (and LLMs) love