DOCSEARCHbyAlgolia
Submit Docs

react-native-node-api

repository·next·Indexed 41 days ago

https://github.com/callstackincubator/react-native-node-api

A framework for building and running Node-API native modules within React Native applications, enabling code reuse between Node.js and mobile environments. It leverages a custom version of the Hermes engine to provide Node-API compatibility on iOS and Android. The ecosystem includes tools like cmake-rn for producing prebuilt binaries, ferric for Rust-based binary production, and gyp-to-cmake for converting binding.gyp files to CMakeLists.txt.

Tokens
33.6K
Snippets
112
Records
142
Agent score
52%

What's inside react-native-node-api

  1. Overview of Node-API Modules for React Native

    next

    This project enables developers to build native modules for React Native using the standard Node-API. This allows for a "write once, run anywhere" approach where native modules written for Node.js can be used within React Native applications.

    Key Concepts

    • Node-API Compatibility: The library leverages a specific version of the Hermes engine (from the static_h branch) that includes a first-party Node-API implementation.
    • Platform Support: Currently supports iOS and Android. Future support is planned for Windows, macOS, visionOS, and other platforms.
    • Host Package: The react-native-node-api package acts as a host that manages Hermes configuration, discovers Node-API binaries, and provides a TurboModule to load them.

  5. Understand the purpose of @react-native-node-api/node-addon-examples

    next

    The @react-native-node-api/node-addon-examples package is a wrapper around the official nodejs/node-addon-examples repository.

    Its primary roles are:

    1. Compliance Testing: It serves as a primary signal for verifying the Node-API implementation. It is preferred over js-native-api tests because it has fewer dependencies on Node.js built-in runtime APIs.
    2. Scaffolding: It uses gyp-to-cmake and cmake-rn to prepare prebuilds and scaffolding required to load these addons in a React Native environment.
    3. Verification: Since the original examples use console.log instead of formal assertions, this package wraps the loading of the example JavaScript code with a console.log stub implementation that buffers and asserts the messages printed by the addon.

  7. Package ecosystem and tools

    next

    The repository is a monorepo containing several specialized tools for building and testing Node-API modules for React Native:

    PackagePurpose
    react-native-node-apiThe host package that adds Node-API support to React Native apps.
    cmake-rnA CMake wrapper for producing prebuilt binaries targeting iOS and Android. Similar to cmake-js for Node.js.
    ferric-cliA Cargo wrapper for producing prebuilt binaries and using napi.rs to generate bindings from Rust.
    gyp-to-cmakeA tool to transform binding.gyp files into CMakeLists.txt files.
    @react-native-node-api/node-addon-examplesA wrapper around Node.js addon examples used for verifying implementation compliance.
    @react-native-node-api/test-appA test application used to exercise the entire implementation.
    @react-native-node-api/ferric-exampleA simple example demonstrating how to use ferric to build a Rust-based Node-API module.

  8. What is Weak Node-API and why use it?

    next

    Weak Node-API provides a clean, linkable interface for Node-API that uses runtime-injectable implementations.

    It is specifically designed to solve symbol linking issues on Android, where the dynamic linker restricts access to global symbols. In environments like React Native, where the Node-API implementation might be split between different runtimes (e.g., Hermes and a host runtime), standard native addons would normally need to explicitly link against all possible implementations to avoid undefined symbol errors.

    Weak Node-API solves this by:

    • Exposing only the Node-API function signatures without providing the actual implementation.
    • Allowing the host runtime to inject the real implementation at runtime.
    • Eliminating the requirement for addons to suppress undefined symbol errors during the linking process.

  9. What is the CMake File API and how does it work?

    next

    The CMake File API is an interface used to query CMake's configuration and project information. It operates using a file-based communication pattern:

    1. Queries: Client tools write query files into a specific directory.
    2. Processing: CMake reads these files during the configuration step.
    3. Replies: CMake writes reply files containing the requested information.
    4. Consumption: Client tools read these reply files to extract project metadata.

    The API is versioned. The current version is v1, and all API-related files are located in the .cmake/api/v1 directory within your CMake build directory.

  11. How react-native-node-api works

    next

    The react-native-node-api package (the "host package") provides the infrastructure required to run Node-API modules in a React Native environment through several mechanisms:

    1. Hermes Customization: It declares a Podspec that vendors a pinned commit of Hermes from its static_h branch. This specific branch contains the Node-API implementation required for these modules to function.
    2. Binary Discovery: It automatically discovers and adds Node-API binaries that adhere to the project's prebuilt binary specification. This is handled via platform-specific build tools (Podspecs on iOS and eventually Gradle on Android).
    3. TurboModule Implementation: It implements a TurboModule containing a requireNodeAddon function. This function is responsible for:
      • Loading dynamic libraries.
      • Registering Node-API modules.
      • Initializing modules per jsi::Runtime.
    4. Module Loading Transformation: It provides mechanisms to transform standard Node.js loading patterns, such as require("./addon.node") or require("bindings")("addon"), into calls to requireNodeAddon.

  12. How auto-linking works in react-native-node-api

    next

    The react-native-node-api package (the host package) automatically detects and links prebuilt binaries from dependencies that contain Node-API modules.

    During this process, binaries are 'vendored' (copied) from the dependency's location into the host package. To prevent naming collisions—since multiple dependency packages might contain library files with the same name—the host package renames these files during the copy process using a specific naming scheme.