Merge branch 'main' into improve-build

dougg0k · web-flow · commit d29bcb5fe462 · 2025-09-01T11:48:02.000-03:00
diff --git a/.changeset/cyan-sloths-move.md b/.changeset/cyan-sloths-move.md
diff --git a/.changeset/kind-forks-talk.md b/.changeset/kind-forks-talk.md
diff --git a/.changeset/loud-dodos-kneel.md b/.changeset/loud-dodos-kneel.md
diff --git a/.changeset/loud-paths-eat.md b/.changeset/loud-paths-eat.md
diff --git a/.changeset/rich-donuts-mix.md b/.changeset/rich-donuts-mix.md
diff --git a/.changeset/shiny-hotels-wink.md b/.changeset/shiny-hotels-wink.md
diff --git a/.changeset/stale-coins-drop.md b/.changeset/stale-coins-drop.md
diff --git a/.changeset/strong-eggs-yell.md b/.changeset/strong-eggs-yell.md
diff --git a/README.md b/README.md
@@ -54,6 +54,10 @@ A wrapper around CMake making it easier to produce [prebuilt binaries](./docs/PR
 
 Serves the same purpose as `cmake-js` does for the Node.js community and could potentially be upstreamed into `cmake-js` eventually.
 
+### [`ferric-cli`](packages/ferric)
+
+A wrapper around [Cargo](https://doc.rust-lang.org/cargo/) making it easier to produce prebuilt binaries targeting iOS and Android matching the the prebuilt binary specification as well as [napi.rs](https://napi.rs/) to generate Node-API bindings from annotated Rust code.
+
 ### [`gyp-to-cmake`](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.
@@ -67,3 +71,7 @@ The main purpose is to use these as tests to verify the implementation. We choos
 ### [`@react-native-node-api/test-app`](apps/test-app)
 
 A test app using `react-native-test-app` to exercise the implementation of it all.
+
+### [`@react-native-node-api/ferric-example`](packages/ferric-example)
+
+A simple example of using the `ferric` CLI to build a Node-API module for React Native in Rust.
diff --git a/apps/test-app/CHANGELOG.md b/apps/test-app/CHANGELOG.md
@@ -1,5 +1,18 @@
 # react-native-node-api-test-app
 
+## 0.1.2
+
+### Patch Changes
+
+- dc33f3c: Added implementation of async work runtime functions
+- Updated dependencies [a477b84]
+- Updated dependencies [dc33f3c]
+- Updated dependencies [4924f66]
+- Updated dependencies [acf1a7c]
+  - react-native-node-api@0.3.3
+  - @react-native-node-api/node-tests@undefined
+  - @react-native-node-api/node-addon-examples@undefined
+
 ## 0.1.1
 
 ### Patch Changes
diff --git a/apps/test-app/package.json b/apps/test-app/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@react-native-node-api/test-app",
   "private": true,
-  "version": "0.1.1",
+  "version": "0.1.2",
   "scripts": {
     "metro": "react-native start --no-interactive",
     "android": "react-native run-android --no-packager --active-arch-only",
diff --git a/docs/ANDROID.md b/docs/ANDROID.md
@@ -4,6 +4,35 @@
 
 Because we're using a version of Hermes patched with Node-API support, we need to build React Native from source.
 
+Follow [the React Native documentation on how to build from source](https://reactnative.dev/contributing/how-to-build-from-source#update-your-project-to-build-from-source).
+
+In particular, you will have to edit the `android/settings.gradle` file as follows:
+
+> ```diff
+> // ...
+> include ':app'
+> includeBuild('../node_modules/@react-native/gradle-plugin')
+>
+> + includeBuild('../node_modules/react-native') {
+> +     dependencySubstitution {
+> +         substitute(module("com.facebook.react:react-android")).using(project(":packages:react-native:ReactAndroid"))
+> +         substitute(module("com.facebook.react:react-native")).using(project(":packages:react-native:ReactAndroid"))
+> +         substitute(module("com.facebook.react:hermes-android")).using(project(":packages:react-native:ReactAndroid:hermes-engine"))
+> +         substitute(module("com.facebook.react:hermes-engine")).using(project(":packages:react-native:ReactAndroid:hermes-engine"))
+> +     }
+> + }
+> ```
+
+To download our custom version of Hermes, you need to run from your app package:
+
+```
+npx react-native-node-api vendor-hermes
+```
+
+This will print a path which needs to be stored in `REACT_NATIVE_OVERRIDE_HERMES_DIR` to instruct the React Native Gradle scripts to use it.
+
+This can be combined into a single line:
+
 ```
 export REACT_NATIVE_OVERRIDE_HERMES_DIR=`npx react-native-node-api vendor-hermes --silent`
 ```
diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.md
@@ -33,14 +33,6 @@ module.exports = require("react-native-node-api").requireNodeAddon(
 > In the time of writing, this code only supports iOS as passes the path to the library with its .framework.
 > We plan on generalizing this soon 🤞
 
-### A note on the need for path-hashing
-
-Notice that the `requireNodeAddon` call doesn't reference the library by it's original name (`prebuild.node`) but instead a name containing a hash.
-
-In Node.js dynamic libraries sharing names can be disambiguated based off their path on disk. Dynamic libraries added to an iOS application are essentially hoisted and occupy a shared global namespace. This leads to collisions and makes it impossible to disambiguate multiple libraries sharing the same name. We need a way to map a require call, referencing the library by its path relative to the JS file, into a unique name of the library once it's added into the application.
-
-To work around this issue, we scan for and copy any library (including its entire xcframework structure with nested framework directories) from the dependency package into our host package when the app builds and reference these from its podspec (as vendored_frameworks). We use a special file in the xcframeworks containing Node-API modules. To avoid collisions we rename xcframework, framework and library files to a unique name, containing a hash. The hash is computed based off the package-name of the containing package and the relative path from the package root to the library file (with any platform specific file extensions replaced with the neutral ".node" extension).
-
 ## Transformed code calls into `react-native-node-api`, loading the platform specific dynamic library
 
 The native implementation of `requireNodeAddon` is responsible for loading the dynamic library and allow the Node-API module to register its initialization function, either by exporting a `napi_register_module_v1` function or by calling the (deprecated) `napi_module_register` function.
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -17,16 +17,15 @@ The app developer has to install both `calculator-lib` as well as `react-native-
 The reason for the latter is a current limitation of the React Native Community CLI which doesn't consider transitive dependencies when enumerating packages for auto-linking.
 
 > [!WARNING]
-> It's important to match the exact version of the `react-native-node-api` declared as peer dependency by `calculator-lib`.
+> It's important to match the version range of the `react-native-node-api` declared as a peer dependency by `calculator-lib`.
 
-For the app to resolve the Node-API dynamic library files, the app developer must update their Metro config to use a `resolveRequest` function exported from `react-native-node-api`:
+For the app to resolve the Node-API dynamic library files, the app developer must update their Babel config to use a `requireNodeAddon` function exported from `react-native-node-api`:
 
 ```javascript
-const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
-const nodeApi = require("react-native-node-api/metro-config");
-module.exports = mergeConfig(getDefaultConfig(__dirname), {
-  resolver: { resolveRequest: nodeApi.resolveRequest },
-});
+module.exports = {
+  presets: ["module:@react-native/babel-preset"],
+  plugins: ["module:react-native-node-api/babel-plugin"], // 👈 This needs to be added to the babel.config.js of the app
+};
 ```
 
 At some point the app code will import (or require) the entrypoint of `calculator-lib`:
@@ -121,18 +120,36 @@ NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
 }
 ```
 
-### Build the prebuilt binaries
+```cmake
+# CMakeLists.txt
 
-```
-npx react-native-node-api build ./addon.c
+cmake_minimum_required(VERSION 3.15...3.31)
+project(addon)
+
+add_compile_definitions(-DNAPI_VERSION=4)
+
+file(GLOB SOURCE_FILES "addon.c")
+
+add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES} ${CMAKE_JS_SRC})
+set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
+target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_JS_INC})
+target_link_libraries(${PROJECT_NAME} PRIVATE ${CMAKE_JS_LIB})
+target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_17)
+
+if(MSVC AND CMAKE_JS_NODELIB_DEF AND CMAKE_JS_NODELIB_TARGET)
+  # Generate node.lib
+  execute_process(COMMAND ${CMAKE_AR} /def:${CMAKE_JS_NODELIB_DEF} /out:${CMAKE_JS_NODELIB_TARGET} ${CMAKE_STATIC_LINKER_FLAGS})
+endif()
 ```
 
-This is a shorthand command which generates a CMake project from the single source-file and prebuilds for both the Apple and Android platforms. See the [CLI documentation](./CLI.md) for more information on the options available and [documentation on prebuilds](./PREBUILDS.md) for the specifics on their format and structure.
+### Build the prebuilt binaries
 
-<!-- TODO: Add a listing of the files produced when running command: Some temp (cached) CMakeList.txt, the CMake project dir, 2x platform specific prebuild directories -->
+```
+npx cmake-rn
+```
 
 ### Load and export the native module
 
 ```javascript
-module.exports = require("./prebuild.node");
+module.exports = require("./build/Release/addon.node");
 ```
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -54,7 +54,7 @@
     "globals": "^16.0.0",
     "prettier": "^3.6.2",
     "react-native": "0.79.5",
-    "tsx": "^4.20.3",
+    "tsx": "^4.20.5",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.38.0"
   }
diff --git a/packages/cmake-rn/CHANGELOG.md b/packages/cmake-rn/CHANGELOG.md
@@ -1,5 +1,20 @@
 # cmake-rn
 
+## 0.3.0
+
+### Minor Changes
+
+- 8557768: Derive default targets from the CMAKE_RN_TARGETS environment variable
+
+### Patch Changes
+
+- 4924f66: Refactor into a platform abstraction
+- Updated dependencies [a477b84]
+- Updated dependencies [dc33f3c]
+- Updated dependencies [4924f66]
+- Updated dependencies [acf1a7c]
+  - react-native-node-api@0.3.3
+
 ## 0.2.3
 
 ### Patch Changes
diff --git a/packages/cmake-rn/README.md b/packages/cmake-rn/README.md
@@ -1,5 +1,5 @@
 # `cmake-rn`
 
-A wrapper around Cmake making it easier to produce prebuilt binaries targeting iOS and Android matching the [the prebuilt binary specification](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md).
+A wrapper around Cmake making it easier to produce prebuilt binaries targeting iOS and Android matching [the prebuilt binary specification](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md).
 
 Serves the same purpose as `cmake-js` does for the Node.js community and could potentially be upstreamed into `cmake-js` eventually.
diff --git a/packages/cmake-rn/package.json b/packages/cmake-rn/package.json
@@ -1,6 +1,6 @@
 {
   "name": "cmake-rn",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Build React Native Node API modules with CMake",
   "homepage": "https://github.com/callstackincubator/react-native-node-api",
   "repository": {
@@ -28,7 +28,7 @@
     "cmake-js": "^7.3.1",
     "commander": "^13.1.0",
     "ora": "^8.2.0",
-    "react-native-node-api": "0.3.2"
+    "react-native-node-api": "0.3.3"
   },
   "peerDependencies": {
     "node-addon-api": "^8.3.1",
diff --git a/packages/ferric-example/CHANGELOG.md b/packages/ferric-example/CHANGELOG.md
@@ -0,0 +1,7 @@
+# @react-native-node-api/ferric-example
+
+## 0.1.1
+
+### Patch Changes
+
+- a7cc35a: Updated napi packages.
diff --git a/packages/ferric-example/package.json b/packages/ferric-example/package.json
@@ -2,7 +2,7 @@
   "name": "@react-native-node-api/ferric-example",
   "private": true,
   "type": "commonjs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "homepage": "https://github.com/callstackincubator/react-native-node-api",
   "repository": {
     "type": "git",
diff --git a/packages/ferric/CHANGELOG.md b/packages/ferric/CHANGELOG.md
@@ -1,5 +1,21 @@
 # ferric-cli
 
+## 0.3.0
+
+### Minor Changes
+
+- 8557768: Derive default targets from the FERRIC_TARGETS environment variable
+
+### Patch Changes
+
+- e613efe: Fixed cargo build release flag
+- a7cc35a: Updated napi packages.
+- Updated dependencies [a477b84]
+- Updated dependencies [dc33f3c]
+- Updated dependencies [4924f66]
+- Updated dependencies [acf1a7c]
+  - react-native-node-api@0.3.3
+
 ## 0.2.3
 
 ### Patch Changes
diff --git a/packages/ferric/README.md b/packages/ferric/README.md
@@ -1,6 +1,6 @@
 # `ferric` (ESM Module)
 
-A wrapper around Cargo making it easier to produce prebuilt binaries targeting iOS and Android matching the [the prebuilt binary specification](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md) as well as [napi.rs](https://napi.rs/) to generate bindings from annotated Rust code.
+A wrapper around Cargo making it easier to produce prebuilt binaries targeting iOS and Android matching [the prebuilt binary specification](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/PREBUILDS.md) as well as [napi.rs](https://napi.rs/) to generate bindings from annotated Rust code.
 
 ## Install the project
 
diff --git a/packages/ferric/package.json b/packages/ferric/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ferric-cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Rust Node-API Modules for React Native",
   "homepage": "https://github.com/callstackincubator/react-native-node-api",
   "repository": {
@@ -22,6 +22,6 @@
     "chalk": "^5.4.1",
     "commander": "14.0.0",
     "ora": "^8.2.0",
-    "react-native-node-api": "0.3.2"
+    "react-native-node-api": "0.3.3"
   }
 }
diff --git a/packages/host/CHANGELOG.md b/packages/host/CHANGELOG.md
@@ -1,5 +1,14 @@
 # react-native-node-api
 
+## 0.3.3
+
+### Patch Changes
+
+- a477b84: Added implementation of napi_fatal_error, napi_get_node_version and napi_get_version. Improved the Logger functionalities
+- dc33f3c: Added implementation of async work runtime functions
+- 4924f66: Refactor into a platform abstraction
+- acf1a7c: Treating failures when scanning filesystems for Node-API prebuilds more gracefully
+
 ## 0.3.2
 
 ### Patch Changes
diff --git a/packages/host/package.json b/packages/host/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-native-node-api",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Node-API for React Native",
   "homepage": "https://github.com/callstackincubator/react-native-node-api",
   "repository": {
diff --git a/packages/node-tests/package.json b/packages/node-tests/package.json
@@ -22,7 +22,7 @@
     "cmake-rn": "*",
     "gyp-to-cmake": "*",
     "prebuildify": "^6.0.1",
-    "react-native-node-api": "^0.3.2",
+    "react-native-node-api": "^0.3.3",
     "read-pkg": "^9.0.1",
     "rolldown": "1.0.0-beta.29"
   }
