Chapter 8: Installing lottie-react-native

Before using lottie-react-native, we need to install the library into our React Native project as a node module so we can import it inside the code base of our app. To perform this installation, we have two different options:

• npm
• Yarn

Both tools will result in the same output (lottie-react-native) and its dependencies will be installed inside the node_modules folder inside our React Native project folder. Using one tool or another will be up to each developer and should not influence the resulting product in any way.

The topics we will cover in this chapter are as follows:

• Basic installation (using npm or Yarn)
• Dependencies of lottie-react-native
• iOS requirements when installing lottie-react-native
• Android requirements
• Installing previous versions of lottie-react-native

Basic installation

Installing lottie-react-native follows a similar process as any other npm library, taking into account that it's a library that depends on native libraries written in Swift and Java. Taking this into account, developers can always read about the installation process in the GitHub repository URL: https://github.com/lottie-react-native/lottie-react-native.

When installing lottie-react-native, developers should know that, because of the way it is built, the iOS native library for Lottie should also be installed to enable lottie-react-native to render Lottie animations in iOS apps.

Let's take a look at the steps we need to follow in order to complete a successful installation.

Using npm

Follow these steps to install the lottie-react-native library using npm:

1. Navigate to our terminal in the React Native project root folder. Once we are there, we should run the following command:

   npm i --save lottie-react-native

This command will follow four different steps:

1. Download the source files for the library from the npm repository.
2. Create the container folder inside the node_modules folder.
3. Install the source files in the created container folder.
4. Update the package.json and package.json.lock files to mark the library as a dependency of the React Native project.

npm detects and installs the latest version of the library from the npm public repository, but we could force a specific version of the library by specifying it after an @ sign followed by the version number we would like to install.

2. Once npm is finished installing the library, we need to install its iOS dependency if we are going to require our Lottie animations to be rendered on iOS devices:

   npm i --save [email protected]

Running this command will trigger the installation of lottie-ios on a very specific version, 3.2.3, which is the compatible version for lottie-react-native to work properly on iOS devices.

3. Once npm finishes installing lottie-ios, we need to install its pod dependencies. We will do so by going into the ios folder inside our React Native project and running the following:

   pod install

This action will trigger CocoaPods, a dependency management tool for iOS and macOS projects that will download and install all the dependencies required by lottie-ios to function.

Once all these dependencies are installed, we can start using the lottie-react-native library inside our React Native app.

Using Yarn

Using Yarn for installing lottie-react-native is similar to using npm.

Let's see how to do so:

1. Navigate from our terminal into our React Native project root folder. Once in that folder, we will run the following command:

   yarn add lottie-react-native

This command will follow four different steps:

• Download the source files for the library from the npm public repository.
• Create the container folder inside the node_modules folder.
• Install the source files in the created container folder.
• Update the package.json and yarn.lock files to mark the library as a dependency of the React Native project.

Yarn always looks for the latest version of the library in the npm public repository, but we could force a specific version of the library by specifying it after an @ sign followed by the version number we would like to install.

2. Once Yarn has finished installing the library, we need to install its iOS dependency if we are going to need our Lottie animations to be rendered on iOS devices. We can install it by running the following command in our project's root folder:

   yarn add [email protected]

Running this command will install lottie-ios on its version number 3.2.3, which is the compatible version for lottie-react-native to work properly on iOS devices.

3. Once Yarn finishes installing lottie-ios, we need to install its pod dependencies. We will do so by going into the ios folder inside our React Native project and running the following:

   pod install

This action will trigger CocoaPods, a dependency management tool for iOS and macOS projects that will download and install all the dependencies required by lottie-ios to function.

Once all these dependencies are installed, we can start using the lottie-react-native library inside our React Native app. This library depends on other packages in order to deploy all its functionality. Let's take a look now at these packages.

Other dependencies of lottie-react-native

As with many other libraries, lottie-react-native depends on a number of libraries that will be automatically installed when running npm or Yarn installations, as we did in the previous section of this chapter. The full list of dependencies is as follows:

"peerDependencies": {

    "lottie-ios": "^3.2.3",

    "react": "*",

    "react-native": "|=0.46"

  },

  "dependencies": {

    "invariant": "^2.2.2",

    "prop-types": "^15.5.10",

    "react-native-safe-modules": "^1.0.3"

  }

As we can see, lottie-react-native needs to run on a project that contains at least three dependent libraries: lottie-ios (which should be installed using npm or Yarn, as we saw in the previous section of this chapter), react, and react-native (version 0.46 or higher).

On top of those peer dependencies, lottie-react-native also requires three regular dependencies: invariant, prop-types, and react-native-safe-modules. All of them will be installed automatically by npm or Yarn so developers do not need to take any manual action to install them.

Let's take a look now at the platform-specific requirements that lottie-react-native has.

Installation requirements

Both platforms have specific requirements for lottie-react-native to be installed properly. Let's take a look now at what those differences are and how we can complete the installation in iOS and Android.

iOS devices

For its iOS version, lottie-react-native depends on lottie-ios, which is a library built by Airbnb in Swift. This means we need to enable our React Native app to read and execute Swift code. In order to do so, we need to create a bridging header (if we haven't done it yet) so the Objective-C part of our app can communicate with the Swift part and therefore, send and receive messages to lottie-ios.

If we don't have a bridging header in our project, we can create one by following these steps:

1. Open your <project_name|/ios/<project_name|.xcworkspace file in Xcode and go to File | New | File…:

Figure 8.1 – Creating a new file in your Xcode project

2. Select Swift File as the file type:

Figure 8.2 – Selecting Swift as file type

3. Confirm the creation of a bridging header:

Figure 8.3 – Confirming creation of bridging header

Upon finishing these steps, our app should be ready to start using lottie-react-native on any iOS and macOS device. Let's now prepare our app to run lottie-react-native on Android devices.

Android devices

On some rare occasions, auto-linking may not work properly when installing lottie-react-native on Android devices. This will result in the app crashing when trying to build it. In this case, you would need to follow these steps to fix the issue:

1. Make the following changes in android/app/src/main/java/<project_name|/MainApplication.java:
   1. Add import com.airbnb.android.react.lottie.LottiePackage; in the import section.
   2. Add packages.add(new LottiePackage()); in List<ReactPackage| getPackages();.
2. Make the following change in android/app/build.gradle:
   1. Add implementation project(':lottie-react-native') in the dependencies block.
3. Add the following lines in android/settings.gradle:

   include ':lottie-react-native'

   project(':lottie-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/lottie-react-native/src/android')

When all these changes are done, rebuild the app for Android devices and check whether the crash is fixed. As we have our installation finished, let's move on now to see the limitations and possibilities of using the most well-known Lottie features.

Limited features of the lottie-react-native library

Not all Adobe After Effects (AE) features are supported by lottie-react-native. In fact, Airbnb maintains a list of non-supported features on their website: https://github.com/airbnb/lottie/blob/master/supported-features.md.

The support list for the most common features at the time of writing is as follows:

• Lottie support for basic geometric shapes in AE:

Figure 8.4 – Support for shapes features

• Lottie support for basic text effects and formats in AE:

Figure 8.5 – Support for text features

• Lottie support for masking effects in AE:

Figure 8.6 – Support for masks features

• Lottie support for layer effects in AE:

Figure 8.7 – Support for layer effects features

• Lottie support for shapes and graphics-driven transparencies in AE:

Figure 8.8 – Support for mattes features

• Lottie support for shape combination techniques in AE:

Figure 8.9 – Support for merge paths features

• Lottie support for other effects in AE:

Figure 8.10 – Support for other features

Let's now learn how to deal with previous versions of lottie-react-native in cases when our version of React Native requires a version other than the latest.

Installing previous versions

Depending on which version of React Native we are building our project with, we will need to install a specific version or range of versions. The list of versions to be installed can be found in the previous chapter, so now we are going to learn how to install one of those specific versions:

1. Identify which React Native version our project is using. For this, we can check our package.json file at the root of our React Native app project. Inside this file, look for the react-native dependency and note down the version number:

Figure 8.11 – Finding out your project's React Native version

2. Look at the lottie-react-native/react-native compatibility list in the previous chapter and select the right lottie-react-native for your project.
3. Install the selected version of lottie-react-native using npm or Yarn by specifying that version number after an @ sign, for example, npm install –save [email protected] or yarn add [email protected].
4. As we saw in the previous section, we need to install lottie-ios as a dependency; the lottie-react-native/lottie-ios compatibility list can be also found in the previous chapter.
5. Install the selected version of lottie-ios using npm or Yarn by specifying that version number after an @ sign, for example, npm install –save [email protected] or yarn add [email protected].

Summary

We now have lottie-react-native and its dependencies properly installed and ready to be used to render Lottie animations within our React Native app.

Our project can now be successfully built on both iOS and Android devices, so let's start the magic and integrate our first Lottie animation. We will cover how to do this in the next chapter.