Skip to content

docs(weak-node-api): update outdated rationale in README #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kraenhansen merged 3 commits into from
Nov 1, 2026
Merged

docs(weak-node-api): update outdated rationale in README #489

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
719a0f1
docs(weak-node-api): update outdated rationale in README
kraenhansen Oct 31, 2026
086660b
ci: trigger checks with weak-node-api label
kraenhansen Oct 31, 2026
f80fff1
docs(weak-node-api): link the vtable proposal as the long-term solution
kraenhansen Oct 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions packages/weak-node-api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,16 @@ This package is part of the [Node-API for React Native](https://github.com/calls

## Why is this needed?

Android's dynamic linker restricts access to global symbols—dynamic libraries must explicitly declare dependencies as `DT_NEEDED` to access symbols. In the context of React Native, the Node-API implementation is split between Hermes and a host runtime, native addons built for Android would otherwise need to explicitly link against both - which is not ideal for multiple reasons.
Android's dynamic linker restricts access to global symbols—dynamic libraries must explicitly declare dependencies as `DT_NEEDED` to access symbols. In the context of React Native, Node-API is implemented by Hermes, but native addons are compiled independently of any app, so they have no specific Hermes to link against.

This library provides a solution by:

- Exposing only Node-API functions without implementation
- Allowing runtime injection of the actual implementation by the host
- Allowing runtime injection of the actual implementation by the host, which is also how the host's `napi_fatal_error` override, logging to logcat on Android, reaches addons
- Eliminating the need for addons to suppress undefined symbol errors

[nodejs/node#60916](https://github.com/nodejs/node/pull/60916) proposes a better long-term solution: the runtime exposes Node-API through vtables reachable from `napi_env`, so an addon links against nothing and this library is no longer needed.

## Is this usable in the context of Node.js?

While originally designed for React Native's split Node-API implementation, this approach could potentially be adapted for Node.js scenarios where addons need to link with undefined symbols allowed. Usage patterns and examples for Node.js contexts are being explored and this pattern could eventually be upstreamed to Node.js itself, benefiting the broader Node-API ecosystem.
While originally designed for React Native's then-split Node-API implementation, this approach could potentially be adapted for Node.js scenarios where addons need to link with undefined symbols allowed. Usage patterns and examples for Node.js contexts are being explored and this pattern could eventually be upstreamed to Node.js itself, benefiting the broader Node-API ecosystem.
Loading