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](https://github.com/nodejs/node/pull/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