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 is currently dependent on a custom version of Hermes and therefore has a very limited range of supported React Native versions. Once the PR adding Node-API support to Hermes merges, we expect this restriction to be lifted.

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:

packages/react-native-node-api

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

• Declares a Podspec which downloads a special version of Hermes, with Node-API support,
  • instructing React Native's Hermes Podspecs to compile from this custom source-code.
  • patching React Native's JSI copy, with the updates introduced by our special version of Hermes.
  • we expect this to eventually be removed, as Node-API support gets merged into Hermes upstream.
• 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.

packages/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.

packages/gyp-to-cmake

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

packages/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.

apps/test-app

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