Building C++ / JSI Native Modules for React Native in 2024

Hi, with this talk, I hope to inspire you to build C++ native modules for React Native. It's hard, but becoming easier, and it's not as hard as you might think. My name is Cain Hansen, I work for MongoDB, building developer tools. In my job at MongoDB, I'm also maintaining a React Native library for an open-source mobile database called Realm.

Having mentioned Realm, I also have to mention that MongoDB has decided to deprecate Realm to focus their energy. So enough about me, enough about Realm. What is a native module? Let's break it down, starting with native. It's the native in React Native. It's everything that's running on device, which is not written in JavaScript. What is a module, then? Think of this as a container of related native code. It needs to be discoverable by the app when you build it, using auto-linking via CocoaParts and Gradle, but also at runtime when the library's JavaScript code needs it.

Why would you build a native module? Well, you can write native module code in a couple of different languages. So Kotlin and Java, Swift or Objective-C, you can use to do more tighter platform integration, such as accessing device peripherals, cameras, etc. C++ and Rust you can use to access and build platform-independent performance code. I will focus the rest of my talk on C++. So why not a C++ native module? Well, it gives you increased build times, it's not as easy and hot loading as JavaScript, which is much faster than rebuilding and relaunching an app. It also provides more headaches when you get catastrophic failures and crashes, because you don't always get a nice stack, the same way that you are used to from JavaScript. Managing package dependencies between your code and your C++ dependencies are also sometimes painful, and it has a higher learning curve, many people say. And this ultimately often leads to a lower developer productivity. But as with anything in software, it's a trade-off and it depends.

So how did we get here? I don't think a talk about React Native these days are a talk about React Native before you clarify the old and the new architecture. So let's just go over the old architecture here. It's actually weird that we're calling it old, because it's only just been disabled by default in the 0.76 release of React Native. And we used to do message parsing over what we called the bridge, and this resulted in expensive copies and increased memory usage, as JSON doesn't store binary data efficiently. And it has had an impact on the design of many of the early native modules for React Native, leaving ample opportunity to innovate.

And one pillar of the new architecture on the other side is the JavaScript interface, JSI for short. It's an abstraction over the JavaScript engines, JavaScript Core and Hermes. And the JSI runtime pointer is initialized by React Native. And the goal for the native module is to ultimately interact with it, either directly or through some generated code, calling into C++ and translating return values and arguments into and from JSI values. This is the JSI header, and at least the classes exported by the JSI header. And it's only 1,500 lines of code, but it has a lot of comments. And this is the list of all the classes, right? Let's dive into the runtime. The public API of the runtime is pretty simple. You get the ability to prepare and evaluate JavaScript, manage microtasks. So this is the event loop. And then also access the global object on the runtime. Then the JSI value here. You can construct those from C++ primitives, or you can supply a string of JSON and it will create a value from it. You can also compare equality of these values using JavaScript equality. And then finally, you can read out primitive values into C++ again. Here we go.

Okay. So, JSI object. This is a special kind of value and it has methods to get and set properties. You can also store native state on them. It's shared pointers with some C++ object that you control. You can use another method to communicate external memory pressure from this native state that you've associated with the JSI object. This allows the JavaScript engine to perform efficient garbage collection. So this is my method. This is what I'm going to do.

I'm going to introduce two criteria that I think is important when you decide what alternative to choose. And then I'm going to introduce the available alternatives as I see them right now. So first criterion, you need to decide if you want to support the old, the new, or both architectures. Do you, for example, have existing users and you want to facilitate a graceful transition? Or are you okay with a forceful major update where you say this is new architecture only? Ultimately, it's a trade-off between the availability for users versus getting your maintenance as a library author. If you ship for the old architecture, you also might need to test on the old architecture and you'll get bugs on the old architecture. As I already mentioned, the new architecture just became default.

Second criterion, do you need strong typing between your JavaScript and your native code? And you probably do to limit the catastrophic failures from crashes. It will also lower your maintenance burden to keep these two sides in sync. I've seen two approaches to code generation. So some alternatives, they will allow code generation from TypeScript or Flow into stops that you need to implement on the native side. Other alternatives, which is the one that Realm uses, is to generate TypeScript declarations from the C++ code or some domain-specific language, either something custom or something like WebIDL. And it won't just generate stops that you need to implement, but actual binding code between the C++ library and JSI. Then it relies on the generated code to fail compilation if the two don't match.

The first and now the default alternative is TurboNativeModules. It requires the new architecture to be enabled. It achieves type safety through a code generation tool from TypeScript or Flow declarations into stops that you need to implement on the native side. TypeScript is fairly limited in the expressiveness compared to other alternatives in terms of what types you can communicate over this boundary. And it generates these stops for C++, Objective-C, and Java, but pure C++ modules aren't supported on iOS yet, as I'm recording this.

The second alternative is the LegacyNativeModules. It's deprecated once the new architecture is considered stable, and I suppose that's now that it became default. And it's not yet Forge compatible, so that means it doesn't require the new architecture to be disabled. And this is because of a compatibility layer. So you can use these in old and new architecture. It does not provide any type safety, and it predates JSI, which makes it a bit trickier to access the JSI runtime pointer. Third alternative, it combines the two. So the Legacy and the Turbo module. It's a pattern announced to ease the adoption of the new architecture. It uses macros and Gradle configuration to switch between the implementation at build time to choose the right implementation for the app that is using the library. And you'll likely be able to call some kind of a shared implementation between the two. So the fourth alternative, XperModules, I have to mention this for completeness, but just to summarize from their own docs and also from the React teams I've seen on React Native frameworks, it states that if you intend to use C++ in your native module, use Turbo modules.

It also doesn't support code generation to guarantee the end-to-end type safety. Okay, I mentioned that getting the JSI runtime pointer was difficult from a Legacy module, and I want to explain that now. This is an approach that Realm has been using for a long time, and it was nicely codified by Ditto, as well, on their blog. And I've linked to that on this slide.

The main drawbacks are it relies on private APIs, which might break anytime, and you need to bring your own code generation to get this end-to-end type safety. As a bonus, you can defer loading of the actual native module into the app on Android until it's actually accessed from JavaScript.

Okay, so I'm going to explain this on Android first. We start by registering a blocking synchronous method, callable from JavaScript. And we load the shared object file just in time. We access the JavaScript context holder, and then we synchronize on that to ensure that no other Java threads access it while we initialize. And this is important because it's not thread safe. Then we call get, which returns a memory address of the JSI runtime pointer. And then we finally call injectModuleIntoJSGlobal, which is a native method that we implement on the C++ side using JNI, which we'll get into that just in the next slide here. Ideally, we would just return the value right now, like the initialized binding, but the problem here is that the legacy native modules predates JSI.

Okay, so on the C++ JNI side, we implement this injectModuleIntoJSGlobal native method. It takes this memory address of the runtime pointer as an argument, and then it reinterpret casts it. Then it creates an object that we can use to store our binding on. And then we call a function that we've generated called RealmJSIInit. It's a lot of generated C++ that will basically store the binding between our C++ library and JSI. And finally, we set a property on the global that we can access from JavaScript afterwards.

On iOS, we have to do it a little more dirty in the sense that we need to access the runtime field of the RCT CXX bridge, which is a private API, and we declare this with a simple point pointer. And later on, we basically, again, we declare a blocking synchronous function that we can call from JavaScript. We get the JSI runtime pointer from the bridge, and then we cast it, and then we create the export subject. Again, we call the RealmJSIInit function to populate it, and finally, we store it on the global so we can access it from JavaScript. Then finally return.

The latest and the last alternative that I'm going to introduce is NitroModules. It's the new kid on the block introduced by Marcello and Mark Rosevie. It's very fast in synthetic benchmarks. It supports C++, Swift, Kotlin. It's much more expressive in the code generation part than the other alternatives. It leverages JSI native state and sets external memory pressure correctly. It also supports both the new and the old architecture as of a few days ago, which I'll get back to. The only drawback that I can see right now from using this is it requires app developers like your library users to install a peer dependency called React Native NitroModules, but I believe this is fixable in the future.

My conclusion is that, or at least as of a few days ago, would be to use the backwards compatible TurboNative module pattern. This is the blessed official way of doing things, but NitroModules changed and it doesn't anymore only support the new architecture. So I would say use NitroModules if you feel adventurous, but then who am I kidding? You're using React Native, so of course you feel adventurous. So basically, the last advice before I go, pre-building is a way of taking a part of your native code and building it on your machine instead of the end users machine. The benefit of this is lowering the build time on your library users' machines and also the complexity on their build chains. Another benefit is you get type failures in your development time instead of doing it on the developers' machines, like your users' machines. One limitation of Xcode and CocoaPods is that they cannot drive a CMake project. And this is a way to get about that is to basically use CMake to generate an Xcode project that can basically pre-build an XE framework, for example. That's what we're doing in Realm. Then one limitation here on the Android side is that these are in decay, like all of these pre-builds are in decay ABI specific, which means you either have to ship multiple pre-builds, one per in decay, but usually it's not a super big problem because in decay versions doesn't change that often. Either that, you need to either then, if you don't ship multiple, then you need to declare, I guess, what in decay version your library is compatible with.

And then either assume or assert that at the build time. Okay, another limitation is that, and this is super important, you should not access React Native APIs from your pre-builds. And this is because the ABI boundary or the ABI is not stable across React Native versions. Super important.

Okay, lastly, if you feel it's taking too long time to compile stuff, then on Android you can use a compiler cache or you can do that on both Android and iOS, but use a compiler cache. On Android, it's pretty simple. It's just these lines into your CMakeList file. On iOS, it used to be a little more difficult, but then with this pull request that I landed, it's easier. You can just declare use C cache one as you pod install. If you have C cache installed, that's going to drive and have the compiler compiling through C cache. And then subsequent compilations of your native module will be much faster.

Okay, so the final conclusion. Use Nitro modules. If your C++ project is complex, you can use pre-builds, but be careful. If you get tired of waiting, use a compiler cache. That's my conclusion for now. If you want to learn more, I've included a couple of links here. Thank you so much for your time and attention. It's a rare commodity these days. Reach out if you have any questions or comments for this talk and see you later.