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
| 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-nativeversion inpackage.json - Run
npm installoryarn 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.,
Navigatorremoved in favor ofNavigationContainer) - Updates to component lifecycle methods (e.g.,
componentWillMountdeprecated) - Changes in how navigation is handled (e.g.,
react-navigationv5+) - 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-nativeand related CLI packages. - Run
npx react-native configto 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
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
| 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
- Revert the version in
package.jsonto the previous stable version - Run
npm installoryarn installto reinstall the old version - Revert any code changes or configuration updates that were specific to the new version
- Update
Podfile(iOS) orbuild.gradle(Android) if necessary to match the old version - Reinstall dependencies using
npx react-native run-iosornpx 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 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
- Run
cd ios && pod install --repo-update - Check for any warnings or errors in the terminal output.
- Manually update conflicting dependencies if needed.
- Re-run
pod installafter changes.
Common Issues in iOS Podfile Updates
- Pod version mismatch between React Native and native modules.
- Missing or outdated
platformdeclaration in Podfile. - Conflicting dependency versions (e.g.,
FlipperorBoost).
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")
}
}