Being stuck on an old React Native version makes every small change feel like it might break the build, and that fear is usually justified. The safest way to upgrade old React Native app code is one minor version at a time, after you have a green build, a short smoke test and control of every account. This post shows how to check where you stand in under an hour. It also covers what usually causes the mess and when a rebuild beats a fix.

Diagnose it yourself in under an hour

You need a clean clone of the repo, current Xcode and Android Studio, and about 60 minutes. Work through these checks in order. Write down what you see, because the notes become your upgrade plan.

1. Find your exact versions (5 minutes)

Run npx react-native info in the project root. It prints React Native, React, Node, Xcode, Java and Gradle versions in one place.

  • Good: within two or three minor versions of the latest release.
  • Bad: below 0.70. That means you predate Hermes as the default engine, the Java 17 requirement from 0.73 and the New Architecture default from 0.76.

2. Try a clean build (20 minutes)

Delete node_modules, ios/Pods and android/build. Then run npm ci and pod install, and build both platforms from scratch.

  • Good: both platforms build with warnings only.
  • Bad: Gradle or Xcode errors appear before your own code compiles. That is toolchain drift, and it is fixable.

3. Audit native dependencies (15 minutes)

Run npm outdated. Then look up every package with native code on React Native Directory, which shows the last release date and New Architecture support.

  • Good: fewer than five native packages without a release in the past year.
  • Bad: archived libraries, or a patches folder full of patch-package diffs nobody can explain.

4. Check store deadlines (10 minutes)

Google Play requires apps to target a recent Android API level, roughly within a year of each major release. Its target API level requirements list the current dates. Apple publishes its minimum Xcode and SDK rules on its upcoming requirements page.

  • Good: no warnings in Play Console or App Store Connect.
  • Bad: a warning with a date on it. After that date, your updates are blocked.

5. Check tests and CI (10 minutes)

  • Good: CI builds both platforms on every pull request, with at least a few tests on critical flows.
  • Bad: the app only builds on one person's laptop.

If you would rather have a second pair of eyes, a free code or performance audit tells you which of these checks your app fails and roughly what each fix costs.

The five usual causes, most common first

In our rescue work, this order holds for most apps. Your mix will differ, but start at the top.

  1. Abandoned native libraries. A camera, maps or payments package stopped at an old version and blocks everything above it. Each one needs a replacement or a fork.
  2. Toolchain drift. The project expects Java 11, Gradle 6 or an Xcode that no longer runs on current macOS. Nothing is wrong with your code, but nothing builds.
  3. Store pressure. A target SDK or Xcode deadline forces an upgrade the team kept postponing. Now it has a hard date.
  4. Silent patches. Someone edited node_modules or added patch-package fixes. Every upgrade wipes or conflicts with them.
  5. No safety net. Without tests or CI, nobody knows whether a change broke checkout until users report it.

How to upgrade old React Native app code without breaking it

The official React Native upgrading guide points to the Upgrade Helper. The helper shows the exact template diff between any two versions. Use it, but use it in small steps.

  1. Freeze features. Run upgrade work on its own branch, and keep feature work small for the duration.
  2. Pin the toolchain. Commit an .nvmrc file, the Gradle wrapper version and the Ruby and CocoaPods versions. A new laptop should then build the same way.
  3. Write a smoke test. Cover 10 to 15 critical flows, such as login, purchase and push opt-in. Maestro or Detox both work.
  4. Replace dead dependencies first. Swap each abandoned library on your current version, ship it, then move on.
  5. One minor version per pull request. Apply the Upgrade Helper diff, build both platforms, run the smoke test and release to internal testers.
  6. Enable the New Architecture last. Turn it on only once every native dependency supports it.

Each minor step typically takes one to three days for a mid-sized app with few native packages. Heavily patched apps can take a week or more per step. If you use Expo, move one SDK at a time and run npx expo install --fix after each bump.

Fix or rebuild: how to tell

A rebuild typically costs several times more than a stepwise upgrade. It also freezes features for months. We only recommend one when most of these conditions are true.

It is a fix when

  • The app builds, or builds after toolchain changes.
  • Most native libraries have maintained replacements.
  • Business logic is separated from screens, even loosely.
  • The product still matches what users need.

It is a rebuild when

  • Core features depend on custom native modules nobody understands.
  • State and API calls are tangled through every screen.
  • The product itself is changing, so you would rewrite most screens anyway.
  • The version gap is so wide that a stepwise path means 15 or more risky steps.

Protect yourself if the agency relationship is failing

Do this before you raise the problem, not after. Access is much harder to get once a relationship turns hostile. This is practical advice, not legal advice, so involve your lawyer on contract terms.

Technical access

  • Repository: admin rights on GitHub, GitLab or Bitbucket, in an organisation your company owns.
  • Apple Developer account: your company should be the Account Holder, not a team member.
  • Google Play Console: owner access. Confirm Play App Signing is on and that you hold the upload keystore and its passwords.
  • Services: Firebase, Sentry, CI, push providers, cloud hosting and the domains used for deep links.

Contract terms

  • IP assignment: code ownership transfers to you on payment, not on project completion.
  • Handover clause: a defined handover period on termination, typically 10 to 15 business days.
  • Documentation as a deliverable: a README that builds the app from scratch, a list of environment variables and written release steps.

What the first week of a rescue looks like

We write no feature code in week one, and usually no upgrade commits either. The goal is a plan you can trust.

  • Day 1: collect access and inventory every account, key and service.
  • Day 2: get a clean build on a fresh machine and reproduce the last store release.
  • Day 3: audit dependencies and patches, then rank the risks.
  • Day 4: add CI for both platforms and the first smoke tests.
  • Day 5: deliver a written plan with the version path, estimates per step and a clear fix-or-rebuild call.

FAQ

Can I skip versions when upgrading React Native?

You can, but it multiplies risk. Each minor version can change templates, build tools and library requirements. Jumping several at once makes failures hard to trace, so step through each minor unless the app is very small.

How long does it take to upgrade an old React Native app?

For a mid-sized app with few native dependencies, each minor version typically takes one to three days. A two-year gap with abandoned libraries often runs four to ten weeks in total. The dependency audit gives you the real number.

Do I have to adopt the New Architecture?

It has been the default since React Native 0.76, and recent releases are dropping the legacy architecture. Plan for it, but turn it on last. Wait until every native library you use supports it.