Install the React Native SDK

Create a React Native Project

Create your React Native project with the following command:

npx react-native init MyApp

Change to the project directory that the previous command just created:

cd MyApp

Install the SDK with npm

In your React Native project directory, add the SDK to your project with the following command:

npm install realm

Enable Hermes

The SDK supports React Native's mobile-optimized JavaScript engine, Hermes. By default, new apps created with the React Native CLI already have Hermes enabled.

We recommend that you use Hermes with the SDK. However, the SDK also supports the JavaScriptCore (JSC) engine if your app requires it.

Existing apps that currently use JSC can enable Hermes separately for Android and iOS. To learn how, see the Using Hermes guide in the React Native docs.

Resolve CocoaPods Dependencies

For the iOS app, fetch the CocoaPods dependencies with the following commands from your React Native project directory:

cd ios && pod install && cd ..

This downloads the SDK libraries and regenerates the project .xcworkspace file that you can work with in Xcode to run your application.

Extend Android Proguard Configuration

You may need to extend your Proguard configuration to use it with an Android app. In your Proguard configuration, add the following:

-keep class io.realm.react.**

Enable TypeScript (recommended, but optional)

TypeScript is a superset of JavaScript that adds static type checking and other features intended to make application-scale development more robust. If you'd like to use TypeScript in your project, follow the React Native team's official TypeScript and React Native guide. The SDK supports TypeScript natively and integrates easily into a TypeScript project.

Install the @realm/react Library

@realm/react is an npm package that streamlines common SDK operations like querying, writing to a database, and listening for object change notifications. This reduces boilerplate code, like creating your own listeners and state management.

@realm/react provides access to the SDK through a set of providers that have various hooks. The hooks update React state when the data changes. This means that components using these hooks rerender on any changes to data in the database.

In your React Native project directory, add @realm/react to your project with the following command:

npm install @realm/react

Run the App

React Native enables simultaneous development of both an iOS and Android app that use the same React codebase. You can edit the .js or .ts source files in your project directory to develop your app.

In development, the apps read their React source code as a bundle from a local bundle server. To run the bundle server, use the following command in your React Native project directory:

npm start

With the bundle server running, you can now launch the Android and iOS apps:

• To run the Android app, use Android Studio to open the android directory in your project directory and click Run.

• To run the iOS app, use Xcode to open the .xcworkspace file in the ios directory. If you did not use CocoaPods during setup, open the .xcodeproj file in the ios directory instead. Once you have opened the project, click Run.

Create a React Native Project

Create your React Native project with the following command:

react-native init MyApp

Change to the project directory that the previous command just created:

cd MyApp

Install the SDK Using NPM

In your React Native project directory, add the SDK to your project with the following command:

npm install realm

Link the SDK's Native Module

In your React Native project directory, link the SDK's native module to your project with the following command:

react-native link realm

Confirm the Link Step (Android)

For Android development, confirm that the link step correctly added the SDK module to the Gradle configuration files. In some versions, React Native has been known to fail to link the SDK properly. If this happens, you can link the SDK manually by adding any missing lines below to the corresponding files.

First, ensure the android/settings.gradle file includes the SDK and specifies the SDK's project directory:

rootProject.name = 'MyApp'
include ':realm'
project(':realm').projectDir = new File(rootProject.projectDir, '../node_modules/realm/android')
apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
include ':app'

Second, ensure the android/app/build.gradle file's dependencies section declares the SDK as a dependency:

dependencies {
    implementation project(':realm')
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation "com.facebook.react:react-native:+"  // From node_modules
    // ...
}

Finally, ensure the MainApplication.java file imports the RealmReactPackage and instantiates it in its packages list.

import io.realm.react.RealmReactPackage; // Add this import.
public class MainApplication extends Application implements ReactApplication {
    @Override
    protected List<ReactPackage> getPackages() {
        return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            new RealmReactPackage() // Add this line.
        );
    }
    // ...
}

Enable TypeScript (optional)

TypeScript is a superset of JavaScript that adds static type checking and other features intended to make application-scale development more robust. If you'd like to use TypeScript in your project, follow the React Native team's official TypeScript and React Native guide. The SDK supports TypeScript natively and integrates easily into a TypeScript project.

Run the App

React Native enables simultaneous development of both an iOS and Android app that use the same React codebase. You can edit the .js or .ts source files in your project directory to develop your app.

In development, the apps read their React source code as a bundle from a local bundle server. To run the bundle server, use the following command in your React Native project directory:

npm start

With the bundle server running, you can now launch the Android and iOS apps:

• To run the Android app, use Android Studio to open the android directory in your project directory and click Run.

• To run the iOS app, use Xcode to open the .xcworkspace file in the ios directory. If you did not use CocoaPods during setup, open the .xcodeproj file in the ios directory instead. Once you have opened the project, click Run.