src: include `node_api_types.h` instead of `node_api.h` in `node.h` #60496

addaleax · 2025-10-30T15:31:25Z

Edit: Split out #60512 from this PR and marking this PR as blocked on it

Including node.h should not result in all of Node-API also being available to callers. Users who want node_api.h contents should explicitly include that header.

We currently include it specifically for napi_addon_register_func; by moving that into node_api_types.h and including that instead, we can reduce unintentionally included API surface a lot.

Refs: #60345 (comment)

nodejs-github-bot · 2025-10-30T15:31:31Z

Review requested:

@nodejs/node-api

addaleax · 2025-10-30T16:40:58Z

src/js_native_api_types.h

+       "Experimental features may be unstable."
+#endif
+#endif
+


For context, this was moved because this file actually depends on these macros being applied, so previously there was an implicit requirement that js_native_api.h would need to be included prior to this file, either directly or indirectly.

I believe this is not a semver-major change. I'm wondering if this can be split into a PR so that it can be backport-ed? Usually we don't mark node-api header changes as semver-major and node-api headers are sync-ed across LTS versions.

@legendecas Yup, that makes a ton of sense. Opened #60512 with the non-breaking changes to Node-API headers.

nodejs-github-bot · 2025-10-30T16:46:09Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69960/

codecov · 2025-10-30T17:13:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.55%. Comparing base (dbe45b7) to head (73d929d).
⚠️ Report is 26 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #60496      +/-   ##
==========================================
+ Coverage   88.54%   88.55%   +0.01%     
==========================================
  Files         704      704              
  Lines      207843   207843              
  Branches    40044    40041       -3     
==========================================
+ Hits       184028   184057      +29     
+ Misses      15858    15834      -24     
+ Partials     7957     7952       -5

Files with missing lines	Coverage Δ
src/node.h	`95.91% <ø> (ø)`

... and 46 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2025-10-30T23:02:05Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69963/

nodejs-github-bot · 2025-10-31T11:45:30Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69968/ (💚)

This means that `node.h` can include only this file, instead of the entirety of `node_api.h`. Split out from nodejs#60496 since it was rightfully pointed out that the breaking part of the change should not touch Node-API headers.

This means that `node.h` can include only this file, instead of the entirety of `node_api.h`. Split out from #60496 since it was rightfully pointed out that the breaking part of the change should not touch Node-API headers. PR-URL: #60512 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>

legendecas · 2025-11-02T14:59:10Z

Sorry for being late. This needs a rebase after #60512 landed.

Including `node.h` should not result in all of Node-API also being available to callers. Users who want `node_api.h` contents should explicitly include that header. We currently include it specifically for `napi_addon_register_func`; by moving that into `node_api_types.h` and including that instead, we can reduce unintentionally included API surface a lot. Refs: nodejs#60345 (comment)

addaleax · 2025-11-02T18:24:47Z

@legendecas Yep, done! And no worries at all, your input here has been great.

nodejs-github-bot · 2025-11-03T12:53:47Z

CI: https://ci.nodejs.org/job/node-test-pull-request/70021/

nodejs-github-bot · 2025-11-03T16:28:47Z

CI: https://ci.nodejs.org/job/node-test-pull-request/70025/ (💚)

addaleax · 2025-11-04T14:19:10Z

@nodejs/tsc I'd leave this tagged semver-major simply to err on the side of caution, but this also means I'd need two approvals from y'all 🙂

nodejs-github-bot · 2025-11-04T14:47:26Z

Commit Queue failed

- Loading data for nodejs/node/pull/60496
✔  Done loading data for nodejs/node/pull/60496
----------------------------------- PR info ------------------------------------
Title      src: include `node_api_types.h` instead of `node_api.h` in `node.h` (#60496)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     addaleax:node-h-only-include-node-api-types.h -> nodejs:main
Labels     c++, semver-major, lib / src, needs-ci, review wanted, commit-queue-squash
Commits    1
 - src: include `node_api_types.h` instead of `node_api.h` in `node.h`
Committers 1
 - Anna Henningsen <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/60496
Reviewed-By: Juan José Arboleda <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Filip Skokan <[email protected]>
Reviewed-By: Darshan Sen <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/60496
Reviewed-By: Juan José Arboleda <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Filip Skokan <[email protected]>
Reviewed-By: Darshan Sen <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Thu, 30 Oct 2025 15:31:25 GMT
   ✔  Approvals: 5
   ✔  - Juan José Arboleda (@juanarbol): https://github.com/nodejs/node/pull/60496#pullrequestreview-3400508206
   ✔  - Chengzhong Wu (@legendecas) (TSC): https://github.com/nodejs/node/pull/60496#pullrequestreview-3408999164
   ✔  - Michaël Zasso (@targos) (TSC): https://github.com/nodejs/node/pull/60496#pullrequestreview-3416771399
   ✔  - Filip Skokan (@panva) (TSC): https://github.com/nodejs/node/pull/60496#pullrequestreview-3416773895
   ✔  - Darshan Sen (@RaisinTen) (TSC): https://github.com/nodejs/node/pull/60496#pullrequestreview-3416825540
   ✘  Last GitHub CI failed
   ℹ  Last Full PR CI on 2025-11-03T16:28:47Z: https://ci.nodejs.org/job/node-test-pull-request/70025/
- Querying data for job/node-test-pull-request/70025/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/19072542185

Including `node.h` should not result in all of Node-API also being available to callers. Users who want `node_api.h` contents should explicitly include that header. We currently include it specifically for `napi_addon_register_func`; by moving that into `node_api_types.h` and including that instead, we can reduce unintentionally included API surface a lot. Refs: #60345 (comment) PR-URL: #60496 Reviewed-By: Juan José Arboleda <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Filip Skokan <[email protected]> Reviewed-By: Darshan Sen <[email protected]>

addaleax · 2025-11-04T14:48:40Z

Landed in 7d2bc52

This means that `node.h` can include only this file, instead of the entirety of `node_api.h`. Split out from #60496 since it was rightfully pointed out that the breaking part of the change should not touch Node-API headers. PR-URL: #60512 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>

addaleax requested a review from legendecas October 30, 2025 15:31

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Oct 30, 2025

addaleax added semver-major PRs that contain breaking changes and should be released in the next major version. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. labels Oct 30, 2025

juanarbol approved these changes Oct 30, 2025

View reviewed changes

addaleax commented Oct 30, 2025

View reviewed changes

addaleax added the request-ci Add this label to start a Jenkins CI on a PR. label Oct 30, 2025

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Oct 30, 2025

addaleax added the blocked PRs that are blocked by other issues or PRs. label Oct 31, 2025

addaleax mentioned this pull request Oct 31, 2025

src: move Node-API version detection to where it is used #60512

Closed

addaleax marked this pull request as draft October 31, 2025 14:01

addaleax force-pushed the node-h-only-include-node-api-types.h branch from 617271c to 73d929d Compare November 2, 2025 18:24

addaleax marked this pull request as ready for review November 2, 2025 18:24

addaleax added review wanted PRs that need reviews. and removed blocked PRs that are blocked by other issues or PRs. labels Nov 2, 2025

legendecas approved these changes Nov 2, 2025

View reviewed changes

addaleax added the request-ci Add this label to start a Jenkins CI on a PR. label Nov 3, 2025

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Nov 3, 2025

targos approved these changes Nov 4, 2025

View reviewed changes

panva approved these changes Nov 4, 2025

View reviewed changes

addaleax added the commit-queue Add this label to land a pull request using GitHub Actions. label Nov 4, 2025

RaisinTen approved these changes Nov 4, 2025

View reviewed changes

nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels Nov 4, 2025

addaleax closed this Nov 4, 2025

addaleax deleted the node-h-only-include-node-api-types.h branch November 4, 2025 14:48

addaleax removed the review wanted PRs that need reviews. label Nov 4, 2025

Uh oh!

src: include node_api_types.h instead of node_api.h in node.h #60496

src: include node_api_types.h instead of node_api.h in node.h #60496

Uh oh!

Conversation

addaleax commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Oct 30, 2025

Uh oh!

addaleax Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

legendecas Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

addaleax Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Oct 30, 2025

Uh oh!

codecov bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nodejs-github-bot commented Oct 30, 2025

Uh oh!

nodejs-github-bot commented Oct 31, 2025 • edited by addaleax Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

legendecas commented Nov 2, 2025

Uh oh!

addaleax commented Nov 2, 2025

Uh oh!

nodejs-github-bot commented Nov 3, 2025

Uh oh!

nodejs-github-bot commented Nov 3, 2025 • edited by addaleax Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

addaleax commented Nov 4, 2025

Uh oh!

nodejs-github-bot commented Nov 4, 2025

Uh oh!

addaleax commented Nov 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

src: include `node_api_types.h` instead of `node_api.h` in `node.h` #60496

src: include `node_api_types.h` instead of `node_api.h` in `node.h` #60496

addaleax commented Oct 30, 2025 •

edited

Loading

codecov bot commented Oct 30, 2025 •

edited

Loading

nodejs-github-bot commented Oct 31, 2025 •

edited by addaleax

Loading

nodejs-github-bot commented Nov 3, 2025 •

edited by addaleax

Loading