Skip to content

napi: re-sync public N-API headers from Node.js 26 - #36804

Merged
Jarred-Sumner merged 6 commits into
mainfrom
claude/farm/51f72bba/napi-headers-node26
Aug 3, 2026
Merged

Jarred-Sumner merged 6 commits into
mainfrom
claude/farm/51f72bba/napi-headers-node26

Conversation

@robobun

@robobun robobun commented Aug 3, 2026 •

Copy link
Copy Markdown
Collaborator

What

Copies js_native_api.h, js_native_api_types.h, node_api.h, and node_api_types.h from nodejs/node@v26.x into src/runtime/napi/. Three of the four files are byte-identical to upstream; js_native_api_types.h carries Bun's three intentional divergences (documented in the new src/runtime/napi/README.md):

  • struct NapiEnv* instead of struct napi_env__* on the three env typedef lines, so the opaque tag matches src/jsc/bindings/napi.h's concrete type.
  • Default NAPI_VERSION is 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 for cc() users.
  • The upstream NAPI_EXPERIMENTAL #warning/#pragma message block is dropped. cc()'s TinyCC backend routes #warning through its error callback, so an includer that #define NAPI_EXPERIMENTAL would fail to compile against the bundled header; Bun's own -Werror C++ build would also break.

scripts/run-clang-format.sh and .github/workflows/CLAUDE.md still excluded the pre-move src/napi/ path, so autofix.ci had been free to reformat these headers; both are pointed at src/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 -I at src/runtime/napi) would:

  • fail to compile when referencing 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, or NAPI_CDECL;
  • not see node_api_symbol_for / node_api_{create,throw}_syntax_error / node_api_get_module_file_name without defining NAPI_EXPERIMENTAL (Node moved these to NAPI_VERSION >= 9);
  • not see node_api_post_finalizer / node_api_create_buffer_from_arraybuffer in the header at all (Bun already implements both);
  • miss the NODE_API_EXPERIMENTAL_HAS_* feature macros and NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED guard;
  • most importantly, not export node_api_module_get_api_version_v1 when using NAPI_MODULE_INIT(), because Bun's macro still expanded to the deprecated NAPI_C_CTOR + napi_module_register path. Both Bun (BunProcess.cpp:708) and Node dlsym that symbol to learn the addon's declared NAPI_VERSION; without it the host falls back to version 8 regardless of what the addon was built for.

Build integration

Bun compiles napi.cpp with NAPI_EXPERIMENTAL defined. With the upstream headers that would make node_api_basic_env a const-qualified alias and break every existing extern "C" signature, so NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT=1 is added next to NAPI_EXPERIMENTAL=ON in scripts/build/flags.ts (the same opt-out test/napi/napi-app/binding.gyp already passes). The now-redundant local node_api_noenv_finalize typedef in napi.cpp is dropped.

Test

test/napi/napi-value-ffi.test.ts gains:

  • an "in-tree N-API headers" case that compiles bundled_napi_headers_node26.c against src/runtime/napi/ with the system cc and dlopens the result. Before: error: unknown type name 'node_api_basic_env', NAPI_CDECL unrecognised, node_api_get_module_file_name undeclared. After: compiles; node_api_module_get_api_version_v1() and use_node26_types() both return the header's default NAPI_VERSION (10).
  • two cc()-path cases (TinyCC, todoIf(isASAN) like the existing one) compiling the same fixture and a #define NAPI_EXPERIMENTAL variant, so a future resync that reintroduces the #warning or 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

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.
@coderabbitai

coderabbitai Bot commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 12 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4486e03f-32a9-4209-a4b2-d4e2e6b38256

📥 Commits

Reviewing files that changed from the base of the PR and between 6c3fdda and 2ce1229.

📒 Files selected for processing (3)
  • .claude/commands/upgrade-nodejs.md
  • .vscode/c_cpp_properties.json
  • src/runtime/napi/README.md

Walkthrough

Changes

The 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

Layer / File(s) Summary
API type foundations
src/runtime/napi/js_native_api_types.h, src/runtime/napi/node_api_types.h
Adds Node-API version macros, NAPI_CDECL, basic environment and finalizer types, registration types, and callback types.
Native API contracts
src/runtime/napi/js_native_api.h
Updates exported declarations with calling conventions, version gates, environment and finalizer types, and experimental APIs.
Node API registration and declarations
src/runtime/napi/node_api.h
Replaces module initialization with symbol-based registration and updates Node-specific APIs, buffer declarations, and version gates.
Shared buffer runtime implementation
src/jsc/bindings/napi.cpp, scripts/build/flags.ts
Adds external SharedArrayBuffer creation with deferred data-and-hint finalization and enables the related build define.
Node 26 header integration validation
test/napi/napi-app/*, test/napi/napi-value-ffi.test.ts, src/runtime/napi/README.md, .github/workflows/CLAUDE.md, scripts/run-clang-format.sh
Compiles and loads Node 26 and experimental fixtures, validates API version 10 and updated callback types, and documents and configures the maintained header paths.

Possibly related PRs

  • oven-sh/bun#36090: Both changes modify N-API external buffer finalizer handling in src/jsc/bindings/napi.cpp.
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly identifies the primary change: re-synchronizing Bun's public N-API headers with Node.js 26.
Description check ✅ Passed The description explains the changes, rationale, build integration, intentional divergences, and verification coverage in sufficient detail.

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added the claude label Aug 3, 2026
Comment thread src/runtime/napi/js_native_api_types.h Resolved
Comment thread src/runtime/napi/js_native_api_types.h Resolved
Comment thread src/runtime/napi/js_native_api_types.h Resolved
Comment thread src/runtime/napi/js_native_api_types.h Resolved
Comment thread src/runtime/napi/node_api.h Resolved
Comment thread src/runtime/napi/node_api_types.h Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 52af832 and 80204d0.

📒 Files selected for processing (8)
  • scripts/build/flags.ts
  • src/jsc/bindings/napi.cpp
  • src/runtime/napi/js_native_api.h
  • src/runtime/napi/js_native_api_types.h
  • src/runtime/napi/node_api.h
  • src/runtime/napi/node_api_types.h
  • test/napi/napi-app/bundled_napi_headers_node26.c
  • test/napi/napi-value-ffi.test.ts
💤 Files with no reviewable changes (1)
  • src/jsc/bindings/napi.cpp

Comment thread test/napi/napi-value-ffi.test.ts Resolved
Comment thread test/napi/napi-value-ffi.test.ts Resolved
Comment thread test/napi/napi-value-ffi.test.ts Resolved
Comment thread test/napi/napi-value-ffi.test.ts Resolved
robobun added 2 commits August 3, 2026 04:23
…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).
Comment thread src/runtime/napi/js_native_api_types.h Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 80204d0 and 6c3fdda.

📒 Files selected for processing (11)
  • .github/workflows/CLAUDE.md
  • scripts/build/flags.ts
  • scripts/run-clang-format.sh
  • src/runtime/napi/README.md
  • src/runtime/napi/js_native_api.h
  • src/runtime/napi/js_native_api_types.h
  • src/runtime/napi/node_api.h
  • src/runtime/napi/node_api_types.h
  • test/napi/napi-app/bundled_napi_headers_experimental.c
  • test/napi/napi-app/bundled_napi_headers_node26.c
  • test/napi/napi-value-ffi.test.ts
💤 Files with no reviewable changes (1)
  • scripts/build/flags.ts

Comment thread src/runtime/napi/js_native_api_types.h Resolved
Comment thread src/runtime/napi/js_native_api.h Resolved
Comment thread src/runtime/napi/README.md Resolved
Comment thread scripts/run-clang-format.sh Resolved
.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.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.cpp definitions under the opt-out — node_api_basic_env/node_api_basic_finalize/napi_cleanup_hook all 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, skipIf on missing cc, and pin the default NAPI_VERSION (10) via both cc() 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_status gap, symbols.def parity) 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 types napi.cpp's extern "C" definitions already use under the opt-out, so no C-linkage mismatch.
  • Tests follow harness conventions (tempDir, await using, concurrent pipe drain, skipIf on missing toolchain, todoIf(isASAN) matching the neighboring cc() test).
  • grep 'src/napi' is clean after 2ce1229.

@Jarred-Sumner
Jarred-Sumner merged commit 804094f into main Aug 3, 2026
54 checks passed
@Jarred-Sumner
Jarred-Sumner deleted the claude/farm/51f72bba/napi-headers-node26 branch August 3, 2026 07:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants