Repository navigation
Ship a node-api library for Node-API addons on Apple and Android - #2310
Draft
kraenhansen wants to merge 6 commits into
Draft
kraenhansen wants to merge 6 commits into
kraenhansen wants to merge 6 commits into
Conversation
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>
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>
kraenhansen
temporarily deployed
to
npm-publish
November 11, 2026 23:07 — with
GitHub Actions
Inactive
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
node-apilibrary next tohermesvmfor Node-API addons to link against instead ofhermesvm, 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_*andnode_api_*functions thathermesvmexports, which are the ones the vendorednode_api.hdeclares withNAPI_VERSION=10andNAPI_EXPERIMENTALunset. JSI, the C++ API and thehermes_napi_*embedder API aren't reachable through it.After
node-apilinks,API/napi/check_node_api.pycompares it with the functionshermesvmexports, for each architecture. If they differ, it fails the build and prints the lines to add or remove.Apple:
node-api.framework, andnode-api.xcframeworkindestroot. It re-exports the functions listed inAPI/napi/node-api.reexportsfromhermesvm, using ld64's-reexported_symbols_list. That gives it a plainLC_LOAD_DYLIBonhermesvm, rather than theLC_REEXPORT_DYLIBthat-reexport_librarywould add and that would re-export everything. ld64 fails the link if the list names somethinghermesvmdoesn't export, and the check covers the other direction.FRAMEWORK_VERSION Akeeps the macOS install name the same when the Hermes major version changes.include/hermes/napiis copied todestroot/include/hermes/napi.Android: two builds of
libnode-api.so:jni/<abi>/defines nothing and is linked with--no-as-needed, so it keeps itsDT_NEEDEDonlibhermesvm.so. bionic searcheslibnode-api.sobeforelibhermesvm.so, so any definitions in it would win. The check also asserts both properties.node-apiprefab module is built fromAPI/napi/node-api-stub.c, which defines each function with a body that traps, because lld doesn't resolve symbols through a dependency'sDT_NEEDED. It's written toHERMES_NODE_API_STUB_DIRand isn't intargets(...), so it isn't packaged. AGP always takes a prefab module's library from the CMake target with the same name (libraryNameonly changesmodule.json), so adoLastonPrefabPackageTaskcopies 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 usesplutil -replaceinstead ofPlistBuddy'sAdd, which fails when the key exists. That made relinking a framework without reconfiguring fail, whichnode-apidoes wheneverhermesvmrelinks.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 withhermesvmwithout adding a dependency, since the build already runs Python.Test Plan
Apple, with
utils/build-apple-framework.shand Xcode 26.2:macosxandiphonesimulatorslices:dyld_info -exportslists exactly 155 entries, each a re-export fromhermesvm.node-apihas anLC_LOAD_DYLIBonhermesvm, the install names are@rpath/node-api.framework/Versions/A/node-apiand@rpath/node-api.framework/node-api, andInfo.plisthasdev.hermesengine.node-api.<platform>and the deployment target.create_universal_frameworkcreateshermesvm.xcframeworkandnode-api.xcframeworkfrom those slices.-framework node-apirecords onlynode-api. A host linked againsthermesvm.frameworkloads it withhermes_napi_load_moduleand getsadd(2, 3) = 5, withhermesvmloaded once.hermesvmandnode-apitwice without reconfiguring succeeds and keeps the deployment target.node-api.reexportsfails the build with the line to add, for each architecture. Adding one thathermesvmdoesn't export fails the link.Android, with
./gradlew :assembleReleaseand NDK 28.2:jni/<abi>/libnode-api.sodepends onlibhermesvm.soand defines none of the 155 functions, andprefab/modules/node-api/libs/android.<abi>/libnode-api.sodefines all 155 and doesn't depend onlibhermesvm.so. Both have the sonamelibnode-api.so.libnode-api.so. A host linked againstlibhermesvm.soloads it with the AAR'sjni/libraries and getsadd(2, 3) = 5, anddlsymthrough the addon's handle resolves its Node-API functions tolibhermesvm.so.node-api-stub.cthathermesvmdoesn'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:
hermes_napi_create_envfails to link againstnode-api.Not included: vendoring
node-api.xcframeworkinhermes-engine.podspec.🤖 Generated with Claude Code