Announcing Node-API Support for React Native

Together with the community, we're bringing Node-API, the native module system developed and widely used in Node.js, into React Native. Node-API allows native code to interface with JavaScript in a runtime-independent and stable way. It’s used in production today across Node.js, Deno, Bun, and more.

By adopting Node-API in React Native, we gain a consistent, cross-platform foundation for building native modules. It supports multiple programming languages and is ABI-stable, making it easier to share, reuse, and maintain modules across projects and versions.

In this article, we dive deeper into the potential future of this module system, our motivation behind building it, and take a closer look at how it works and what it enables for the React Native ecosystem.

If you just want to see the code, we've published an example repo with a Node-API addon prebuilt for Node.js and React Native: https://github.com/callstackincubator/node-api-example-lib

Special thanks

Before we dig in, we need to acknowledge how this is truly a collaborative effort across the community.

Since Vladimir Morozov’s PR adding Node-API to Hermes and Jamie Birch’s talk at React Summit US ‘24 we’ve been meeting on a regular weekly cadence and worked together.

None of this would be possible without the attention and generous contributions from Vladimir (Microsoft), Jamie (NativeScript), Kræn (MongoDB / Independent), Matt Hargett (Rebecker Specialties) and numerous Callstack engineers - Mariusz (Mario) Pasinski in particular.

Motivation

Pre-builds that work across React Native versions

Today, most native modules for React Native are distributed as source, and so contribute significantly to the overall build time of apps. In fact, compiling native modules can constitute the majority of an app's build time, as we can see clearly on Android:

On iOS, it is the second-biggest build task after compiling React Native core. And as work is underway to distribute React Native iOS as a prebuilt binary (like Android), it will soon become the biggest one.

By distributing all native modules as prebuilds, apps could be built in as little as 7 seconds.

React Native and Hermes teams are actively working on ABI stability for JSI, and it's scheduled for React Native 0.81 (currently in RC). Once shipped, it will make such optimizations possible for everyone.

Existing ecosystem of Node-API compatible runtimes & languages

Node-API is the technology of choice for calling native code from JavaScript, for a number of runtimes, such as Node.js, Deno, and Bun. Being engine-agnostic, and with bindings from a variety of programming languages (e.g., C, C++, C#, Swift, Zig, Go, or Rust), it has become a popular tool for cross-ecosystem code-sharing, with countless modules available on npm today.

With Node-API being a part of the Node.js project (hosted by the OpenJS foundation) the longevity and healthy evolution of the specification is secured. We believe it’s here to stay and worth the effort for the React Native community to start investing into as well.

Because Node-API is a C API, any language with the ability to call a C-style foreign function interface (FFI) can call into it. Below are a few examples of a simple sum function implemented in different languages. Some (like Rust) are very concise as they leverage code-generation, and others (such as C++) are a bit more verbose.

C++

1#include <napi.h>
2
3Napi::Value Sum(const Napi::CallbackInfo& info) {
4  Napi::Env env = info.Env();
5
6  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {
7    Napi::TypeError::New(env, "Expected two number arguments").ThrowAsJavaScriptException();
8    return env.Null();
9  }
10
11  double arg0 = info[0].As<Napi::Number>().DoubleValue();
12  double arg1 = info[1].As<Napi::Number>().DoubleValue();
13  double sum = arg0 + arg1;
14
15  return Napi::Number::New(env, sum);
16}
17
18Napi::Object Init(Napi::Env env, Napi::Object exports) {
19  exports.Set(Napi::String::New(env, "sum"),
20              Napi::Function::New(env, Sum));
21  return exports;
22}
23
24NODE_API_MODULE(SumAddon, Init)

Rust

A Rust Node-API Module exporting a sum() function, using the napi.rs binding generator. Example from here.

1#[napi]
2fn add(a: u32, b: u32) -> u32 {
3  a + b
4}

Swift

A Swift Node-API module exporting a sum() function. Heavily inspired by this example.

1import NAPI
2
3func sum(a: Double, b: Double) -> Double {
4    return a + b
5}
6
7@_cdecl("_init_function_arguments")
8func initFunctionArguments(env: OpaquePointer, exports: OpaquePointer) -> OpaquePointer? {
9    return initModule(env, exports, [
10        .function("sum", sum)
11    ])
12}

Existing ecosystem of Node-API native code

With React Native's push for Web conformance, it is vital to make use of existing work where possible. Many Web APIs, such as WebRTC, Web Audio, and Canvas, have been implemented with Node-API. The Hermes team sees this and is eager to adopt Node-API for implementing functionality such as Temporal and Intl.

Supporting Node-API interface will allow for unprecedented code sharing opportunities between the web and React Native ecosystem.

As the time of writing, our project has built-in support for Cmake-based C++ addons through our cmake-rn build tool, conversion of Gyp-based C++ addons through gyp-to-cmake and finally Rust through our ferric build tool.

Perfect use-cases

You would reach for Node-API, if you’re building an app or library and have code which is either:

• shared across multiple platforms, potentially outside of React Native too: databases, sync-engine, shared business logic that you only want to implement once.
• computationally costly: AI inference, classification, encryption, hashing, physics engines, digital signal processing using Fourier transformations or solving differential equations via Laplace transforms - the fun stuff!
• calling into platform APIs: Through an Apple SDK, Android NDK or even JNI. Node-API prebuilds can call into any of the platform APIs provided by the platform build tools.

Using prebuilt Node-API for React Native is less ideal for apps and libraries with native code calling into React Native Core, since they face the same issue as JSI: not being ABI stable. It can be done, using a traditional “sibling” TurboModule or via the JavaScript boundary; which is fine, but potentially less performant.

Work in progress

The PR adding Node-API support to Hermes is a work-in-progress, although most of the actual code is being upstreamed from React Native Windows. Because of this, using React Native Node-API modules require building Hermes from source, using a patched version with the Node-API functions, which incidentally means the app will have to use specific versions of React Native (currently 0.79.1 or 0.79.2).

We expect this restriction to go away as soon as the PR adding Node-API support to Hermes is merged and pulled in by React Native core team.

At the time of writing, the Node-API host module supports only iOS and Android. We want to embrace out-of-tree platforms too and will be gradually extending support for these. Please, reach out if you're an expert on any of these and want to help implement or support this effort.

Join our effort and contribute!

If you, too, get excited about a future of native modules for React Native being prebuilt, fast and backed by binding-generators as well as increased collaboration across the JS ecosystem, we need your help!

You can find all the code and more documentation on how to get started with Node-API modules for React Native via https://github.com/callstackincubator/react-native-node-api

Express your excitement: Through posts and comments spreading the message, starring the repository and reacting with 👍 and 💙 as we continue to move this forward and release improvements.

Take it for a spin: Install an example Node-API into your app, try building a simple Node-API module to get a feel for the simplicity and bettered developer experience and, if you’re feeling particularly adventurous, fork and clone the repo to start working on a good first issue.

If you’re already authoring a native add-on for Node.js, try targeting React Native directly and if you’re already building a native module using JSI, try out the Node-API experience; we firmly believe the benefits from ease of developer experience and ease of maintenance is worth the efforts of switching over for many existing libraries.

We can’t wait to see what you build with this, and we’re here to help you make it happen!