Accessing JavaScript land from native modules in the New Architecture

[philIip]

Hi all, with the release of 0.74, we've introduced new APIs and backwards-compatibility for previously unsupported functionality in the bridgeless architecture, such as getting the CallInvoker to safely jump to JavaScript thread and retrieving the jsi::Runtime, which was supported in the bridge architecture. I'd like to summarize those changes in this discussion as well as gather feedback from you all.

Immediate access to jsi::Runtime

Bridge

In the bridge architecture, currently we have the following options for immediate access to the runtime. These are not thread safe, and it is up to the consumer to use the runtime correctly by casting it to the correct type, managing its lifecycle, and handling it on the JS thread.

Android

Accessed through getJavaScriptContextHolder on ReactContext.

JavaScriptContextHolder javaScriptContextHolder = context.getJavaScriptContextHolder();

iOS

Accessed through exposing the private runtime selector via a category on RCTBridge:

@interface RCTBridge (BridgeWithRuntime)
- (void *)runtime;
@end

Bridgeless

In bridgeless, the above APIs have been made backwards compatible. However, we acknowledge that the ways to handle this raw runtime pointer is a bit hacky and dangerous, so we are currently recommending C++ TurboModules as the solution here. We've added support for C++ TurboModule autolinking in 0.74 so that users of your libraries do not need to change their code in order for your C++ TurboModule to be registered. However, there are some changes that you will need to do in order for this happen.

RN CLI (Android only)

On Android, @cortinico added support for C++ TurboModule autolinking in react-native-community/cli#2296 via the RN CLI, with detailed instructions on how to enable this.

RCT_EXPORT_CXX_MODULE_EXPERIMENTAL (Android and iOS)

Within the RN framework, we've added a macro that will register your C++ TurboModule before startup. This is a temporary solution to encourage authors to explore C++ TurboModules, but incurs a startup cost. We will look to replace this with a solution in the future, but wanted to provide this option to start with. Instructions on how to use are detailed in facebook/react-native#43054.

Asynchronous JavaScript thread access

Bridge

In the bridge architecture, currently we have the following options to safely asynchronously access the JavaScript thread, but not the runtime.

Android

Accessed through the CatalystInstance, which is first retrieved from the ReactContext:

CallInvokerHolder callInvokerHolder = context.getCatalystInstance.getJSCallInvokerHolder();

iOS

Accessed through exposing the private jsCallInvoker selector via a category on RCTBridge:

@interface RCTBridge (BridgeWithCallInvoker)
- (std::shared_ptr<facebook::react::CallInvoker>)jsCallInvoker;
@end

// In implementation somewhere
auto callInvoker = [bridge jsCallInvoker];

Bridgeless

In the 0.74 bridgeless architecture, we have provided the RuntimeExecutor API. It is similar to CallInvoker but also provides thread safe access to the runtime, making it a good option to install bindings if there is an acceptable async delay. Note that you can also use C++ TurboModules, as their methods will have access to the callInvoker as well.

Android

The RuntimeExecutor is retrieved via a method from the ReactContext. This is forward compatible with bridge.

RuntimeExecutor runtimeExecutor = context.getRuntimeExecutor();

Then, you can pass it down to C++ layers via JNI to execute code on the JS thread.

runtimeExecutor([=](facebook::jsi::Runtime &runtime) { 
  // do stuff on JS thread
});

iOS

We have provided a protocol that your native module can conform to which will decorate the module with a property that allows them to access the RuntimeExecutor. You need to make your module conform to this protocol and synthesize a selector for the RuntimeExecutor. This is currently not forward compatible in bridge mode, but I am open to that if it seems to cause a lot of forked code.

// In RCTMyModule.mm
@interface RCTMyModule () <NativeMyModuleIOSSpec, RCTRuntimeExecutorModule>
@end

@implementation RCTMyModule

@synthesize runtimeExecutor = _runtimeExecutor;
...
[self.runtimeExecutor execute:^(facebook::jsi::Runtime &runtime) {
    // do stuff on JS thread
})];
...
@end

---

I hope this post will help answer some of the questions you all have on how to interact with JavaScript land in bridgeless mode. Please let me know if there are any challenges with the migration path here or if the recommendations are not sufficient for your use case. I'm very open to evolving these as I learn about everyones' use cases. Thank you!

[acoates-ms]

Windows

Going to provide the windows version of this documentation for completeness:

In react-native-windows the primary way to access the jsi::Runtime is using ExecuteJsi. This takes a ReactContext and a callback which recieves the jsi::Runtime. This can be used for both synchronous and asynchronous scenarios, as ExecuteJsi will run synchronously when run on the JavaScript thread, otherwise it will post to the JavaScript thread.

winrt::Microsoft::ReactNative::ExecuteJsi(reactContext, [](facebook::jsi::Runtime& runtime) {
  // do stuff on JS thread
}

If you require a RuntimeExecutor to pass around cross platform code, a simple implementation of one would be:

auto runtimeExecutor = [reactContext](std::function<void(facebook::jsi::Runtime& runtime)>&& callback) {
  winrt::Microsoft::ReactNative::ExecuteJsi(reactContext, std::move(callback));
}

ReactContext can be accessed from the ReactInstanceSettings lifecycle events (InstanceCreated, InstanceLoaded and InstanceDestroyed), or from the Initialize method attributed with REACT_INIT of a windows TurboModule.

jsi::Runtime is also provided to C++ facebook::react::TurboModules. These can be registered and auto-linked the same way as windows TurboModules - and have been able to be since 0.64.

All of these methods and APIs will remain unchanged when enabling bridgeless mode in the future.

[jpudysz]

Is it possible to access CallInvoker too?
I'm in the middle of transitioning from hybrid JSI module to a pure C++ TurboModule in react-native-unistyles, and I need both jsi::Runtime and facebook::react::CallInvoker references. In the future I will grab them directly from JSI methods.

I was able to get it from catalystInstance on Android, and RCTBridge on iOS.

How can I do that on Windows?

Also, is grabbing JSIRuntime like this correct?

Thank you in advance for any guidance.

[jpudysz]

Was abe to grab it with MakeAbiCallInvoker:

[maksimlya]

Thanks for sharing! I am on similar stage right now, have android/ios/mac working but need windows solution. Any advices of how much it differs than other platforms? So far only added the 'structure' using the react-native-windows-init lib.

[jpudysz]

It differs a little bit, because winrt has different API. Once you get used to it, it's just C++ 😉
You can check my implementation in unistyles repo.

[jobpaardekooper]

It is mentioned that we can get the callInvoker on android using:

CallInvokerHolder callInvokerHolder = context.getCatalystInstance.getJSCallInvokerHolder();

I think thats missing the brackets on getCatalystInstance so it should be:

CallInvokerHolder callInvokerHolder = context.getCatalystInstance().getJSCallInvokerHolder();

[teodorciuraru]

@philIip Awesome work! I presume modules must support both Bridge and Bridgeless architectures in the mid-term. It seems like Bridgeless provides a thread-safe async way to grab a hold on runtime while the Bridge way doesn't (as far as I read). How can we ensure runtime will be safely retrieved async for both architectures in the long term?

For example, a JS function is passed to JSI and will be used as a callback that will trigger sporadically on the C++ side. Let's say it triggers every minute, and we need a new valid runtime reference to call JS Land back. jsCallback->call(runtime, obj);. What's a backward-compatible solution for this?

[maksimlya]

Can anyone please explain me about thread safety of that one?

RuntimeExecutor runtimeExecutor = context.getRuntimeExecutor();

my jsi .cpp file:

jsi::Runtime* runtime_ = nullptr;
namespace myApp {

    int install(jsi::Runtime &runtime) {
        runtime_ = &runtime; // store runtime for future use / calls to js.
    }
}

Now, for example I have some data arriving on tcp socket that was open (so obviously it will be triggered on different thread).

int onTcpCall(char* name, char* socketId, void* bytesData) {
                jsi::Runtime& runtime = *runtime_;

                // some processing code....
                     jsi::Function onTcpData = runtime.global().getPropertyAsFunction(runtime, "onTcpData");
                onTcpData.call(runtime, socketIdStr, buf, 2);

                return 0;
        }

Now this one still crashes the app with 'is thread attached?' error (works correctly if I call the callback from same thread). I understand there's other apps out there that solved it with invoker code, but they took it from catalyst instance, which is just same as old bridge? Is there better/more efficient way to do what I need now in rn 0.74? Because I tested it and unlike it is stated, the jsi::Runtime& runtime doesn't looks thread safe.

[jobpaardekooper]

You should still solve it in the same kind of way like you mentioned other apps are doing. Those other apps are doing it with call invoker but in bridgless you can now use RuntimeExecutor as mentioned in the original post.

Also it is stated that "RuntimeExecutor [...] provides thread safe access to the runtime" that does NOT mean that the runtime you are using is thread safe.

[maksimlya]

And I assume that RuntimeExecutor only accessible from Java/ObjC, so if my trigger is inside cpp itself, there's no way for me to get it and I should store invoker reference instead?

[jobpaardekooper]

Seems like you should just store a reference to the RuntimeExecutor in your c++ code if that is what you are asking.

Also the post says: "Note that you can also use C++ TurboModules, as their methods will have access to the callInvoker as well."

I think they ment to say RuntimeExecutor instead of callInvoker in that sentence.

[maksimlya]

Seems like you should just store a reference to the RuntimeExecutor in your c++ code if that is what you are asking.

Yes! Would like to know how to do that, as I don't think there's any examples for it. Will try to play with it later tonight but if anyone got idea, would be happy to hear. TurboModules - not sure what that means, but I think TurboModules always refer to communication between platform-specific layer (Java/Obj-C) to JS, which I don't need, as I am writing c++ and golang module for my app that doesn't directly involves Java/Obj-C.

[jobpaardekooper]

Like mentioned in the post you should pass them for example using some sort of install or initialisation method for your library. You have to it from java/objective-c to your c++ code. I am not using this so I don't have a code snippet for you but maybe you can find a library that is using RuntimeExecutor and see how they do it.

[vonovak]

I just wanted to share that some of the information above is probably outdated, and newer info is covered in this talk https://youtu.be/oLmGInjKU2U?si=iZt8ieaWr28eCq71&t=1141