Offer a C FFI for Node.js embedders

[alshdavid]

What is the problem this feature will solve?

Node.js is prolific throughout the server-side world with many projects wanting to repackage the Node.js runtime and the associated standard library/resolution logic/Node.js-isms to offer it to customers such that they can reuse their existing tooling/dependencies.

Notable examples of this:

• Rspack
• Esbuild
• Parcel
• Supabase
• AWS Lambda
• etc

Currently, Node.js cannot be embedded in languages that only support native libraries with a C FFI (Rust, Dotnet, Go, etc).

This leads project maintainers to look for alternative embeddable runtimes that have incomplete Nodejs support, notably Deno (which is a great project in its own right, but lacks certain features that would necessitate consumers rewriting project code).

What is the feature you are proposing to solve the problem?

• Expose Node.js embedding capabilities via a C FFI
• Offer a static library to allow including Node.js within the embedding binary

What alternatives have you considered?

• Embedding Deno
• Removing the "Deno" parts of Deno and maintaining a light version with a focus on supporting the Node.js standard library
• Maintaining a fork of Nodejs with a C FFI
  • With Rust bindings

[joyeecheung]

libnode already exists via the --shared option of configure, and it's been used by other projects like mongodb and Electron to embed Node.js. Check out the documentation and the header file for details.

[peng]

Can you show some demo

[alshdavid]

Thanks for the reference and documentation @joyeecheung! Glad to see there is a pathway to integrate Node.js into an application - and I'm a little embarrassed I missed that part of the documentation.

Any reason this is not officially supported?

Is it that the Node.js team doesn't want to offer API stability guarantees or is it simply not a big enough use case to be a point of focus?

Outside of the Node.js executable, are there more examples of usage?

EDIT:
I have found this Rust crate which seems to do something with libnode and NAPI https://github.com/branchseer/rust-nodejs

[joyeecheung]

I think it’s already semi-officially supported. The reason why it’s not fully officially supported is probably mostly that not enough volunteers have stepped up to maintain it or provide support for it. But usually whenever we touch Environment or the NodePlatform we do think about API/ABI breakages and do compatibility patches on older release lines. We also have some cctests and whenever embedders get broken accidentally they will send patches and there usually will be someone reviewing them & try to get them landed (through the flaky CI…). The documentation could probably use more updates and elaboration but not enough people have volunteered to do that either….PR welcomed though :)

Is it that the Node.js team doesn't want to offer API stability guarantees or is it simply not a big enough use case to be a point of focus?

Not sure where the policy document is but I am fairly certain that we do provide API/ABI stability guarantees on LTS.

[addaleax]

and it's been used by other projects like mongodb

Just to clarify: libnode is too impractical for us (= mongodb), so we're just building our embedded application as if it is a regular Node.js build from source. 🤷‍♀️ If somebody did step up to properly maintain libnode as a library that we could use, that would be awesome for us though.

[alshdavid]

@addaleax does that mean you're vendoring in parts of the Node.js binary source and rewriting the entry points to be callable programmatically?

as in, translating

node ./index.js

to something like

let runtime = NodeWrapper::exec("/path/to/file.js");
runtime.eval();

Do you need to inject napi functions into your Node.js environment from the host application and can you do that with your approach?

In my application I am finishing off integrating Deno before I begin exploring libnode - But now I am wondering if libnode is worth exploring.

I'd be happy to take on work to get it to a point where it could be embedded but if there is too much missing I'd imagine it would require substantial changes which would be difficult to get into Node.js (PRs, reviewing, etc).

[alshdavid]

Another option is if there was an ability to somehow have an adapter that goes between an existing Node.js process and an external program with the same performance as Napi.

I tried experimenting with using a memory mapped file to act as a place to store shared memory, where the Node.js side has a napi module which opens the shared memory and both the host and Node.js can work with it - but building such an adapter is very cumbersome and limiting (e.g. sharing dynamic data structures like HashMaps and Vectors) so I gave up on that

[joyeecheung]

To see how to use the existing libnode to embed Node.js into a C++ program, you can check out some of our tests, for example https://github.com/nodejs/node/blob/main/test/embedding/embedtest.cc and https://github.com/nodejs/node/blob/main/test/cctest/test_environment.cc

[jasongin]

#43542 adds a simpler ABI-stable API for embedding, that would make libnode much easier to use from other applications and programming languages.

[DavidPeicho]

We succeeded to have a pretty decent support for libnode on our side. However, there are a number of issues that makes it tricky for production:

• Re-loading code loaded via import is leaky. Probably related to Invalidate cache when using import #49442
• Hard to apply sourcemaps without going through require/import

I wouldn't mind helping to make it even easier / more robust to embed, but I would need some pointers especially for the above issues.

[viferga]

@alshdavid If you want to use an existing library which already embeds NodeJS, you have this: https://github.com/metacall/core
If you require to use it from Rust, you have the option too:
https://crates.io/crates/metacall
And if you need to distribute it as compiled library, you can also use this: https://github.com/metacall/libnode
We also have other ways of distributing the binaries if you need them I can share them too.

I have been checking all the issues in this repository related to embedding and we are solving almost all of them, like the hot code reloading @DavidPeicho mentioned.. or other issues like this one: #52282

We are using it in production ready environment and commercially.