Skip to main content

Upgrading and Migrating

1. Checking Current Version

Command Description Output
npx react-native --version Check the version of React Native CLI installed globally 0.73.0
npx react-native config Display the React Native configuration including version JSON object with version field
npm list react-native Check the installed version of React Native in your project react-native@0.73.0
yarn list react-native Check the installed version of React Native in your project using Yarn react-native@0.73.0

Example: Check React Native Version in Package.json

{
  "dependencies": {
    "react-native": "0.73.0"
  }
}

2. Using React Native Upgrade Helper

Example: Using the React Native Upgrade Helper CLI

# Install the upgrade helper
npm install -g react-native-upgrade-helper

# Run the upgrade helper for a specific version
react-native-upgrade-helper --from 0.66.0 --to 0.67.0

# Generate a diff for manual review
react-native-upgrade-helper --from 0.66.0 --to 0.67.0 --diff
Option Values Description
--from 0.66.0 Current React Native version to upgrade from
--to 0.67.0 Target React Native version to upgrade to
--diff true Generate a diff for manual review instead of auto-fixing
--dry-run false Preview changes without applying them
Note: The upgrade helper does not automatically fix all issues. It provides a diff and highlights files that need manual attention.

3. Upgrading React Native

Example: Upgrade React Native version

npm install react-native@0.73.0
Version Changes Notes
0.73.0 react-native@0.73.0 Latest stable version as of 2026
0.72.0 react-native@0.72.0 Previous stable version
Note: Always check the official React Native upgrade guide for breaking changes and migration steps.
Warning: Ensure all dependencies are compatible with the new React Native version before upgrading.

Upgrade Steps

  • Backup your project
  • Update react-native version in package.json
  • Run npm install or yarn install
  • Update any deprecated APIs
  • Test the application on both platforms

4. Handling Breaking Changes

Common Breaking Changes in React Native

  • Changes to the core API (e.g., Navigator removed in favor of NavigationContainer)
  • Updates to component lifecycle methods (e.g., componentWillMount deprecated)
  • Changes in how navigation is handled (e.g., react-navigation v5+)
  • Updates to the React Native CLI or build process
Change Type Description Migration Path
Navigation API Navigator component removed in favor of NavigationContainer Use react-navigation v5+ with NavigationContainer
Lifecycle Methods componentWillMount, componentWillReceiveProps deprecated Use componentDidMount, getDerivedStateFromProps
Build Process Changes in how native modules are linked or built Update react-native.config.js or use npx react-native link

Example: Migrating Navigation

// Before (v4)
import { StackNavigator } from 'react-navigation';

const AppNavigator = StackNavigator({
  Home: { screen: HomeScreen },
});

// After (v5)
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';

const Stack = createStackNavigator();

function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}
Note: Always check the official React Native release notes for breaking changes and migration guides.

5. Updating Dependencies

Example: Updating React Native and Core Dependencies

npm install react-native@latest
npm install @react-native-community/cli@latest
npm install @react-native-community/cli-platform-android@latest
npm install @react-native-community/cli-platform-ios@latest
Dependency Latest Version Notes
react-native 0.73.6 Core React Native library
@react-native-community/cli 14.0.0 Command-line interface
@react-native-community/cli-platform-android 14.0.0 Android platform support
@react-native-community/cli-platform-ios 14.0.0 iOS platform support
Note: Always check the React Native release notes for breaking changes before updating.
Warning: Updating dependencies may introduce breaking changes. Test thoroughly in a staging environment.

Update Process Summary

  • Backup your project before updating.
  • Update react-native and related CLI packages.
  • Run npx react-native config to regenerate configs.
  • Test on both platforms after update.

6. Migrating to New Architecture

Note: The New Architecture is a major update that requires careful migration planning. Ensure all dependencies are compatible before starting.
Step Description Action
1 Check compatibility of dependencies Review all third-party libraries for New Architecture support. Use react-native-architecture to verify.
2 Update React Native version Upgrade to React Native 0.72+ for full New Architecture support.
3 Enable New Architecture Add newArchEnabled: true to android/app/src/main/java/.../MainApplication.java and ios/Podfile.
4 Update native modules Modify native modules to use ReactNative APIs and Component instead of legacy methods.
5 Run migration tools Use npx react-native-gradle-plugin and npx react-native-config to update build configurations.

Example: Enabling New Architecture in Android

public class MainApplication extends Application implements ReactApplication {
  private final ReactNativeHost mReactNativeHost =
      new ReactNativeHost(this) {
        @Override
        public boolean getUseDeveloperSupport() {
          return BuildConfig.DEBUG;
        }

        @Override
        protected List<ReactPackage> getPackages() {
          return new PackageList(this).getPackages();
        }

        @Override
        protected String getJSMainModuleName() {
          return "index";
        }

        // Enable New Architecture
        @Override
        protected boolean isNewArchEnabled() {
          return true;
        }
      };
}

Example: Enabling New Architecture in iOS

# Podfile
platform :ios, '12.0'

target 'YourApp' do
  use_frameworks!
  use_modular_headers!

  # Enable New Architecture
  $ReactNativePath = '../node_modules/react-native'
  $ReactNativePath += '/packages/react-native/React'

  pod 'React', :path => $ReactNativePath
  pod 'React-Core', :path => $ReactNativePath
  pod 'React-bridging', :path => $ReactNativePath

  # Other pods...
end

Migration Checklist

Warning: Migrating to New Architecture may require significant changes in native modules and build configurations. Back up your project before starting.

7. Testing After Upgrade

Example: Running Tests After Upgrade

npm test
Test Type Description Command Notes
Unit Tests Test individual components or functions npm run test:unit Use Jest for unit testing
Integration Tests Test interactions between components npm run test:integration Ensure component behavior in context
E2E Tests End-to-end tests using Detox or Appium npm run test:e2e Simulate real user flows

Testing Best Practices After Upgrade

  • Run all test suites to ensure no regressions
  • Update test snapshots if needed
  • Verify UI components with visual regression tools
Warning: Ensure all dependencies are compatible with the new React Native version before running tests.

8. Rolling Back Upgrades

Steps to Rollback a React Native Upgrade

  1. Revert the version in package.json to the previous stable version
  2. Run npm install or yarn install to reinstall the old version
  3. Revert any code changes or configuration updates that were specific to the new version
  4. Update Podfile (iOS) or build.gradle (Android) if necessary to match the old version
  5. Reinstall dependencies using npx react-native run-ios or npx react-native run-android
Step Description Action Required
Revert package.json Change React Native version to previous stable release Manual
Reinstall dependencies Ensure all packages are compatible with the older version Manual
Update native configs Adjust iOS/Android build files if needed Manual
Rebuild project Run build commands to verify rollback success Manual
Note: Always backup your project before attempting a rollback.
Warning: Some third-party libraries may not support older versions of React Native. Ensure compatibility before rolling back.

9. Handling iOS Podfile Changes

Note: When upgrading React Native versions, iOS Podfile changes often require manual intervention to ensure compatibility with native dependencies.
Change Type Description Action Required
Podfile Platform Sets the minimum iOS version supported by the app. Update to 12.0 or higher depending on React Native version.
React Native Dependency Points to the React Native library in your project. Ensure it matches the version you're upgrading to (e.g., 12.0.0).
Podfile Plugins Includes third-party native modules (e.g., react-native-camera). Update to compatible versions or remove outdated entries.

Example: Updating Podfile Platform

# Before
platform :ios, '10.0'

# After
platform :ios, '12.0'

Example: Updating React Native Version in Podfile

# Before
pod 'React', :path => '../node_modules/react-native'

# After
pod 'React', :path => '../node_modules/react-native', :subspecs => ['Core']

Workflow: Resolving Podfile Conflicts

  1. Run cd ios && pod install --repo-update
  2. Check for any warnings or errors in the terminal output.
  3. Manually update conflicting dependencies if needed.
  4. Re-run pod install after changes.

Common Issues in iOS Podfile Updates

  • Pod version mismatch between React Native and native modules.
  • Missing or outdated platform declaration in Podfile.
  • Conflicting dependency versions (e.g., Flipper or Boost).

10. Updating Android Gradle

Note: Ensure you are using the latest stable version of React Native and Android Gradle Plugin (AGP) for optimal compatibility and security.
Property Value Description
android.gradlePluginVersion 8.0.2 Latest stable version as of 2026
android.minSdkVersion 21 Minimum SDK version supported
android.targetSdkVersion 33 Target SDK version for Android 13

Example: Updating Gradle Plugin in build.gradle

buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33
        ndkVersion = "25.1.8937393"
        kotlinVersion = "1.8.0"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.0.2")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
    }
}

Example: Updating Gradle Wrapper in gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

Steps to Update Android Gradle Plugin

  1. Update build.gradle with the new AGP version
  2. Update Gradle wrapper to match the required version
  3. Sync project with Gradle files
  4. Run npx react-native run-android to test

Was this article helpful?