Upgrading React Native: The Good, the Bad and the Ugly

November 24, 2021

Ringo Wong

Why Upgrade?

It's more performant, some libraries are not backwards compatible, security, being able to leverage the newest tooling, language changes and adjusting your application to the changes in iOS and Android. These are all great reasons to upgrade, so why do developers avoid upgrading? Well, it's hard. Upgrading React Native is notoriously difficult and there are numerous data points online highlighting the nightmarish experience.

The first time I upgraded an application was when I joined a company with a dormant project on React Native 0.59. It was running but there were so many issues: numerous warning logs, new features were difficult to implement, community libraries stopped supporting this version of React Native and most of the application was held together by several patches to existing libraries. Stability and performance became major issues. Do yourself a favor and do not put yourself in this situation.

The longer an upgrade is put off, the greater the technical debt and headache. It’s not worth it; upgrading regularly will minimize the pain. A caveat to this, do not assume the latest is the greatest. Unless the release contains fixes to problems you need to correct for production, I would wait until the next major version is at least a few iterations in with bug fixes before upgrading. To do this, go to the GitHub repository and check the changelog: GitHub - React Native

How to Prepare for the Worst

Backup everything before you do anything. Programming is almost never as simple as it first appears, and the longer you hold off from updating, the more issues you’re likely to run into. When I first tried to upgrade my two-year-old project, I went straight to the React Native upgrade documentation online and excitedly ran the react-native upgrade command. I watched as thousands of changes are being made and when it finished, my project wouldn’t compile, then after hours of debugging, it finally compiled and built but the application only showed a black screen. Now I’m thousands of changes in and I’m blocked moving forward and reversing these changes was a challenge as well. Luckily, I pushed the latest build onto a cloud repository, so I was able to clone the project again and try again with a fresh start.

How to Upgrade

There are now tools to help us make the upgrade process easier. If your version of React Native is a few minor versions away from the latest then the first option should take care of your needs. For everything else, I strongly recommend using the react native upgrade helper to manually make the changes yourself. The reason for this is so that you understand exactly what has changed and where and it will help you learn more about the technology you’re using.

IMPORTANT:  While upgrading is great, it should be done carefully. Do not automatically select the latest major version. Always check the changelog and issues to be aware of any potential problems. For a production application, it’s generally better to wait for at least a few minor releases before upgrading.

1. npx react-native upgrade

The more regularly you update the higher the probability this will work, and you move on with your day. The upgrade command will use a git apply with a 3-way merge so you will need to take care of any merge conflicts that arise.

a.    To upgrade to the latest version: npx react-native upgrade

b.    For a specific version: npx react-native upgrade 0.67.0-rc.2

If this fails, try the second option below.

2.  React Native Upgrade Helper (Recommended)

This is a web tool that uses rn-diff-purge to check for differences between versions. You will need to manually make the changes and save them. It’s more work but at the same time the benefit of this method is that you will gain a better understanding of what changes are being made and being able to investigate specifics that don’t make sense. Github - Upgrade Helper (react native)


1. If you’re coming from a much older project, then try to upgrade the project one major version at a time if upgrading to the latest is failing

2. Changes in *.pbxproj are usually because different versions of XCode produce results that are ordered differently. So normally, you do not need to make changes to this file unless there is a comment next to it that looks like this:

After opening it, follow the instructions in the comment:

3. Create-react-native-app

If the above steps do not work, then you can also create a new React Native project and copy the project files over. This method usually works when the options above fail. You will need to set up two separate environments, one that is upgrading and your old codebase. The actual upgrade step will be done in two steps, the first one by creating a fresh React Native project at the latest or preferred version and the second step will move project files over incrementally and continually checking to ensure the application is working. This way, it is easier to identify where the problems are and correct them as they come up. It can be tough to stay sane while doing this but it’s a necessary evil.


That's it! Just run npm install or yarn to update React Native. The next step now is to go through each dependency and update them to the appropriate version as well. Hopefully, this article has helped clear up some doubts and if you have decided to take the plunge to upgrade then my hope is that you have found this article helpful.



Latest Posts

Be the first to know whats new at RedBit and in the industry. Plus zero spam.

Thank you! An email has been sent to confirm your subscription.
Oops! Something went wrong while submitting the form.

Let's Make Something Great Together

Contact Us