React Native, Meet node.js Native Addons

We'll be going over a few things in this talk. Of course, what are Node.js native add-ons? We're going to run into a couple of use cases. One, an ABI stable API for Hermes that is already in use. And two, a proof of concept of cross ecosystem library sharing. We'll wrap it all up afterwards.

So, what are Node.js native add-ons? Well, Node.js has its own native modules called native add-ons. For example, for Node.js to interact with SQLite3, there's an NPM package for that. And just as React native modules are written with JSI, Node.js native add-ons are written with NodeAPI, which is similarly engine agnostic. Now, to put that visually, it's like this. NodeAPI occupies the same position between native code and JavaScript engines as JSI does.

So, why should we care? We've already got JSI. What more do we need? Well, first of all, NodeAPI is incredibly popular. So, if you measure it just by the downloads per week of Node add-on API, which is commonly imported by Node.js native add-ons based on C++, there's 20 million downloads per week. Very popular. It's community driven. It's a de facto industry standard, and it's available for various languages. So, instead of writing in C++, you can write in Swift, as, you know, we can do with Expo modules and Nitro modules, but also Rust, C Sharp, Nim, Zig, Go. And it can express pretty much anything ECMAScript can. You want proxies, you can have it. You can do class extensions, static methods, all sorts of things, very idiomatically, rather than having to do lots of prototype tricks, for example. There's first class interrupt between native and JavaScript context. So, you've got lifetimes, you've got async functions, you've got threading, that sort of thing. And it's ABI stable, which we'll be getting into later.

So, is this all just theorycrafting? It's one thing to say Node API would be great, it's got all these characteristics, but what's the story about bringing it into React Native? Well, the truth is, it's already in use in React Native Windows. So, I'd like to tell a story about an ABI stable API for Hermes. But in order to explain that, first we need to be clear of what an ABI is. So, here we have a lovely image of some binary, which expresses part of this story. So, an application binary interface is the compiled version of an API. So, while you when you're dealing with APIs are dealing with human concepts, like classes and declarations and functions and that sort of thing, an ABI is a lower level. It's like it says inside this big old binary blob, where do I find the stuff that I need and what does it mean? So, it defines the set of functions and their signatures, the data structures, for example layouts of structs and enums, function calling conventions, error handling, and memory management.

And an ideal ABI is both safe and stable. Let me explain what I mean by that. There's a concept of ABI safety, where you have your app and a library that it consumes, let's say Hermes. And for building your app as fast as possible, you want to be building your app and your userland code in debug mode. But libraries such as Hermes, you'll want precompiled in release mode. You don't want to be compiling them from scratch each time. And you want it to be running as fast as possible. That's why you want all the optimizations of release compilation.

Now, ABI safety, therefore, lets a binary be used in your app without recompilation, regardless of the build mode, compiler, or language. ABI stability is another thing that goes along with it. We've got our app again. We've got Hermes again. But, say we wanted to swap out an older version of Hermes for a newer one, without recompiling the rest of our app. This is what ABI stability is about. It's a commitment to backwards compatibility, saying, for example, if we're going to add any new case to an enum or any new method to a class, we do it, you know, we commit to doing things additively, and we never remove stuff.

So, this is put into practice in React Native Windows. In order to realize these benefits, React Native Windows uses a fork of Hermes, that implements an API based on Node API. Since its development, Hermes has begun developing an official API, but for now, let's study how Hermes Windows works. The way things started off, the Hermes library would expose JSI, as the API by which React Native uses it. JSI being a C++ library is not ABI safe. In future, this will get a bit better, we'll have a Hermes ABI safe API, which React Native can code against. But, as that was not originally available, Hermes Windows took a certain approach to expose an ABI safe API for React Native Windows. How did they do that? Well, they made a library called Node API, JSI. And I'll get into that in just a second, but instead of exposing JSI, which was not ABI safe, they exposed Node API, which is ABI safe. And then, Node API JSI can expose JSI to React Native Windows, and it implements JSI on top of Node API. This is a little bit confusing, but this is how it all is set up. The key thing about this is Node API JSI is source only. So, any symbols it's exporting, JSI symbols, don't matter because they're internal to the React Native DLL. So, it doesn't matter that JSI is not ABI disabled if it's not, you know, if it's private.

So, it doesn't matter that JSI is not ABI disabled if it's not, you know, if it's private. So, that's how they did it. And the benefits of this are, concretely, we can now use the latest Hermes regardless of React Native Windows. We can use prebuilt Hermes in release mode for faster execution, whilst building the rest of our app in debug mode for faster builds. This is all thanks to Node API.

Now, another use case is cross ecosystem libraries. I'd like to talk about NativeScript. So, this is a cross ecosystem library that we'd like to bring to React Native, as it's exactly the kind of thing that I think React Native could benefit from. But first, to explain why we'd want this, I just want to show what it is for a moment. So, NativeScript is a library for calling native APIs from JavaScript. Say you wanted to call a phone number, give them a platform, iOS, you can do idiomatic JavaScript access to the iOS SDK. So, here we're interacting with UIKit. We're grabbing the UI application, and we're calling a method with some a mixture of JavaScript arguments. So, you'll see the middle argument is a simple object which gets marshaled to an NSDictionary. But the other arguments, you know, we've got the result of a function call, and we're passing a JavaScript function, as well. So, it's really quite magic stuff. And we can do the same for Android. And the idea of this is it would mean we don't have to deal so much with native code. We can do JavaScript inline that calls native APIs for us. So, it's a very good fit for React Native. And we actually have a proof of concept of this working on Node.js.

The way we approached it was we made a Node.js native addon. We thought, well, could we bring this to React Native? The problem is, Node.js native addons can't be used as is, even in React Native windows. Because although native script is available as a Node.js native addon, Hermes windows only implements the underlying API. Node API. So, this is something I probably should explain sooner. If Node API is this subset, Node.js native addons wrap around it. And the key thing about native addons is that implementing all of that spec is needed to implement module loading support so that you can simply do require your addon. But given the library is mostly Node API and there's just a tiny bit for that module loading logic at the end, can we still use it somehow? There is a way. Here's how I went about it.

To initialize the addon, just so you know, the typical approach in Node.js would be this. You would acquire the library. And that causes the module to be evaluated, which makes the modules initialize a run, which ultimately calls our internal function, which we've called objective C bridge init. And that runs all logic for setting up these bindings. So, how could we do that in the world of React Native, where we have Node API, but not module loading support? Here's our modified approach.

We'd auto link something we're going to call native script XC framework. So, for each architecture that we want to support, we'll have a recompilation of native script.node. And native script.node is at the end of the day a library. You can embed it in various ways. You can append it at the end of the binary or shove it in XC framework. And once we have that native code available in our app, we can manually call objective C bridging it from the native side. I'll show you how we go about doing that.

So, what I did was I recompiled Hermes Windows for iOS because this particular library is all about the objective C bridge, so we had to use iOS to do any sort of proof of concept. Then I patched the following file to set up Node API. It's Hermes executive factory. This is where Hermes gets the Hermes of a runtime gets initialized in your React Native app. So, just a few lines here. We create a Node API environment at the time we're making the Hermes runtime and we open up a Node API environment scope. And just one extra line here for the native script Node API set up. We call objective C bridge in it passing in that environment and then off we go. Ideally, this stuff would not involve patching Hermes executive factory. Node API would be set up from the beginning. And maybe in user and maybe in a JSI module. I'm not sure if that's too late in the life cycle to do it. Ideally, we could then call objective C bridge in it in user land. Anyway, let's try it. I've created an expo template. This is on an older version of React Native. But the concept and principles are still there. So, you can play along with it, too.

One simple little demo. We can read the battery level without getting a native module involved just by writing some inline JavaScript. So, we can grab UI device and inspect it and grab the battery level out.

Another thing we can do is get some proper debugging on native data. So, for example, here we grab the root view and we ask what is the debug description. And we can see all sorts of cool stuff. We can see the pointer values. We can see the frame. And this can be really useful for distinguishing one native view for another, which might be really interesting for a virtual list, for example.

And here's a fun one. We can actually do view changes. So, here I grabbed root view again and we set the background color on it. This was actually quite surprising because we're on the JS thread and we were able to make a UI change. This should have crashed the app. But as it turns out, the background color is a thread safe property. So, we get away with this. But if we want to do some serious work on the UI thread, there is a way. And it involves React Native reanimated. We use a React Native reanimated worklet and we run that worklet on the UI thread. Now, the developer experience here is not ideal, I would say. So, I'd like to come up with a better API for this in the future. But just to show a proof of concept, we could even access the UI thread safely with this methodology. And here we create a native alert using UI APIs inline. So, this is all to say there really is no limit of Node.js native add-ons. You can do really native stuff from the JavaScript side.

Starting with my hopes for the future. I'd like to see Node API upstreamed into Hermes. This is actually in progress. There is a PR open for this right now.

There is a PR open for this right now. I'd like to see support for Node.js native add-ons. No idea what sort of timeline we might ever see this in. But that would really open up this whole ecosystem.

Completion of the official ABI stable Hermes API would also be incredible because that would lead the goal. Native modules currently code against JSI. So, it's a really bad story if you want to distribute prebuilt ABI stable native modules. So, once ABI stability comes to them, you can start precompiling them. And distributing them flexibly.

And finally, more cross ecosystem collaboration. I'd love for us to stop reinventing the wheel and to work together with folks from Electron, for example, and Node and start reusing some of their stuff and sharing some of ours. So, in summary, Node.js native add-ons are the de facto JavaScript native module standard and are based on ABI stable API, Node API. ABI stability is important for flexibility in using prebuilt libraries, such as using one thing in debug mode while the rest of your app compiles in release mode or vice versa, whatever you want to do. And cross ecosystem collaboration is currently limited without full Node.js native add-on support, but not impossible with workarounds.

Work is also underway to upstream Node API into Hermes, and I'm very excited for that. So, I'll end with some acknowledgements. Thank you to React Native Windows team for implementing all these concepts and proving them out. The Hermes team for being receptive to taking Node API into core. The NativeScript TSC for sort of getting me involved in this world of thinking about Node API with this proof of concept of running NativeScript on Node.js. And then Expo. I needed a way to share these samples and Expo templates were the perfect way to do that. So, thanks for watching. I hope we can use Node API more in the future and I hope we can share more cross ecosystem.