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:
- 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).
- 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
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:
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
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:
CxxNodeApiHostModule) that creates anapi_envper 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 (HostContextincpp/HermesNapiHost.cpp,cpp/RuntimeNodeApi.cpp).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.dlopenanalogue. 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 islib<name>.soresolved by the dynamic linker out of the APK, on Apple it is@rpath/<name>.framework/<name>. Adlopen-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_napi_create_envandhermes_napi_load_module, which we now use directly (Load addons through Hermes'hermes_napi_load_module#445). The upstream ask reduces to "expose what the engine already does", not "implement Node-API".The
weak-node-apiproblemThis 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 withNODE_API_MODULE_USE_VTABLElinks against nothing at all. That removes the reasonweak-node-apiexists, 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:
weak-node-apias a peer package here and propose only the host to core, accepting that addons still need our shim to build.Prerequisites on our side
Roughly in order, and all independently useful:
requireNodeAddonto take the package name and extension-less path of an addon #222).{ packageName, path }(RefactorrequireNodeAddonto take the package name and extension-less path of an addon #222, ExtendrequireNodeAddon(path)to support more use-cases #91).getLibraryMap()already computes exactly this map) so JS and the linker cannot disagree, and so per-library overrides (Package specific configuration (for apps and libraries) #368) have somewhere to live.Open questions
HostContext's threading model (a process-global worker pool plusCallInvokerdispatch) survive contact with core's own scheduling, or would core want to back those primitives differently?napi_env(as in Node) the right model for core, given a React Native app can have several runtimes over its lifetime?Related
#222, #91, #368, #412, #4, #3, #104