Skip to main content

React Native Upgrade Guide: Fixing Breaking Changes and Dependency Issues

· 6 min read
Michael
Mobile Developer
Last updated on May 18, 2026

React Native upgrade guide

React Native upgrades are safest when you treat them as a controlled migration, not a package bump. The work spans JavaScript dependencies, native iOS and Android project files, Expo modules, build tooling, runtime versions, and QA. This guide gives you an evergreen upgrade path that works for bare React Native apps, Expo apps, and production templates.

Quick Answer​

Upgrade React Native in small steps. Start from a clean Git branch, read the React Native and Expo upgrade notes, apply the React Native Upgrade Helper diff or Expo SDK walkthrough, update dependencies through the project's package manager, rebuild iOS and Android from clean native state, and run typecheck, tests, device smoke tests, and release builds before shipping. Do not publish OTA updates across incompatible native runtime changes.

If you are using an Instamobile template, pair this guide with the current React Native stack, the getting started guide, and the release checklist.

1. Prepare a Clean Upgrade Branch​

Before changing packages, create a branch where the current app already builds.

git status --short
git checkout -b upgrade/react-native
corepack yarn install --immutable
corepack yarn typecheck

Record the current state:

  • React Native, React, Expo, TypeScript, and navigation versions
  • Node and package manager versions
  • iOS deployment target and Xcode compatibility
  • Android Gradle Plugin, Gradle, compile SDK, and min SDK
  • Firebase, payments, push, maps, media, and any custom native modules

If baseline typecheck or builds already fail, fix that first. Upgrades become much harder when you cannot separate old breakage from new breakage.

2. Choose the Right Upgrade Path​

Use the path that matches your project:

Avoid jumping multiple major SDK or React Native releases unless you have a strong test suite and a migration branch dedicated to dependency cleanup.

Mega Bundle Sale is ON! Get ALL of our React Native codebases at 90% OFF discount 🔥

Get the Mega Bundle

3. Update Dependencies Deliberately​

Do not accept every latest package version at once. Move the core stack first, then align native packages that are tightly coupled to it.

corepack yarn up react react-native expo
corepack yarn install
corepack yarn why react

For Expo apps, prefer Expo-aware installs for packages managed by Expo:

corepack yarn expo install --fix

Then inspect the diff:

git diff package.json yarn.lock

Pay close attention to:

  • react, react-native, and expo
  • react-native-reanimated, gesture handler, screens, safe area, and navigation packages
  • Firebase, Stripe, maps, video, camera, image picker, notifications, and IAP packages
  • TypeScript, ESLint, Jest, Metro, Babel, and React Native config packages

If a package requires native changes, plan a binary rebuild. Do not assume an OTA update is enough.

4. Reconcile Native iOS and Android Diffs​

Most painful upgrade bugs live in native files. Compare generated changes carefully instead of copying snippets blindly.

For iOS, inspect:

  • ios/Podfile
  • deployment target
  • CocoaPods install output
  • app delegate changes
  • permissions and Info.plist entries
  • custom native modules and config plugins

For Android, inspect:

  • root Gradle files
  • android/app/build.gradle
  • settings.gradle
  • Kotlin and Java source changes
  • AndroidManifest permissions and queries
  • R8/resource shrinking rules
  • build variants and signing config

After native changes:

cd ios && bundle exec pod install
cd ..
corepack yarn android
corepack yarn ios

Use the commands that match your project. If your app does not use Bundler, run the repo's documented CocoaPods command instead.

5. Fix Breaking Changes by Surface Area​

Work from compile errors to runtime behavior:

  1. TypeScript errors
  2. Metro and Babel errors
  3. Native build errors
  4. startup crashes
  5. navigation and screen rendering
  6. auth, chat, media, maps, payments, push, and backend flows

Keep each fix small and committed. When an upgrade fails, small commits let you isolate whether the problem came from dependencies, native config, or application code.

Common fixes include:

  • replacing removed APIs;
  • updating config plugin options;
  • adjusting permission declarations;
  • regenerating pods after native dependency changes;
  • removing duplicate React versions;
  • aligning peer dependencies;
  • fixing packages that are not ready for the New Architecture.

6. Treat OTA Updates Carefully​

Expo Updates and other OTA systems are useful, but native runtime compatibility matters. If an upgrade changes native modules, React Native, Expo SDK, Hermes behavior, permissions, or build-time config, ship a new binary and set the runtime version deliberately.

Use OTA updates for compatible JavaScript and asset fixes after you know the installed native runtime can execute them.

7. Validate Like a Release​

Before merging the upgrade:

corepack yarn typecheck
corepack yarn test
corepack yarn expo-doctor

Then run device checks:

  • clean install on iOS and Android;
  • login and logout;
  • onboarding and navigation;
  • feed/list scrolling;
  • image/video upload where enabled;
  • chat or realtime updates where enabled;
  • push notification registration;
  • payments in test mode where enabled;
  • release build startup;
  • store submission metadata if the binary will ship.

Use the Instamobile release checklist as the final gate.

FAQ​

Should I upgrade Expo and React Native separately?​

For Expo-managed apps, upgrade through the Expo SDK path because Expo pins a compatible React Native version and package set. For bare apps, follow the React Native Upgrade Helper and then update compatible community packages.

Should I delete native folders and regenerate them?​

Only if your project is designed around prebuild and you understand which native customizations must be reapplied. Production apps often contain signing, permissions, Firebase, payments, and native module changes that should be reconciled carefully.

What is the safest rollback plan?​

Keep the previous production branch and binary available. If the issue is JavaScript-only and runtime-compatible, publish an OTA rollback. If native code is affected, ship a reverted binary.

Looking for a custom mobile application?

Our team of expert mobile developers can help you build a custom mobile app that meets your specific needs.

Get in Touch