Repository navigation
napi: re-sync public N-API headers from Node.js 26 - #36804
Conversation
The four public N-API headers in src/runtime/napi/ are copied verbatim
from nodejs/node@v26.x, keeping Bun's single intentional divergence
(typedef struct NapiEnv* napi_env).
This brings in:
- node_api_basic_env / node_api_nogc_env / node_api_basic_finalize /
node_api_nogc_finalize / node_api_noenv_finalize typedefs
- NAPI_CDECL, napi_cleanup_hook, node_api_addon_get_api_version_func
- the modern NAPI_MODULE_INIT() that emits
node_api_module_get_api_version_v1, so hosts can detect an addon's
NAPI_VERSION (the previous macro used the deprecated
napi_module_register constructor path and exported no version hook)
- NAPI_VERSION >= 9 gates for node_api_symbol_for /
node_api_{create,throw}_syntax_error / node_api_get_module_file_name
(were NAPI_EXPERIMENTAL)
- declarations for node_api_post_finalizer and
node_api_create_buffer_from_arraybuffer (implementations already
existed in napi.cpp)
- the NODE_API_EXPERIMENTAL_HAS_* feature-detection macros
Bun compiles its own N-API implementation with NAPI_EXPERIMENTAL
defined; with the upstream headers that would make node_api_basic_env a
const-qualified alias (breaking every napi.cpp signature) and emit a
#warning (breaking -Werror). Defining
NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT and
NODE_API_EXPERIMENTAL_NO_WARNING in the build flags keeps
node_api_basic_env == napi_env for the implementation, the same
approach the existing test addons already use.
The redundant local node_api_noenv_finalize typedef in napi.cpp is
dropped now that the public header defines it unconditionally.
|
Warning Review limit reached
Next review available in: 12 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (3)
WalkthroughChangesThe PR updates Node-API headers with version gates, calling conventions, environment types, registration symbols, and experimental APIs. It adds external SharedArrayBuffer finalization and validates Node 26 header compatibility through native compilation and loading. Node-API compatibility
Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@test/napi/napi-value-ffi.test.ts`:
- Around line 97-115: Update the Bun.spawn result handling around compile.stderr
and compile.exited to consume compile.stdout concurrently as well, then assert
the collected stdout, stderr, and exitCode together while preserving the
existing compiler error and successful-exit checks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: b8b85a8e-a0ab-441a-9df8-bd4fd7566952
📒 Files selected for processing (8)
scripts/build/flags.tssrc/jsc/bindings/napi.cppsrc/runtime/napi/js_native_api.hsrc/runtime/napi/js_native_api_types.hsrc/runtime/napi/node_api.hsrc/runtime/napi/node_api_types.htest/napi/napi-app/bundled_napi_headers_node26.ctest/napi/napi-value-ffi.test.ts
💤 Files with no reviewable changes (1)
- src/jsc/bindings/napi.cpp
…xclusion The first pass of this PR missed that #20772 intentionally raised Bun's in-tree default NAPI_VERSION from 8 to 10; restoring upstream's 8 would have hidden the v10 string / property-key declarations from cc() users who previously got them without opting in. Keep it at 10. It also introduced the upstream #warning block for NAPI_EXPERIMENTAL. cc()'s TinyCC backend routes every #warning through the error callback (handle_compilation_error pushes every message into deferred_errors), so an addon that #defines NAPI_EXPERIMENTAL before #include <node_api.h> would fail to compile. Drop the block from Bun's copy; Bun's own C++ build no longer needs NODE_API_EXPERIMENTAL_NO_WARNING. autofix.ci then reformatted all four headers because scripts/run-clang-format.sh still excluded the pre-move src/napi/ path. Point it (and the matching .github/workflows/CLAUDE.md entry) at src/runtime/napi/ and restore the upstream formatting so the only diff against nodejs/node is in js_native_api_types.h. A README in src/runtime/napi/ lists the three divergences so the next resync knows what to carry over. cc()-path tests are added alongside the system-cc one (the latter is what the gate exercises under ASAN).
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/runtime/napi/js_native_api_types.h`:
- Around line 111-152: Update the N-API status metadata used by
napi_get_last_error_info: add entries for napi_no_external_buffers_allowed and
napi_cannot_run_js to error_messages, and include napi_would_deadlock with its
correct metadata so last_status produces valid error information for all three
statuses.
In `@src/runtime/napi/js_native_api.h`:
- Around line 101-147: Update the Windows export list in symbols.def to include
node_api_symbol_for, node_api_create_syntax_error, and
node_api_throw_syntax_error. Keep the exports aligned with the Node-API
declarations guarded by NAPI_VERSION and preserve the existing symbol-list
format.
In `@src/runtime/napi/README.md`:
- Around line 8-9: Update the README guidance around the byte-identical upstream
files to clarify that resyncing must preserve or reapply the documented local
header divergences in lines 13-21, rather than blindly replacing them with an
upstream copy.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: f1585910-f1c9-4b14-8ed3-9a321fbd0456
📒 Files selected for processing (11)
.github/workflows/CLAUDE.mdscripts/build/flags.tsscripts/run-clang-format.shsrc/runtime/napi/README.mdsrc/runtime/napi/js_native_api.hsrc/runtime/napi/js_native_api_types.hsrc/runtime/napi/node_api.hsrc/runtime/napi/node_api_types.htest/napi/napi-app/bundled_napi_headers_experimental.ctest/napi/napi-app/bundled_napi_headers_node26.ctest/napi/napi-value-ffi.test.ts
💤 Files with no reviewable changes (1)
- scripts/build/flags.ts
.claude/commands/upgrade-nodejs.md pointed at the pre-move src/napi/js_native_api.h for the NAPI_VERSION define; the define now lives in src/runtime/napi/js_native_api_types.h (and the resync procedure is in the README alongside it). .vscode/c_cpp_properties.json still listed src/napi in six include-path entries.
There was a problem hiding this comment.
Both earlier nits are addressed (dead -DNODE_GYP_MODULE_NAME dropped in 6c3fdda; remaining src/napi/ references swept in 2ce1229). I didn't find anything further, but a vendored N-API header resync plus a new global build define (NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) is worth a maintainer's eyes.
What was reviewed:
- Header declarations vs.
napi.cppdefinitions under the opt-out —node_api_basic_env/node_api_basic_finalize/napi_cleanup_hookall alias back to the existing types, so signatures still match. grep -rn 'src/napi'is now clean repo-wide; the clang-format exclusion covers the new path.- New tests drain both pipes concurrently,
skipIfon missingcc, and pin the defaultNAPI_VERSION(10) via bothcc()and a system-compiler dlopen.
Extended reasoning...
Overview
Re-syncs the four public N-API headers in src/runtime/napi/ from nodejs/node@v26.x. Three files are byte-identical to upstream; js_native_api_types.h carries three documented Bun divergences (NapiEnv* tag, NAPI_VERSION default 10, dropped #warning block) now recorded in a new README.md. Adds NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT=1 to scripts/build/flags.ts so napi.cpp (which defines NAPI_EXPERIMENTAL) keeps its existing non-const napi_env signatures, drops the now-redundant local node_api_noenv_finalize typedef in napi.cpp, points the clang-format exclusion / workflow docs / VS Code config / /upgrade-nodejs skill at the post-move src/runtime/napi/ path, and adds three tests plus two C fixtures in test/napi/.
Security risks
None identified. The headers are declarations/typedefs/macros only — no executable logic. The one napi.cpp change is a two-line typedef deletion. No auth, crypto, or untrusted-input handling touched.
Level of scrutiny
Medium-high. The bulk of the diff is a mechanical vendor copy, and the three intentional divergences all preserve pre-existing Bun behavior (default 10 since #20772; #warning drop is forced by -Werror + TinyCC; NapiEnv* tag is unchanged). But N-API is a compat-critical surface: these headers are what napi.cpp compiles against and what cc() bundles for users, and the new NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT define is a global build flag. That combination is past my threshold for auto-approval.
Other factors
- All prior review threads (mine and CodeRabbit's) are resolved; the two out-of-scope CodeRabbit findings (
error_messages[]/last_statusgap,symbols.defparity) predate this PR and were correctly deferred. - Spot-checked that the header's changed parameter types (
node_api_basic_env,node_api_basic_finalize,napi_cleanup_hook) alias back to the typesnapi.cpp'sextern "C"definitions already use under the opt-out, so no C-linkage mismatch. - Tests follow harness conventions (
tempDir,await using, concurrent pipe drain,skipIfon missing toolchain,todoIf(isASAN)matching the neighboringcc()test). grep 'src/napi'is clean after 2ce1229.
What
Copies
js_native_api.h,js_native_api_types.h,node_api.h, andnode_api_types.hfromnodejs/node@v26.xintosrc/runtime/napi/. Three of the four files are byte-identical to upstream;js_native_api_types.hcarries Bun's three intentional divergences (documented in the newsrc/runtime/napi/README.md):struct NapiEnv*instead ofstruct napi_env__*on the three envtypedeflines, so the opaque tag matchessrc/jsc/bindings/napi.h's concrete type.NAPI_VERSIONis 10 (upstream: 8). Bun's header has defaulted to 10 since [publish images] Upgrade self-reported Node.js version from 22.6.0 to 24.3.0 (v2) #20772 so the v9/v10 declarations Bun already implements are visible without opting in; keeping upstream's 8 would have been a silent regression forcc()users.NAPI_EXPERIMENTAL#warning/#pragma messageblock is dropped.cc()'s TinyCC backend routes#warningthrough its error callback, so an includer that#define NAPI_EXPERIMENTALwould fail to compile against the bundled header; Bun's own-WerrorC++ build would also break.scripts/run-clang-format.shand.github/workflows/CLAUDE.mdstill excluded the pre-movesrc/napi/path, so autofix.ci had been free to reformat these headers; both are pointed atsrc/runtime/napi/now.Why
Bun's in-tree headers had drifted several releases behind Node. Addons compiled against them (via
cc()'s bundled#include <node_api.h>, or anything pointing-Iatsrc/runtime/napi) would:node_api_basic_env,node_api_nogc_env,node_api_basic_finalize,node_api_noenv_finalize,napi_cleanup_hook,node_api_addon_get_api_version_func, orNAPI_CDECL;node_api_symbol_for/node_api_{create,throw}_syntax_error/node_api_get_module_file_namewithout definingNAPI_EXPERIMENTAL(Node moved these toNAPI_VERSION >= 9);node_api_post_finalizer/node_api_create_buffer_from_arraybufferin the header at all (Bun already implements both);NODE_API_EXPERIMENTAL_HAS_*feature macros andNODE_API_NO_EXTERNAL_BUFFERS_ALLOWEDguard;node_api_module_get_api_version_v1when usingNAPI_MODULE_INIT(), because Bun's macro still expanded to the deprecatedNAPI_C_CTOR+napi_module_registerpath. Both Bun (BunProcess.cpp:708) and Nodedlsymthat symbol to learn the addon's declaredNAPI_VERSION; without it the host falls back to version 8 regardless of what the addon was built for.Build integration
Bun compiles
napi.cppwithNAPI_EXPERIMENTALdefined. With the upstream headers that would makenode_api_basic_envaconst-qualified alias and break every existingextern "C"signature, soNODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT=1is added next toNAPI_EXPERIMENTAL=ONinscripts/build/flags.ts(the same opt-outtest/napi/napi-app/binding.gypalready passes). The now-redundant localnode_api_noenv_finalizetypedef innapi.cppis dropped.Test
test/napi/napi-value-ffi.test.tsgains:bundled_napi_headers_node26.cagainstsrc/runtime/napi/with the systemccand dlopens the result. Before:error: unknown type name 'node_api_basic_env',NAPI_CDECLunrecognised,node_api_get_module_file_nameundeclared. After: compiles;node_api_module_get_api_version_v1()anduse_node26_types()both return the header's defaultNAPI_VERSION(10).cc()-path cases (TinyCC,todoIf(isASAN)like the existing one) compiling the same fixture and a#define NAPI_EXPERIMENTALvariant, so a future resync that reintroduces the#warningor drops the 10 default is caught on non-ASAN lanes.no test proof · iteration 0 · Platform-specific test(s) that do not run on this machine. Deferring to CI, which covers all platforms: test/napi/napi-value-ffi.test.ts