Node-API Modules
for React Native

Write once, run anywhere:
Build native modules for React Native with Node-API.

Getting started

Warning

This library is still under active development. Feel free to hack around, but use at your own risk.

How does this work?

Important

This library builds Hermes from a pinned commit on its static_h branch, which carries Hermes' first-party Node-API implementation. React Native has not shipped that Hermes yet, so the range of supported React Native versions is very limited — see the react-native peer dependency of the host package for the version we currently build against. We expect this restriction to be lifted once React Native ships a Hermes with Node-API included.

Note

This library only works for iOS and Android and we want to eventually support React Native for Windows, macOS, visionOS and other out-of-tree platforms too.

See the document on "how it works" for a detailed description of what it's like to write native modules using this package.

Packages

This mono-repository hosts the development of a few packages:

react-native-node-api

Responsible for adding Node-API support to your React Native application:

• Declares a Podspec which vendors Hermes from a pinned commit on its static_h branch, where Node-API is implemented,
  • instructing React Native's Hermes Podspecs to compile from this checkout.
  • we expect this to eventually be removed, as React Native starts shipping a Hermes with Node-API included.
• Automatically discovers and adds Node-API binaries, matching the the prebuilt binary specification
  • This is driven by the platform specific build tools (through the Podspec on iOS and eventually Gradle on Android)
• Implements a TurboModule with a requireNodeAddon function responsible for
  • Loading dynamic libraries
  • Node-API module registration and (per jsi::Runtime) initialization.
• Provides ways of transforming require("./addon.node") and require("bindings")("addon") calls into requireNodeAddon calls.

Note: We'll sometimes refer to this as the "host package", as it can be seen as a host of Node-API modules in React Native apps.

cmake-rn

A wrapper around CMake making it easier to produce prebuilt binaries targeting iOS and Android matching the the prebuilt binary specification.

Serves the same purpose as cmake-js does for the Node.js community and could potentially be upstreamed into cmake-js eventually.

ferric-cli

A wrapper around Cargo making it easier to produce prebuilt binaries targeting iOS and Android matching the the prebuilt binary specification as well as napi.rs to generate Node-API bindings from annotated Rust code.

gyp-to-cmake

A tool to transform binding.gyp files into CMakeLists.txt files, intended for cmake-js or cmake-rn to build from.

@react-native-node-api/node-addon-examples

A wrapper around the examples in the nodejs/node-addon-examples repo, using gyp-to-cmake and cmake-rn to prepare prebuilds and scaffolding for loading the addons.

The main purpose is to use these as tests to verify the implementation. We choose to use this as our first signal for compliance, over the js-native-api tests in the Node.js project, because the examples depends much less on Node.js built-in runtime APIs.

@react-native-node-api/test-app

A test app using react-native-test-app to exercise the implementation of it all.

@react-native-node-api/ferric-example

A simple example of using the ferric CLI to build a Node-API module for React Native in Rust.