Upstreaming the Node-API host into React Native core ☂️

Start by reading cpp/HermesNapiHost.cpp and cpp/RuntimeNodeApi.cpp, then review #222, #91, #368, #412 and the weak-node-api discussion. This issue is done only when the minimum upstream boundary, prerequisites, and unresolved scheduling, environment, and addon-linking questions are settled into a proposal.

A tracking issue for a long-term ambition: propose the core of this project — creating a Node-API environment and loading an addon into it — for inclusion in React Native itself, and keep the build tooling here.

Nothing here is committed to. The point is to have one place to argue about the seam, and to record what has to be true before a proposal is worth writing.

Why the cut is worth making

The repo currently spans two quite different kinds of work:

1. A runtime capability. A TurboModule (CxxNodeApiHostModule) that creates a napi_env per addon, loads a dynamic library into it, and supplies the host primitives Node-API needs but React Native has no equivalent of — async work, thread-safe function dispatch, fatal-error routing (HostContext in cpp/HermesNapiHost.cpp, cpp/RuntimeNodeApi.cpp).
2. A build system. cmake-rn, ferric, gyp-to-cmake, the autolinking CLI, the Babel plugin, the prebuild naming and packaging conventions.

(1) is small, general, and belongs anywhere React Native runs. (2) is opinionated, iterates fast, and is a much bigger ask to hand to another project. Asking core to adopt both is likely to sink the whole proposal; asking for (1) alone is close to a one-sentence pitch.

The seam: loading an addon

The natural boundary is the loading primitive itself — the thing #222 describes as a process.dlopen analogue. Core would own "given a reference to an addon, load it and give me its exports"; everything that decides the reference stays here.

Two things to get right in a proposal:

It cannot honestly be process.dlopen(module, filename). Node's takes an absolute filesystem path. On neither of our platforms is there one: on Android the library is lib<name>.so resolved by the dynamic linker out of the APK, on Apple it is @rpath/<name>.framework/<name>. A dlopen-named API that does not accept a path will cost the proposal a long argument about its name. Something honest — load a Node-API addon by library name, resolved the platform's way — is both defensible and a smaller API surface, and the path-shaped case can be an extension later if it ever makes sense.

The naming must not leak across the seam. Whatever core accepts has to be free of our library-name mangling (see #222, #91 and the manifest discussion in #368). If the strategy leaks upstream, we can never change it.

What already argues in favor

• Hermes implements Node-API itself. The engine at our pinned commit ships the whole surface, plus hermes_napi_create_env and hermes_napi_load_module, which we now use directly (#445). The upstream ask reduces to "expose what the engine already does", not "implement Node-API".
• #412 — once React Native ships a Hermes with Node-API, we stop vendoring, and the remaining host code is small enough to read in one sitting.
• The frameworks are no longer preloaded (#351), so addons load on demand and the loading path is ordinary, not a startup-order special case.

The weak-node-api problem

This is the main obstacle, and it is not build tooling, so it does not fall cleanly on our side of the cut.

Addons are compiled independently of any app, so they cannot link against the app's Hermes. Today they link weak-node-api: generated forwarding stubs for every Node-API symbol, backed by a function table the host injects at startup. If the host moves to core, addons still need something to link, and "core gains one TurboModule method" turns into "core gains a method and takes on a shim package" — a much harder sell.

The long-term dissolution is nodejs/node#60916 ("node-api: use v-table to reverse module dependencies", @vmoroz), which inverts the dependency: the runtime exposes its API through vtables reachable from napi_env, and an addon built with NODE_API_MODULE_USE_VTABLE links against nothing at all. That removes the reason weak-node-api exists, and with it the awkward part of the cut. It is upstream, open, and not something to plan a schedule around — but it is the shape of the end state, and worth tracking here.

Until then, options worth thinking through:

• Keep weak-node-api as a peer package here and propose only the host to core, accepting that addons still need our shim to build.
• Have addons link the Hermes/React Native framework directly where the platform allows it, and keep the shim only where it does not.
• Wait for the vtable work and propose the whole thing once addons link nothing.

Prerequisites on our side

Roughly in order, and all independently useful:

• A raw, naming-free loading API in JS — the shape core would eventually own (#222).
• A friendly resolver layered on top of it, taking { packageName, path } (#222, #91).
• Make the library name data rather than a shared algorithm — a manifest emitted by the linking step (getLibraryMap() already computes exactly this map) so JS and the linker cannot disagree, and so per-library overrides (#368) have somewhere to live.
• Stop vendoring Hermes (#412).
• Settle the addon-declared Node-API version question, which needs an upstream Hermes change either way (#4).

Open questions

• Does HostContext's threading model (a process-global worker pool plus CallInvoker dispatch) survive contact with core's own scheduling, or would core want to back those primitives differently?
• Is the per-addon napi_env (as in Node) the right model for core, given a React Native app can have several runtimes over its lifetime?
• What is the minimum viable proposal — the TurboModule alone, or does it only make sense together with autolinking, so that an app can actually get an addon into its bundle?

Related

#222, #91, #368, #412, #4, #3, #104