Upgrading React Native Without Breaking Everything

Every React Native team has a story about the upgrade that ate two weeks: a library that stopped compiling, an Xcode error nobody could read, a layout that broke only on one Android version. Those stories usually have the same cause: too many versions at once, too long after the last upgrade.

Upgrades are much less painful when they're small and regular. This guide covers how often to upgrade, how to do it one step at a time (for bare projects and for Expo), how to handle dependencies, and how to test and release so an upgrade never surprises your users.

Key takeaways

• Upgrade one minor version at a time, keeping the app releasable after each step.
• Use the React Native Upgrade Helper to see exactly which native files changed between versions (bare projects).
• In Expo, upgrade one SDK at a time with npx expo install expo@^SDK and npx expo install --fix, then follow the SDK's changelog and codemods.
• Upgrade or replace native dependencies first, especially unmaintained ones.
• Release upgrades like features: test release builds on real devices, then roll out gradually with crash reporting watching.

Which versions are current?

Expo apps follow the SDK rather than React Native directly: each SDK pins a tested React Native version, and you move both together. Check the React Native releases page and Expo's changelog before planning, because both ship new versions every few months.

How often should you upgrade?

React Native ships new minor versions roughly every couple of months, and only recent versions receive fixes. Expo releases around three SDKs a year, each pinned to a React Native version. A practical cadence:

• Expo apps: move to each new SDK within a month or two of release, once key libraries support it.
• Bare apps: stay within a couple of minor versions of the latest.
• Always: don't fall behind the store requirements, such as Google Play's yearly target API level, which often forces an upgrade on its own timetable.

Small, regular upgrades are cheaper than rare, giant ones, because each step has few changes and clear causes when something breaks.

The process for bare React Native projects

1. Read the release notes for the next version, especially breaking changes.
2. Open the Upgrade Helper with your current and target versions. It shows a diff of every template file that changed: package.json, Gradle files, Podfile, AppDelegate, MainApplication and more.
3. Apply the diff by hand, file by file. Don't copy whole files over your customised ones.
4. Update native dependencies to versions that support the new React Native version.
5. Clean and rebuild: clear Metro's cache, delete Pods and reinstall, and clean the Gradle build.
6. Fix compile errors, then runtime issues, then warnings.
7. Repeat for the next version once this one is tested and released.

The process for Expo projects

1. Read the SDK changelog and its breaking changes.
2. Upgrade the SDK: npx expo install expo@^57.0.0 (for example), then npx expo install --fix to align every Expo package and known library version.
3. Run the codemods listed in the changelog, such as SDK 56's codemod for moving expo-router code off direct React Navigation imports.
4. Run npx expo-doctor to catch dependency and configuration problems.
5. Regenerate native projects if you use Continuous Native Generation, and rebuild development and preview builds with EAS.
6. Test, release, then move to the next SDK.

Dependencies: the real work

Most upgrade pain comes from third-party native libraries, not React Native itself:

The React Native Directory shows maintenance status and New Architecture support for many libraries, which makes this audit much faster.

From the field: I've migrated eight apps to the New Architecture, which is the biggest upgrade React Native has had in years. The habits that make it manageable are the ones in this article: audit dependencies first, move one version at a time, and release each step before taking the next.

Testing an upgrade

• Build release versions for both platforms, not just debug builds.
• Test every critical flow: sign-in, payments, push notifications, deep links, camera and any hardware features.
• Check performance: startup time and scrolling on a mid-range Android phone, compared with the previous version.
• Run automated end-to-end tests if you have them; upgrades are where they pay for themselves.

Making upgrades routine

The teams that never dread upgrades treat them as maintenance, not projects:

• Put upgrades on the calendar, for example in the first sprint after each Expo SDK release.
• Keep a short upgrade log in the repository: which version, what broke, how it was fixed. The next upgrade often hits the same libraries.
• Watch your dependency list. Every new native library is a future upgrade cost, so add them deliberately.
• Automate the boring checks: CI that builds both platforms in release mode on every pull request catches most upgrade regressions within minutes.

Releasing an upgrade

Ship upgraded versions with a phased release on iOS and a staged rollout on Android, and compare crash-free sessions with the previous version before widening. Remember that over-the-air updates published for the old version won't run on the new one if the native runtime changed, so plan your update channels and runtime versions around the release.

FAQ

How do I upgrade React Native to the latest version?

Upgrade one minor version at a time. For bare projects, use the Upgrade Helper to apply native file changes, update native dependencies, clean and rebuild, then test. For Expo projects, upgrade one SDK at a time with npx expo install, run the listed codemods, and rebuild.

What is the React Native Upgrade Helper?

It's a web tool from the React Native community that shows the differences in the default project template between any two React Native versions. You apply those changes to your own project's native files, which is far safer than copying files over.

How long does an upgrade take?

One minor version on a well-maintained app often takes a day or two including testing. Upgrades spanning several versions, or involving unmaintained native libraries and custom native code, can take weeks, which is why regular small upgrades are cheaper.

Should I upgrade React Native or Expo first?

In an Expo project, upgrade the Expo SDK, which brings the matching React Native version with it. Don't upgrade React Native independently of the SDK, because Expo's packages are tested against a specific React Native version.

Next steps

If your app is several versions behind and every upgrade feels risky, I can plan and run the upgrades in safe steps, or take them on as part of a maintenance retainer. Get in touch, or see my services.

Sources

• Upgrading to new versions, React Native docs
• React Native Upgrade Helper, React Native Community
• Upgrading Expo SDK, Expo
• React Native Directory, React Native Directory
• React Native versions, React Native