Rusty Native Modules for React Native

Hi, this is my talk about Veric, a Rust binding generator for React Native, Node API modules. And I want to be very clear on this. What you will be seeing today here, it does work. It's still being improved and it barely worked about two weeks ago. So as I'm recording this talk, most of the code isn't published yet. And my hope is that it will be when the recording airs. See this as an aspiration and an early tech preview on what is to come.

First up, my name is Crane. I'm a senior software engineer at MongoDB. I help build developer tools at MongoDB, primarily compass and electron based GUI application to browse your database and your database cluster. I also help maintain the Atlas devices to cover TypeScript, formerly known as RealmJS. It's a lot of TypeScript code, some C++ code, and it supports multiple runtime environments, operating systems, and JavaScript engines. And outside of work, I'm a proud father of two six-year-old girls and a two-year-old toddler, all girls. And I live in Rustkilde, just west of Copenhagen in Denmark. And besides spending time with my family, I also work at MongoDB about 30 hours a week. And outside of that, I like to build in public. And for this, I do accept sponsorships on GitHub by CoreStack in particular. And write to me on BlueSky if you have any feedback. I highly appreciate that.

So why do I care about native modules and about React Native? So I've been battling this beast for seven years now. And in the fall of last year, MongoDB decided to refocus their efforts and deprecate the database I was working on. I have a lot of sunk cost in the problem space, in React Native, and in our community. And I feel obliged to share my learnings from my time building this SDK. As opportunities also emerge on authoring new native modules for React Native, I am conscious that I never want to write and debug a manual binding again. And if at all possible, I would love to build for the least amount of JavaScript engines as possible. Let's dive into Rust. So what makes it difficult to combine React Native, which is written in C++ with a Rust library? First up, their data layouts don't match automatically. And many of the concepts don't carry over between Rust and C++. Here's a couple of examples of how they are not compatible. And you end up dropping down into the least common denominator between when you're communicating between the two.

We call this the foreign function interface often, or also sometimes referred to as a C bridge. And this is an example of this. I made a diagram here depicting the sequence of calls between components. As this is the architecture most often used when wrapping a Rust library in a React Native Turbo module.

When the Turbo module is loaded, it calls into the JavaScript engine via JSI to expose its native functions via the app's JavaScript code, either via the host function or host object abstraction provided by JSI. After this initialization, the JavaScript can call into the Turbo module. And in this example, the app calls the get item passing a string. And this code, it basically calls through the host function into the C++, which then calls the actual library code via the C bridge.

Notice here how the C bridge is domain-specific. It has this call to get item. It's not abstracted away. It's like it's a very concrete language of the library, which is a difficult task to implement and test as a library author, this C bridge, this custom C bridge. And because of the C bridge consumer, it registers itself into the app using JSI, which is not ABI safe. This cannot be put into a prebuilt reliably. So you have to compile this on the app developer's machine.

And notice also that while the Turbo module implements a code generated spec, its internal implementation and the way that it calls into the C bridge, it is type safe, but it could be using and calling incorrectly, which is also another potential issue. And this is because calling from Rust libraries into C++ and with these and the other way around, it quickly becomes very complicated and error prone, especially for complex data types, like structs and things with objects with lifetimes, references to objects with lifetimes. And it's often repetitive, verbose. There's a lot of good reasons why we like to write code in a higher level language. And it often leads to memory leaks and runtime crashes because memory management like doing that manually and also object lifetime aware code, it's very hard to write in a good way. I think it's basically, it's like an endless point of frustration and pain and potentially it will be illegal in the future as well. So it's not a lot of fun to debug these things, to write them or debug them. And here's my heartache, if C is ever a part of your project, it should be generated and considered ephemeral, some sort of like intermediary representation. And there should be no need to commit this into your repository if at all can be avoided.

So what are the alternatives to this? So the first alternative I want to mention is UniFFI by Mozilla. You can use this to alleviate the pain or at least some of the pain. It features multiple target languages. So React Native being one of them. And it is optimized for a broad support of target platforms and it uses a lot of martialing and copying of data to achieve that. It favors ease of implementation and understanding over performance as they write on their own documentation. And this might be the right trade off for you. As I was building a proof of concept for a UniFFI binding for the auto-merge trade back in December, I noticed the rush code I needed to write there to basically prepare it for being exposed this way was considerably, it was the most, there was a lot of code that I needed to write to expose it in a reliable way.

Another alternative is SaferFFI by Dido, and it is improving the developer experience of maintaining such a foreign function interface or ZBridge. It is used and maintained by Dido, as I said, in this local first peer-to-peer sync solution. And it helps deduce safe blocks, sorry, it helps reduce the unsafe blocks in your rush code and it generates a C header for the consumer, but the consuming side of the bridge you still need to implement and maintain manually. And in the context of ABI stability and React Native, you might have also heard about the Hermes ABI. It's an experimental C-based stable ABI for Hermes. So on the surface, exactly what we need, but it's not really for general consumption. And in their own words, it doesn't immediately solve the ABI stability for native libraries targeting React Native. So not React Native itself, but the libraries that built on top of it. And this is because the libraries will still consume a C++ JSI runtime pointer provided by React Native and not Hermes. And the Hermes team is aware of this, and it's within the scope of their efforts to solve this eventually. Until it's ready, I do think that we have other and more, in my opinion, better alternatives available. So this thing happened at React Summit US last year. In the end of the year, I was presenting a talk on building C++ JSI native modules for React Native.

And while I was doing that, Jamie Burch also did a talk on the state of Node API native add-ons in React Native. I highly recommend watching this talk. And when I did, something clicked for me. So why is it that I'm so stoked about these Node API modules? And why was Jamie? Well, it's because it's an ABI safe alternative to JSI and the Hermes API that I mentioned earlier. And it's a C-based API, and it also has a higher level C++ wrapper, just like JSI would be to the Hermes API. And there's an existing thriving community of ecosystems. Sorry, there's a thriving ecosystem of tools and runtimes and libraries available for Node API. It is adopted by Node.js itself, of course, but also other runtimes like Deno, Bon, Electron, and more. And React Native for Windows already use this in their fork of Hermes. So if you, as a library author, want to support multiple JavaScript runtimes beyond React Native, or already have this Node API binding written, then you don't need to spend the time also writing and maintaining a JSI binding. And many binding generators already exist exposing native code through generated Node API function calls.

One of my personal favorites here is that it's trivial to test a binding without spinning up a simulator. You can just run the Node.js process with a dash dash test to run a Node.js process consuming the Node API dynamic library that you build. So the stable ABI here, which is provided by Node API, it enables distribution of your library as a pre-built binary. And what does this mean? Well, it's a huge deal for your users because they don't need to wait for your code to build. And it also means that they won't have to experience and report native build errors when you've messed up. And it also puts less constraints on their environment as they don't have to deal with all the choices you make around the tools that you need to build your library.

How do you go about achieving this? How do you pre-build and generate a Node API binding for your Rust library? And this is what the next part of my presentation is all about. It's about Ferric. Ferric is this pretty simple wrapper around a few other tools. And I explained it as being a part, it's basically comprised of three different parts. So based on Rust macros that you annotate your code with, this generates a low level Node API binding code. And this code is basically calling into Node API functions for you. This is provided by NAPI-RS, the project. It's a different project that Ferric uses to achieve this. This also generates TypeScript declarations for your library, which match the resulting JavaScript API that gets produced when these Node API functions are called. Secondly, the Ferric tool will drive the Rust compiler to build dynamic libraries for each of the requested platforms and architectures as you're pre-building. And finally, these dynamic libraries will then be combined and packaged into pre-builds, which are consumable by React Native, Node API, and what I'm going to talk about later as well. These are basically XG frameworks when you're targeting Apple and JNI, Libs-like directories. These directories where you have architecture-specific subdirectories and then the shared object files inside of them when you're targeting Android.

Okay, time for a demo here. I built this thing called Rusty Web Storage. It's a very stupid implementation, but basically it wraps this storage API, the local storage or session storage API provided by a web browser. Now we want to, as an example, ship this for React Native. And the way that I did it is basically set up a package here, Rusty Web Storage with a package.json file declaring the dependency on the Ferric build tool. It also has a Cargo.toml file which sets the Node API version that it uses. It declares that it wants to compile or build as a C dynamic library, and it also declares a dependency on NAPI-RS, the crate that we use to generate code. It also has a test suite written against the Node.js test runner, and it has the implementation here in a Rust file.

The Rust file here is basically a bit of a preamble. In this case, we just have this storage struct. It's a stupid hash map, so it's all in memory. It could persist, it could encrypt other features. We could add to this, but just for the sake of simplicity, we're just storing values in a hash map. And we expose this using, in this case, we call it the jsStorage. And we give it a different name here. When we use the NAPI macro here, we also provide a jsName for whatever the name is supposed to be when it is generated to JavaScript code. Yeah, so internally, it has a reference to this internal storage object. The implementation of this, again, we annotated with the NAPI annotation here, or the macro.

And here we annotate the new function as a constructor of NAPI. Yeah, and it's pretty simple. We then implement the different members expected by the, or described in the specification for web storage. Here, a length to get all the, like how many values are in the storage. A mutable function here to basically clear the storage. Something to get the item by key. Something here to get the key of the nth entry in the storage. This is used when you generate over the storage. Then there's something here to remove a key and finally to set a key from a, sorry, set a value from a key. Okay, so that's it. And what you do then is basically run the Ferric build tool here. You can see we generate for all the different targets.

We generate the TypeScript declarations. We generated the entry point as well. It's a JavaScript file. We build these Android lib directory. And we also combine some Darwin libraries into a universal library. And finally we packaged up NXE framework. So this is one command that builds for Android and Apple from the Rust code that you just saw. And it also generates the entry point and the TypeScript declarations.

Below here, you can see below the line here, you can see all the things that are ephemeral build artifacts. First up the entry point here, it just contains a require call of the note, the pre-built that was built. And the pre-built here is just a regular dynamic library built for Node.js. But as a sibling find so that we have the Android.node here on the Android pre-builds, the things that are targeting Android. So this is where the shared object files intended for Android and the specific architectures of Android will be put.

We also have this renamed XG framework for iOS and macOS and other like the simulator and whatever is pre-built here. Okay, so the entry point is pretty simple. It's just this require call and the DTS part here, the TypeScript declaration file. You can see here, it basically generates a class, a storage class with a constructor and the length property and or the getter here and then all the different functions that you would expect. So this is matching the web specification. And this is generated completely from the rush code. I also mentioned this test file here which is written against the Node.js test runner API.

Here you can see we're just importing the storage from our package. And we expect that it exports a function like a constructor function here. It can be constructed. It can set and get values. It can return null if there's a missing key. So these are like tests that we can run. It has a length. It can clear all the values. All these things are tests that we can run on Node.js to exercise the module that we created. And I also built a test app in this case. This is an Expo app consuming this rusty web storage.

And you can see here, there's a screen cast on the right-hand side of me typing in and using this library. I'm basically just importing it, initializing it. And then here's some state management around the key presses. Text input here. You can see here in the handle submit, we do storage set item, which is a part of the API that we just implemented. And you can see we have a clear, the storage clear here when you clear the items when you press the button here as well. And then we have an iteration, like a way to iterate over all the possible values inside the storage. And we also use the storage. Here, you can see we use the key, the end key, and we also get the item based on that. And then we also have this code here where we remove an item when you click a trash can icon to the right of the value.

Okay, as an app developer, what you need to do to consume this, you need to install the React Native Node API modules package. And I'm going to get into that. And then you install the library. Then you pod install, or you build your Gradle project. And you have to add a Babel plugin to your Babel config file. I'm also going to get into why that's needed. And then finally, you consume the package as you want it. Okay, so why do you need those things? It's because so far I've been talking about Ferric, but as if React Native already knows how to load Node API modules. And this, however, is not the case.

A major part of the owner for Fabric, sorry, not Fabric, Ferric being so simple is the fact that the community is working on bringing Node API modules to React Native. And this is exactly what I'm going to talk about now. At the center of everything of this React Native Node API modules, we have this host package, we call it. We call it host because it hosts the Node API modules. It comes with a weak Node API pre-built for libraries to link against when pre-building themselves. And it downloads a special version of Hermes with Node API support. It automatically discovers and links these Node API bindings, and it matches, which are matching this pre-built specification, the gni-libs and the XG frameworks that I talked about earlier. And it also, this whole package implements a turbo module with a requireNodeAddOn function responsible for loading the pre-built dynamic libraries and providing the Node API functions to these modules. And it also initializes a per module per JSI runtime, Node API environment, also known as the nappyenv. And finally, the host package exports this Babel plugin, which app developers use to transform require calls for .node files into requireNodeAddOn calls.

Now let's look at the sequence of calls when loading and initializing and calling into our Rusty web storage library built as a Node API module. The app requires the pre-built, which registers and initializes itself using Node API, which the app can call, after which the app can call the getItem function, which calls directly into the library using Node API call conventions. And notice how the FFI is now turned around compared to the manual C bridging. There's no longer a library. It's no longer the library providing the C API. Now it is consuming the Node API instead. So the C bridge is now generic. And this means that names and concepts are no longer specific to the domain of the library. And this is huge because we can invest in making this super well implemented and tested once and for all.

So what are the limitations here? I mentioned in the beginning that this is early and there are a few limitations that apply. As I'm recording this, only a few of the runtime-specific Node API functions are implemented. All the JavaScript object and function manipulation works, but asynchronous code like futures and promises, they don't. And the Hermes support for Node API is an open PR, which is actively being worked on, but it's not yet merged. This means that the initial app build time will be slow because you're basically compiling Hermes and React Native from source, and there are very specific requirements on the React Native version that you can use. And if you think any of this is interesting, please let us know and let other people also hear about it, because we need your help to keep the momentum going here. OK, I'm not alone in this. None of this would be possible without the help and active participation of our awesome community. Here's a few names of people that I've been meeting with weekly since January, and I probably also forget to mention some, but I would love to also extend my gratitude to my employer, MongoDB, and also the team at Callstack. Thank you so much for your time and attention. It's a rare commodity these days, and I hope to see you in person. Please stop and tell me if you find any of this interesting, if you find me in person. Goodbye.