We all know how painful react-native upgrades can be. At BAM, we made a handful of them. We have made some mistakes, and we’ve learnt our lessons from the past. So we’d like to share our guide and some advice to upgrade the react-native version of your app, for non-expo users.

‍

How can I upgrade my react-native app?

Before you begin

Two resources to check out before you begin your upgrade :

• First of all, make sure you’ve read the official documentation’s guide to react-native upgrades
• Also read the changelog of the versions you’re upgrading, with a careful attention to the breaking changes. For example, you may find in there that some components you were using are no longer available. And when you’ll be facing an error, you may remember something you read from the changelog that might be helpful.

‍

Steps to upgrade

Here are the steps to upgrade your app:

• First of all, apply all the necessary changes, either with the CLI, or by following the upgrade helper’s lead. I’ve never tried the CLI personally, so I can’t give a recommendation here.
• If you’re using TypeScript, you may need to upgrade react-native types as well. Until version 0.71, ++code>@types/react-native++/code> isn’t included in react-native. So you have to update it yourself to the last patch of the major of your update (for example: 0.68.9 for rn 0.68.x).
• Install your JS and native dependencies
• Run your tests: types, unit tests, end-to-end
• Build your app in debug mode, in your staging environment. Take a couple of minutes to go though the main features of your app, to make sure you don’t have any runtime error : on iOS and on Android.
• Build your app in release mode, in your staging environment : on iOS and on Android.
• If you have other environments (for production for exemple), make sure to test them as well
• Deploy in staging on your private store, then test on real device : on iOS and on Android
• Test your debugging tool (flipper/react-native debugger) : on iOS and on Android

‍

A few tips

Here are some advices and lessons we’ve learnt with the upgrades we’ve made over time.

Debuging

When facing an error, apart from googling it, these two resources can help you:

• the changelog
• a repo containing issues encountered during upgrades

‍

I need to upgrade several majors, which strategy should I adopt?

If you have several majors you planned on upgrading, our advice here is to upgrade each major one by one, and not all of them at one time.

Here are the reasons why:

• To be able to see your progress: you don’t want to spend two weeks on your branch upgrading for 5 majors without seeing the end of the tunnel.
• To let your team see your progress, and evaluate the remaining time: Splitting your task gives more visibility to the rest of the team, and especially to your project owner.
• When you get an error, it’s easier to target the scope of the change, and guess where it may come from:
• first of all, when you’re searching on the internet, you can add “upgrade rn + version”, to target answers better
• and secondly, the scope of the changes is smaller, both on the upgrade helper, and in the changelog
• To be able to stop between majors. If you’re running late on your upgrade (and upgrades are very hard to estimate), or if some big production bug pops in that is way more urgent, it’s great to be able to stop in a good environment. For example, imagine you’re upgrading from version 67 to 71, and you have to switch to another task on the 70th upgrade, you’ve already got 2 versions bump merged. And when you come back to your work two weeks later, you’re less likely to find a branch that has over 100 files changes. Way less overwhelming.

One of the reasons why I was skeptical of this method, is that I was scared to do some rework (building several times, over and over again), and that I would spend some time correcting an error that would be fixed in a later version anyway. But from our experience, that didn’t happen a lot.

‍

Do I really to apply all of those pbxproj changes?

Weeeell, it depends. There are two kinds of diffs in the .pbxproj:

• Some of the changes of the .pbxproj are automatic, like the following one:

This change is an index, changed by Xcode. Xcode will make those changes itself, as a consequence of other modifications. So this change shouldn’t be applied.

• But some other changes are properties that you need to change yourself! Like this script:

‍

So what do you need to change in the .pbxproj?

Our advice here is to go through all of the diffs in the react-native upgrade helper, and ask yourself wether the change is automatic or not. Apply them if they don’t seem to be automatic, like indexes. And once you’ve ran ++code>pod install++/code>, compare your diffs to the upgrade helper’s diffs, to make sure they’re all there.

‍

How should I change the .pbxproj?

In either case, never change the ++code>.pbxproj++/code> file directly!

Every change you make has to be made inside Xcode, in the corresponding section. For exemple, if you need to change the iPhone deployment target, you can go into the ++code>Build Settings++/code> section, inside your project and your targets settings.

‍

Estimations

The last subject we wanted to talk about is estimations. It is very hard to estimate a react-native upgrade, as the problems you’ll encounter and the changes you’ll need to make are directly related to your codebase.

But to have an idea of how much time a react-native upgrade may require, especially if you’ve never done any, we wanted to share the ones we use from our experience.

For each major from the version 0.65, we count between 1 and 2 man-day, except for the 0.68 that introduces the new architecture, for which we count between 3 and 4 man-day.

Keep in mind that this is very project-dependent. For example, you should increase these estimations if you’ve written some native code. Also, the bigger your codebase is, and the bigger your list of dependencies is, the bigger should your estimations be.

The main idea here is don’t underestimate, and give some visibility to your team and project managers that your estimations are not precise at all and this really may take longer.

‍

Conclusion

Thanks for reading this guide! We sincerely hope that this will help!

We’d love to know about your own experience with react-native upgrades. If we all agree on some steps to upgrade, we’d be happy to make a PR to add this information to the official documentation.

‍

‍