Review requested:

• @nodejs/gyp

@alshdavid , we had discussed this PR in our last Node-API meeting on 5/9/2025.
The overall opinion is that we should proceed with this change.
The key points from the discussion are:

• The API should follow the same patterns as in the Node-API. It should include the Node-API header and use its macros as other Node-API functions do. (See my comment for the header file.)
• We discussed a bit the function name. It should reflect the purpose and then work together with other upcoming embedding APIs. While node_embedding_start reflects the Node.js function node::Start, its name may sound a bit confusing for the people seeing it the fist time. My intuition is that if we have start, then we should have the end, isn't it? I would propose the name node_embedding_main which IMHO better reflects the purpose. Other candidate names are node_embedding_run, node_embedding_main_run, and node_embedding_run_main. What is your opinion?
• It would be nice to see the tests or examples. Though they can be added in the follow up PR.
• We must document this function. You may consider looking at the embedding docs that I started to work on in PR node-api: use c-based api for libnode embedding #54660.

Overall, it is a great step towards the ABI-stable embedding API and thank you for doing it!

@alshdavid , we had discussed this PR in our last Node-API meeting on 5/9/2025. The overall opinion is that we should proceed with this change.

🥳

• We discussed a bit the function name. [...]I would propose the name node_embedding_main. What is your opinion?

I agree with your intuition here. node_embedding_main feels more appropriate.

• The API should follow the same patterns as in the Node-API. It should include the Node-API header and use its macros as other Node-API functions do. (See my comment for the header file.)
• We must document this function. You may consider looking at the embedding docs that I started to work on in PR node-api: use c-based api for libnode embedding #54660.

I will update the PR to reflect these requirements and happy to write the documentation.

• It must not depend on the node.h. The node.h is a non-ABI stable C++ API. It should rather depend on the node-api.h or js_native_api.h.
• It would be nice to see the tests or examples. Though they can be added in the follow up PR.

If I'm honest, outside of compsci 101 many years ago, I am very new to real-world C/C++ and would definitely require assistance with writing tests as I'm already treading water just trying to navigate the build system, templating and macros 😅.

As for using node-api.h or js_native_api.h, I will give it a try but I'm a bit out of my depth and am concerned I will miss platform specific conditional templates or something (e.g. __cdecl was a surprise to me).

Overall, it is a great step towards the ABI-stable embedding API and thank you for doing it!

Likewise! Thank you for working with the team to get the ball rolling, obtaining consensus on the approach and helping out with the implementation specifics in comments to this PR.

P.S. I wouldn't be offended if you added commits to this PR or rewrote it/raised a new PR that is idiomatic as I might need some time to get it right.

P.S. I wouldn't be offended if you added commits to this PR or rewrote it/raised a new PR that is idiomatic as I might need some time to get it right.

@alshdavid , sure, I can do that to streamline the process.
Though, in the end, you must squash all changes to redo the first commit.
It is important that the name of the first commit and the PR name follow the Node.js rules: be prefixed wth node-api: and followed with a lower case letter, e.g.: node-api: minimal C node_embedding_api function.
See: https://github.com/nodejs/node/blob/main/doc/contributing/pull-requests.md#commit-message-guidelines

@alshdavid , I do not have permissions to update your PR branch directly.
This commit has the changes that I would suggest for the PR: vmoroz@0642652
Feel free to merge/copy them.

@vmoroz, thanks for the commit. I have applied those changes and amended the commit message to fit the Nodejs rules

I have also added you as a co-author and given you write access to my fork if you'd like to make changes

@vmoroz, thanks for the commit. I have applied those changes and amended the commit message to fit the Nodejs rules

I have also added you as a co-author and given you write access to my fork if you'd like to make changes

@alshdavid , it looks great! Let me also update the PR title.
It would be great to update the embedding.md

@nodejs/node-api and @nodejs/embedders , could you have a look at this PR?

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.65%. Comparing base (8edeff9) to head (2992007).
⚠️ Report is 1352 commits behind head on main.

@@           Coverage Diff           @@
##             main   #58207   +/-   ##
=======================================
  Coverage   89.65%   89.65%           
=======================================
  Files         676      677    +1     
  Lines      206342   206344    +2     
  Branches    39531    39523    -8     
=======================================
+ Hits       184994   185005   +11     
  Misses      13475    13475           
+ Partials     7873     7864    -9     

... and 52 files with indirect coverage changes

• ❄️ 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.

@vmoroz @mhdawson , updated the PR to fix the linting error and add some basic documentation. Feel free to modify the documentation to better suit.

I tried to write an example but I'm better at Rust than I am C and I didn't want to write something misleading

We discussed in the Node-api team meeting today and @vmoroz volunteered to pull the framework for testing from his PR into this one with a basic test.

Hi @vmoroz, any chance you've had some time to look into this?

Hey @vmoroz, I have merged your changes into this PR. I have also squashed the commits and rebased onto main.

Hey @vmoroz, I have merged your changes into this PR. I have also squashed the commits and rebased onto main.

Thank you, @alshdavid!
Last week we did not have a Node-API meeting.
Hopefully the change can be discussed this week and be reviewed by other team members.

@joyeecheung , @addaleax , @legendecas , @KevinEady , could you have a look at this PR?

On the Node-API team meeting, it was raised that the term rt (runtime) could be ambiguous and embedding is informative about the APIs' main use case, established in the current C++ APIs, e.g. https://github.com/nodejs/node/blob/main/doc/api/embedding.md.

@legendecas, I've rebased the branch and renamed the init function to node_embedding_start

Hi @alshdavid , in the last Node-API meeting (2/20/2026) we had discussed the PR and the naming conventions.
It seems that everyone was OK to adopt the new node_embed_ prefix.
It is shorter than the node_embedding_ prefix, and still reflects the same meaning.
Sorry, my last proposal with the node_rt_ was not that well accepted.

I had updated the code to follow the new naming conventions and updated the tests.
This is the branch with the changes: https://github.com/vmoroz/nodejs-node/tree/alshdavid-forks_alsh/node_embedding_api

Hopefully we will discuss it tomorrow (2/27/2026) in Node-API meeting and if it looks good, then you may consider to take the new code.

@legendecas , could you please have a look? All changes on top of the main branch are in this commit: vmoroz@611d65c

@vmoroz thanks for the diff. I've rebased the PR onto main and updated it with the changes to the function names 🙏

@vmoroz, I have sent you an invite (contributor with write permissions) to my fork if you want to maintain the branch directly. Feel free to raise PRs there or just push directly to the branch.

I was just laid off (Atlassian) so I may not have the same time available to dedicate to keeping the PR up to date 🙏

This pull request has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

@avivkeller has this been abandoned or is there hope for something like this to land in the near future?

This PR went stale. You are welcome to continue the work, should it need to be continued.