id | title | sidebar_label |
---|---|---|
installation |
Installation |
Installation |
Reanimated 2 is primarily built in C++ using Turbo Modules infrastructure which is not yet completely deployed in React Native (specifically on Android).
Because of that the installation of new Reanimated requires additional steps apart from just adding a dependency to package.json
.
As a consequence of the above the minimum supported version of React Native is v0.62. Before you continue with the installation, make sure that you are running the supported version of React Native.
Please follow the below instructions for Android and iOS.
We realize the project setup is very complex and you may not want to add that to your existing app rightaway. If you just want to play with Reanimated 2, we made a clean repo that has all the steps configured so that you can pull it from github and give the new version a shot.
Visit the Playground repo here or copy the command below to do a git clone:
git clone git@github.com:software-mansion-labs/reanimated-2-playground.git
Continue with the instruction below if you'd like to install Reanimated v2 on an existing or new React Native project.
:::caution
Please note that Reanimated 2 doesn't support remote debugging, only Flipper can be used for debugging.
:::
First step is to install react-native-reanimated
alpha as a dependency in your project:
yarn add react-native-reanimated
To use experimental support of Reanimated 2 in the Expo managed apps follow their installation instructions.
To use Reanimated 2 built from the main branch:
- go to the "Build npm package" workflow in Reanimated repository
- select latest build and download
react-native-reanimated-2.0.0-alpha.tgz
artifact - run
tar zxvf react-native-reanimated-2.0.0-alpha.tgz.zip
to unpack zip (or unpack it manually) - run
yarn add file:react-native-reanimated-2.0.0-*.tgz
to install the package - run
cd android && ./gradlew clean
Add Reanimated's Babel plugin to your babel.config.js
:
module.exports = {
presets: [
...
],
plugins: [
...
'react-native-reanimated/plugin',
],
};
:::caution
Reanimated plugin has to be listed last.
:::
:::info
After adding the react-native-reanimated/plugin
to your project you may encounter a false-positive "Reanimated 2 failed to create a worklet" error. In most cases, this can be fixed by cleaning the application's cache. Depending on your workflow or favourite package manager that could be done by:
yarn start --reset-cache
npm start -- --reset-cache
expo start -c
or other.
:::
- Turn on Hermes engine by editing
android/app/build.gradle
project.ext.react = [
enableHermes: true // <- here | clean and rebuild if changing
]
- Plug Reanimated in
MainApplication.java
import com.facebook.react.bridge.JSIModulePackage; // <- add
import com.swmansion.reanimated.ReanimatedJSIModulePackage; // <- add
...
private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
...
@Override
protected String getJSMainModuleName() {
return "index";
}
@Override
protected JSIModulePackage getJSIModulePackage() {
return new ReanimatedJSIModulePackage(); // <- add
}
};
...
:::info
In previous releases, we required an additional step which is turning on Turbo Modules. If you are upgrading from alpha.{ <=3 } please remove the following lines:
static {
ReactFeatureFlags.useTurboModules = true;
}
from MainActivity.java
.
:::
You can refer to this diff that presents the set of the above changes made to a fresh react native project in our Playground repo.
If you're using Proguard, make sure to add rule preventing it from optimizing Turbomodule classes:
-keep class com.facebook.react.turbomodule.** { *; }
Run pod install
in the ios/
directory.
:::info
In previous releases, the installation process was manual and required turning turbo modules on. Some libraries break when turbo modules are enabled so we decided to change our approach and we no longer use the standard way for registering a turbo module. It let us simplify the installation process and as a result, you can safely undo all installation steps from the previous instruction.
:::
:::tip
If you want to turn off autoinstall on iOS please add the following compilation flag:
DONT_AUTOINSTALL_REANIMATED
.
It can be done by pasting:
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['OTHER_CPLUSPLUSFLAGS'] = '-DDONT_AUTOINSTALL_REANIMATED'
end
end
end
to your Podfile
. Don't forget to run pod install
after doing that.
:::