Phase 2: create a real Node-API env via hermes_napi_create_env

Replace the `env = nullptr` stub in CxxNodeApiHostModule with a real
Node-API environment: cast the JSI runtime to `IHermes`, read the
underlying `vm::Runtime*` via `getVMRuntimeUnsafe()`, and create the env
with `hermes_napi_create_env(vm, nullptr)`. The env is owned by the
runtime and cached on the module (shared across all addons).

This flips the Phase 1 baseline abort (`assert(status == napi_ok)` right
after `napi_create_object(env=nullptr, …)`) green: with
`MOCHA_REMOTE_CONTEXT=allTests` the iOS-sim suite now reports 14 passing
(node-addon-examples getting-started incl. the Rust ferric addon,
buffers, async, and a js-native-api node-test).

Linking note: the RN `hermesvm` framework already force-loads
`hermesNapi`, so all `napi_*` runtime symbols are exported and
`hermes_napi_create_env`'s code is present — but the `hermes_napi_*`
public entry points lack the `NAPI_EXTERN` (visibility("default"))
attribute the `napi_*` funcs carry, so Hermes' `-fvisibility=hidden`
stripped them from the export table. `vendor-hermes` now annotates those
declarations in `API/napi/hermes_napi.h` (idempotent) so a clean
framework build exports them. This is an upstream oversight to report to
Hermes; no force_load or second VM copy in our pod is needed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kraenhansen

packages/host/cpp/CxxNodeApiHostModule.cpp

@@ -2,8 +2,19 @@
 #include "Logger.hpp"
 #include "RuntimeNodeApiAsync.hpp"
 
+#include <jsi/hermes-interfaces.h>
+
 using namespace facebook;
 
+// Declared by the vendored Hermes in API/napi/hermes_napi.h. We forward declare
+// it here (rather than including that header) to avoid pulling in Hermes' own
+// node_api.h alongside the weak-node-api copy already included transitively.
+// Only the mangled name matters for linking, so passing host as nullptr is
+// enough — async work / thread-safe functions will return failure until a
+// host integration is wired up (Phase 3).
+struct hermes_napi_host;
+napi_env hermes_napi_create_env(void *hermes_runtime, hermes_napi_host *host);
+
 namespace callstack::react_native_node_api {
 
 CxxNodeApiHostModule::CxxNodeApiHostModule(
@@ -108,8 +119,25 @@ bool CxxNodeApiHostModule::initializeNodeModule(jsi::Runtime &rt,
   // TODO: Read the version from the addon
   // @see
   // https://github.com/callstackincubator/react-native-node-api/issues/4
-  // TODO: Phase 2-3 will replace this with hermes_napi_create_env
-  napi_env env = nullptr;
+
+  // Lazily create the Node-API environment backing this runtime. Hermes binds
+  // an env to its low-level VM runtime, which we reach through the (unstable)
+  // IHermes JSI interface. The env is owned by the runtime and shared across
+  // all addons, so we create it once and cache it.
+  if (env_ == nullptr) {
+    // Fully qualified: `using namespace facebook` makes a bare `hermes`
+    // ambiguous with the top-level `::hermes` (VM) namespace pulled in via
+    // <jsi/hermes-interfaces.h>.
+    auto *hermes = facebook::jsi::castInterface<facebook::hermes::IHermes>(&rt);
+    if (hermes == nullptr) {
+      log_debug("NapiHost: JSI runtime is not castable to IHermes; cannot "
+                "create a Node-API environment");
+      abort();
+    }
+    env_ = hermes_napi_create_env(hermes->getVMRuntimeUnsafe(), nullptr);
+    assert(env_ != nullptr);
+  }
+  napi_env env = env_;
 
   // Create the "exports" object
   napi_value exports;

packages/host/cpp/CxxNodeApiHostModule.hpp

@@ -30,6 +30,11 @@ class JSI_EXPORT CxxNodeApiHostModule : public facebook::react::TurboModule {
   std::unordered_map<std::string, NodeAddon> nodeAddons_;
   std::shared_ptr<facebook::react::CallInvoker> callInvoker_;
 
+  // The Node-API environment backing every addon loaded into this runtime.
+  // Created lazily on first use from the underlying Hermes VM runtime and
+  // shared across all addons (Node-API expects a single env per realm).
+  napi_env env_ = nullptr;
+
   using LoaderPolicy = PosixLoader; // FIXME: HACK: This is temporary workaround
                                     // for my lazyness (work on iOS and Android)
 

packages/host/src/node/cli/hermes.ts

@@ -28,6 +28,42 @@ const platformOption = new Option(
   "The React Native package to vendor Hermes into",
 ).default("react-native");
 
+// The public `hermes_napi_*` entry points declared in `API/napi/hermes_napi.h`
+// lack the export annotation that the `napi_*` functions carry (`NAPI_EXTERN` ==
+// `visibility("default")`). Under Hermes' `-fvisibility=hidden` they are hidden
+// and stripped from the shared `hermesvm` framework, so embedders cannot link
+// `hermes_napi_create_env` even though its code is force-loaded into the
+// framework. Annotate them so they are exported.
+//
+// This is an upstream oversight (a public header entry point that isn't
+// exported) and should be reported to Hermes; until then we patch the vendored
+// checkout. The insertion is idempotent so re-running is safe.
+const EXPORTED_HERMES_NAPI_ENTRY_POINTS = [
+  "hermes_napi_create_env",
+  "hermes_napi_destroy_env",
+  "hermes_napi_get_last_registered_module",
+  "hermes_napi_load_module",
+];
+
+async function exportHermesNapiEntryPoints(hermesPath: string) {
+  const headerPath = path.join(hermesPath, "API", "napi", "hermes_napi.h");
+  const original = await fs.promises.readFile(headerPath, "utf8");
+  const patched = EXPORTED_HERMES_NAPI_ENTRY_POINTS.reduce(
+    (contents, name) =>
+      // A declaration is the only place the name is followed by "(" — doc
+      // comments reference the names without parentheses. The negative
+      // lookbehind keeps this idempotent.
+      contents.replace(
+        new RegExp(`(?<!NAPI_EXTERN )\\b${name}\\(`, "g"),
+        `NAPI_EXTERN ${name}(`,
+      ),
+    original,
+  );
+  if (patched !== original) {
+    await fs.promises.writeFile(headerPath, patched);
+  }
+}
+
 export const command = new Command("vendor-hermes")
   .argument("[from]", "Path to a file inside the app package", process.cwd())
   .option("--silent", "Don't print anything except the final path", false)
@@ -115,6 +151,10 @@ export const command = new Command("vendor-hermes")
           });
         }
       }
+      // Ensure the public Node-API entry points are exported from the shared
+      // framework. Applied unconditionally (idempotent) so an existing checkout
+      // from before this patch also gets fixed.
+      await exportHermesNapiEntryPoints(hermesPath);
       console.log(hermesPath);
     }),
   );