Skip to content

Ship a node-api library for Node-API addons on Apple and Android - #2310

Draft
kraenhansen wants to merge 6 commits into
meta:static_hfrom
kraenhansen:kh/node-api-library
Draft

kraenhansen wants to merge 6 commits into
meta:static_hfrom
kraenhansen:kh/node-api-library

Conversation

@kraenhansen

@kraenhansen kraenhansen commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds a node-api library next to hermesvm for Node-API addons to link against instead of hermesvm, so prebuilt addons record a name that stays the same across Hermes releases. Discussed in #1074 (comment).

It forwards only the Node-API functions: the 155 napi_* and node_api_* functions that hermesvm exports, which are the ones the vendored node_api.h declares with NAPI_VERSION=10 and NAPI_EXPERIMENTAL unset. JSI, the C++ API and the hermes_napi_* embedder API aren't reachable through it.

After node-api links, API/napi/check_node_api.py compares it with the functions hermesvm exports, for each architecture. If they differ, it fails the build and prints the lines to add or remove.

Apple: node-api.framework, and node-api.xcframework in destroot. It re-exports the functions listed in API/napi/node-api.reexports from hermesvm, using ld64's -reexported_symbols_list. That gives it a plain LC_LOAD_DYLIB on hermesvm, rather than the LC_REEXPORT_DYLIB that -reexport_library would add and that would re-export everything. ld64 fails the link if the list names something hermesvm doesn't export, and the check covers the other direction. FRAMEWORK_VERSION A keeps the macOS install name the same when the Hermes major version changes. include/hermes/napi is copied to destroot/include/hermes/napi.

Android: two builds of libnode-api.so:

  • The one in jni/<abi>/ defines nothing and is linked with --no-as-needed, so it keeps its DT_NEEDED on libhermesvm.so. bionic searches libnode-api.so before libhermesvm.so, so any definitions in it would win. The check also asserts both properties.
  • The one in the node-api prefab module is built from API/napi/node-api-stub.c, which defines each function with a body that traps, because lld doesn't resolve symbols through a dependency's DT_NEEDED. It's written to HERMES_NODE_API_STUB_DIR and isn't in targets(...), so it isn't packaged. AGP always takes a prefab module's library from the CMake target with the same name (libraryName only changes module.json), so a doLast on PrefabPackageTask copies the stub over it.

The framework deployment-target step moves into hermes_set_framework_min_os_version, so both frameworks can use it. It now uses plutil -replace instead of PlistBuddy's Add, which fails when the key exists. That made relinking a framework without reconfiguring fail, which node-api does whenever hermesvm relinks.

Considered: generating the stub, either in CMake or with a script outside it (for example TypeScript over the vendored headers or the symbol lists in node-api-headers). Checked-in sources are easier to read and review. The check keeps them in step with hermesvm without adding a dependency, since the build already runs Python.

Test Plan

Apple, with utils/build-apple-framework.sh and Xcode 26.2:

  • macosx and iphonesimulator slices: dyld_info -exports lists exactly 155 entries, each a re-export from hermesvm. node-api has an LC_LOAD_DYLIB on hermesvm, the install names are @rpath/node-api.framework/Versions/A/node-api and @rpath/node-api.framework/node-api, and Info.plist has dev.hermesengine.node-api.<platform> and the deployment target.
  • create_universal_framework creates hermesvm.xcframework and node-api.xcframework from those slices.
  • macOS: an addon linked with -framework node-api records only node-api. A host linked against hermesvm.framework loads it with hermes_napi_load_module and gets add(2, 3) = 5, with hermesvm loaded once.
  • Relinking hermesvm and node-api twice without reconfiguring succeeds and keeps the deployment target.
  • Removing a function from node-api.reexports fails the build with the line to add, for each architecture. Adding one that hermesvm doesn't export fails the link.

Android, with ./gradlew :assembleRelease and NDK 28.2:

  • For all four ABIs, jni/<abi>/libnode-api.so depends on libhermesvm.so and defines none of the 155 functions, and prefab/modules/node-api/libs/android.<abi>/libnode-api.so defines all 155 and doesn't depend on libhermesvm.so. Both have the soname libnode-api.so.
  • arm64 emulator: an addon linked against the prefab module records only libnode-api.so. A host linked against libhermesvm.so loads it with the AAR's jni/ libraries and gets add(2, 3) = 5, and dlsym through the addon's handle resolves its Node-API functions to libhermesvm.so.
  • Adding a function to node-api-stub.c that hermesvm doesn't export fails the build with the line to remove. Run directly, the script also fails for a stub with a function removed, and when given the stub in place of the runtime library.

Both:

  • An addon that calls hermes_napi_create_env fails to link against node-api.
  • The other Apple slices and the Android debug variants, in CI.
  • An addon in a React Native app.

Not included: vendoring node-api.xcframework in hermes-engine.podspec.

🤖 Generated with Claude Code

kraenhansen and others added 3 commits November 11, 2026 11:22
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Re-exports only the Node-API functions from hermesvm, using
-reexported_symbols_list, so prebuilt addons can link against a library
whose name doesn't change with Hermes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
libnode-api.so is packaged for runtime and depends on libhermesvm.so
without defining anything. The prefab module gets a stub with the same
soname that defines every function, for addons to link against.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@meta-cla meta-cla Bot added the CLA Signed Do not delete this pull request or issue due to inactivity. label Nov 11, 2026
kraenhansen and others added 3 commits November 11, 2026 15:01
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PlistBuddy's Add fails when the key exists, so relinking a framework
without reconfiguring failed. plutil -replace adds or overwrites it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replaces generating C from CMake with a checked-in stub and ld64 list,
and a POST_BUILD script that compares them with what hermesvm exports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
npm-publish — 5814d9f5 Deployed Nov 11, 2026 by kraenhansen via publish #1722
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed Do not delete this pull request or issue due to inactivity.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant