Announcing Reanimated 3

Today we are happy to announce the new major release of the popular Reanimated library — version 3.0. Before you get scared about having to rewrite all your Reanimated code, we want to emphasize that this version does not bring a lot of changes API-wise, at least not ones that we believe are going to be significant to the way most people use Reanimated nowadays. Reanimated 3 will be the first version of the library that supports the new React Native architecture — Fabric. We are very excited about the future adoption of Fabric and we think that it is also the future of Reanimated. However, Fabric support in Reanimated also means more challenges for us maintaining versions that can be compatible with both old and new architectures. For this reason we decided to phase out some of the legacy stuff that we maintained as part of Reanimated 2. In this blog post we list all the differences and provide guidance on who, how, and when should upgrade to Reanimated 3.

How is it different from Reanimated 2?

To make things super clear below we list three differences between Reanimated 2 and Reanimated 3. Some of the points cover a number of things but the below list is exhaustive and really has everything that we’ve changed.

1. Reanimated 3 will no longer include support for legacy Reanimated 1 API. This may be the most critical change for some. As we don’t expect a lot of people to be writing or maintaining code written using the old Reanimated 1 API, we know that there still are libraries that use it. When we announced Reanimated 2 we decided for it to include implementation of the previous version for compatibility purposes. This allowed everyone to upgrade to 2.0 without a need of rewriting everything and to only upgrade incrementally. With version 3.0 that old implementation and old API will no longer be available. We provide more details about the reasoning and how we plan to mitigate the problem caused by this decision.
2. Reanimated 3 will no longer ship with pre-built binaries for Android. This means that when building your app for Android, Reanimated 3’s C++ code will need to be compiled from source. This matches the build behavior on iOS where all the Reanimated code has always been compiled from sources. However, on Android this may require some additional setup when upgrading (see more details later on).
3. Finally some good news: Reanimated 3 will support the new Fabric architecture while also being compatible with the old architecture. This will make it possible for most of the people to upgrade today even if they can’t yet use Fabric, and only experiment with the new architecture in the future without caring about the version of Reanimated they have installed. Note, however, that in the first RC release the Layout Animation feature is not yet available for Fabric implementation. If you want to try Reanimated with Fabric, you will need to use React Native 0.69 (note that you can still use Reanimated 3.0 with older React Native versions so long you don’t want to run it with Fabric).

Who and when should upgrade?

If your app including its dependencies doesn’t use Reanimated 1 API, we recommend that you upgrade at your earliest convenience. For your use case, version 3.0 does not introduce any changes compared to the latest 2.x release, but upgrading now will make it easier to bump to future 3.x updates easier, while also allowing you to try the new React Native architecture at some point.

If you still rely on code that uses Reanimated 1 API, we recommend looking into either replacing the dependencies that use it, upgrading its versions, or planning to refactor the code to the new API. We are sure you’ll be satisfied with such migration, and it will make your codebase more readable. In any case, we still plan to publish 2.x updates along with new 3.x releases and we commit to do so for at least a couple more versions, so there is no reason to feel abandoned. We wanted to highlight, however, that the old API won’t be supported on Fabric, as the amount of code necessary to be ported is just too much to be justified.

How to upgrade?

If you can (see section above) upgrade, here is what you need to do:

1. Bump the package version e.g. with yarn do: yarn upgrade react-native-reanimated@next
2. In order to build your app for Android, you will have to install and configure NDK. It is likely that you already have the NDK installed as it is required by other community packages, but in case you don’t, please follow the instructions from Android developers portal. Note that more and more community packages and react-native core itself migrates towards building C++ code for Android from source, so installing NDK is going to become a prerequisite for all react-native developers very soon.
3. If you’d like to try running Reanimated on the new Fabric architecture, make sure that you are using at least version 0.69 of React Native, and follow steps to opt into the new architecture as documented on the React Native blog.

What if I can’t upgrade?

As mentioned in the previous section, we plan to maintain the 2.x branch and merge all the changes there (except for ones that are specific to Fabric), as well as publish updates on a regular basis. We plan to do so for at least the next couple of releases, and we will definitely communicate the plans regarding it as we move forward. Nevertheless, we recommend moving away from Reanimated 1 API, as even though the supporting implementation has been kept in 2.x releases since the beginning, it has not received any updates in a long time.

Reanimated is joining the Fabric club

With this release, Reanimated is another library by our Open Source team at Software Mansion that supports the new React Native architecture. We want to thank Shopify for their support in the process of porting the libraries. We are sure that this work will help accelerate the migration to Fabric for everyone, as Reanimated, Gesture Handler, and Screens libraries are among the ones that are most frequently installed. But, we also hope for the libraries’ codebase to serve as an example of third-party code that works with both React Native architectures and hence help other community library authors to work porting their codebases. Finally, we want to thank the React Native core team for their help in adding some important patches to version 0.69 that made this integration possible.