React Native JSI: Part 1 - Getting Started

How is JSI different?

1. Javascript Interface which allows us to register methods with the Javascript runtime. These methods are available via the global object in the Javascript world.

2. The methods can be entirely written in C++ or they can be a way to communicate with Objective C code on iOS and Java code in Android.

3. Any native module that is currently using the traditional bridge for communication between Javascript and the native worlds can be converted to a JSI module by writing a simple layer in C++

4. On iOS writing this layer is simple because C++ can run directly in Objective C hence all the iOS frameworks and code is available to use directly.

5. On android however we have to go an extra mile to do this through JNI.

6. These methods can be fully synchronous which means using async/await is not mandatory.

Setting up our JSI Module

npx create-react-native-library react-native-simple-jsi

Configuring on Android

1. Install NDK.

2. Install CMake.

CMakeLists.txt

cmake_minimum_required(VERSION 3.9.0)

add_library(cpp
            SHARED
            ../cpp/example.cpp
            ./cpp-adapter.cpp
)

include_directories(
            ../../react-native/React
            ../../react-native/React/Base
            ../../react-native/ReactCommon/jsi
            ../cpp
)

set_target_properties(
        cpp PROPERTIES
        CXX_STANDARD 17
        CXX_EXTENSIONS OFF
        POSITION_INDEPENDENT_CODE ON
)

target_link_libraries(
        cpp
        android
)

1. cpp is the name of our library.

2. SHARED libraries are linked dynamically and loaded at runtime.

3. We are including different files that we will need for our code to run.

4. example.cpp is where our c++ code lives

build.gradle

  externalNativeBuild {
    cmake {
      path "./CMakeLists.txt"
      version "3.8.0+"
    }
  }

Step 3: Installing JSI Bindings

SimpleJsiModule.java

package com.reactnativesimplejsi;

import android.util.Log;

import androidx.annotation.NonNull;

import com.facebook.react.bridge.JavaScriptContextHolder;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.module.annotations.ReactModule;

@ReactModule(name = SimpleJsiModule.NAME)
public class SimpleJsiModule extends ReactContextBaseJavaModule {
  public static final String NAME = "SimpleJsi";

  static {
    try {
      // Used to load the 'native-lib' library on application startup.
      System.loadLibrary("cpp");
    } catch (Exception ignored) {
    }
  }

  public SimpleJsiModule(ReactApplicationContext reactContext) {
    super(reactContext);
  }

  @Override
  @NonNull
  public String getName() {
    return NAME;
  }

  private native void nativeInstall(long jsi);

  public void installLib(JavaScriptContextHolder reactContext) {

    if (reactContext.get() != 0) {
      this.nativeInstall(
        reactContext.get()
      );
    } else {
      Log.e("SimpleJsiModule", "JSI Runtime is not available in debug mode");
    }

  }

}

1. We are loading our c++ library using System.loadLibrary.

2. We have an installLib function which is looking for javascript runtime memory reference. The get function basically returns a long value. This value is passed over to JNI where we will install our bindings.

SimpleJsiModulePackage.java

package com.reactnativesimplejsi;

import com.facebook.react.bridge.JSIModulePackage;
import com.facebook.react.bridge.JSIModuleSpec;
import com.facebook.react.bridge.JavaScriptContextHolder;
import com.facebook.react.bridge.ReactApplicationContext;
import java.util.Collections;
import java.util.List;

public class SimpleJsiModulePackage implements JSIModulePackage {
  @Override
  public List<JSIModuleSpec> getJSIModules(ReactApplicationContext reactApplicationContext, JavaScriptContextHolder jsContext) {

    reactApplicationContext.getNativeModule(SimpleJsiModule.class).installLib(jsContext);

    return Collections.emptyList();
  }
}

....

import com.facebook.react.bridge.JSIModulePackage;
import com.reactnativesimplejsi.SimpleJsiModulePackage;

public class MainApplication extends Application implements ReactApplication {

  private final ReactNativeHost mReactNativeHost =
      new ReactNativeHost(this) {
        @Override
        public boolean getUseDeveloperSupport() {
          return BuildConfig.DEBUG;
        }

        @Override
        protected List<ReactPackage> getPackages() {
          @SuppressWarnings("UnnecessaryLocalVariable")
          List<ReactPackage> packages = new PackageList(this).getPackages();
          // Packages that cannot be autolinked yet can be added manually here, for SimpleJsiExample:
          // packages.add(new MyReactNativePackage());
          return packages;
        }

        @Override
        protected JSIModulePackage getJSIModulePackage() {
          return new SimpleJsiModulePackage();
        }

        @Override
        protected String getJSMainModuleName() {
          return "index";
        }
      };
.....

1. We are importing JSIModulePackage

2. We are registering our SimpleJsiModulePackage as a JSI Module so that when JS Runtime loads, our jsi bindings are also installed. Inside our instance of ReactNativeHost we are overriding getJSIModulePackage method and returning an new instance of SimpleJsiModulePackage.

cpp-adapter.cpp

#include <jni.h>
#include "example.h"

extern "C"
JNIEXPORT void JNICALL
Java_com_reactnativesimplejsi_SimpleJsiModule_nativeInstall(JNIEnv *env, jobject thiz, jlong jsi) {
    // TODO: implement nativeInstall()
}

#include <jni.h>
#include "example.h"

extern "C"
JNIEXPORT void JNICALL
Java_com_reactnativesimplejsi_SimpleJsiModule_nativeInstall(JNIEnv *env, jobject thiz, jlong jsi) {

    auto runtime = reinterpret_cast<facebook::jsi::Runtime *>(jsi);

    if (runtime) {
        example::install(*runtime);
    }
}

1. JNIEnv: A JNI interface pointer

2. jobject: The java class from which the function is called.

3. long value of our runtime memory reference.

Configuring on iOS

SimpleJsi.mm

#import "SimpleJsi.h"
#import <React/RCTBridge+Private.h>
#import <React/RCTUtils.h>
#import <jsi/jsi.h>
#import "example.h"

@implementation SimpleJsi

@synthesize bridge = _bridge;
@synthesize methodQueue = _methodQueue;

RCT_EXPORT_MODULE()

+ (BOOL)requiresMainQueueSetup {

    return YES;
}

- (void)setBridge:(RCTBridge *)bridge {
    _bridge = bridge;
    _setBridgeOnMainQueue = RCTIsMainQueue();
    [self installLibrary];
}

- (void)installLibrary {

    RCTCxxBridge *cxxBridge = (RCTCxxBridge *)self.bridge;

    if (cxxBridge.runtime) {
       example::install(*(facebook::jsi::Runtime *)cxxBridge.runtime);
    }
}

@end

1. We are telling React that our module requires setup on Main Queue.

2. We are getting an instance of bridge which we will use to get the runtime and install our jsi bindings. Inside it we are checking if bridge.runtime exists or not. If it does not, we are waiting for sometime and then trying again until the bridge.runtime becomes available.

SimpleJsi.h

#import <React/RCTBridgeModule.h>;

@interface SimpleJsi : NSObject <RCTBridgeModule>;

@property (nonatomic, assign) BOOL setBridgeOnMainQueue;

@end

#include "example.h";
#include <jsi/jsi.h>;

using namespace facebook::jsi;
using namespace std;

namespace example {
    void install(Runtime & jsiRuntime) {
        auto helloWorld = Function::createFromHostFunction(jsiRuntime, PropNameID::forAscii(jsiRuntime, "helloWorld"), 0, [](Runtime & runtime,
            const Value & thisValue,
                const Value * arguments, size_t count) -> Value {
            string helloworld = "helloworld";
            return Value(runtime, String::createFromUtf8(runtime, helloworld));
        });

        jsiRuntime.global().setProperty(jsiRuntime, "helloWorld", move(helloWorld));
    }
}

1. At the top, you see that we have included jsi include files.

2. The using namespace facebook::jsi; etc helps us not write facebook::jsi over and over.

3. install function takes one parameter and that is our JS runtime. Inside this function we are registering a method by name helloWorld which will return a hello world string when we call it from javascript code.

4. Function::createFromHostFunction is a method creates a function which, when invoked, calls C++ code.

5. jsiRuntime.global().setProperty is where we bind our function with the javascript runtime global object.

1. Runtime: Represents a JS runtime where our javascript code is running

2. PropNameID: An identifier to find our function. It is a simple string.

3. paramCount: Number of parameters this function will have. In our case it's 0.

4. function: A function that will be invoked when we call global.helloWorld() from javascript.

1. Runtime: Represents a JS runtime where our javascript code is running

2. Value &thisValue: It is a reference to Value class instance which is used to pass JS values to and from javascript code.

3. Value *arguments: The arguments for this function coming from Javascript.

4. size_t count: Total number of arguments.

Calling our function in Javascript

export default function App() {
  const [result, setResult] = React.useState<number | undefined>();

  React.useEffect(() => {
    setResult(global.helloWorld())
  }, []);

  return (
    <View style={styles.container}>
      <Text>Result: {result}</Text>
    </View>
  );
}

Calling function with multiple arguments

auto multiply = Function::createFromHostFunction(
    jsiRuntime, PropNameID::forAscii(jsiRuntime, "multiply"), 2,
    [](Runtime &runtime, const Value &thisValue, const Value *arguments,
       size_t count) -> Value {
      int x = arguments[0].getNumber();
      int y = arguments[1].getNumber();
      return Value(x * y);
    });

jsiRuntime.global().setProperty(jsiRuntime, "multiply", move(multiply));

Calling a JS Callback from C++

auto multiplyWithCallback = Function::createFromHostFunction(
    jsiRuntime, PropNameID::forAscii(jsiRuntime, "multiplyWithCallback"), 3,
    [](Runtime &runtime, const Value &thisValue, const Value *arguments,
       size_t count) -> Value {
      int x = arguments[0].getNumber();
      int y = arguments[1].getNumber();
      arguments[2].getObject(runtime).getFunction(runtime).call(runtime, x * y);
      return Value();
    });

jsiRuntime.global().setProperty(jsiRuntime, "multiplyWithCallback",
                                move(multiplyWithCallback));

While in javascript, we can call the function like this:

  global.multiplyWithCallback(2,4,(a) => {
    console.log(a); // 8
  })

Value

Conclusion