nodejs / nodejs/node

N-API: An api for embedding Node in applications

Open
#23,265 56 comments 20 reactions 1 assignee View on GitHub

@rubys is already working on this.

Since Nov 4, 2018.

c++ embedding feature request never-stale node-api
Dominant language
JavaScript
Stars
122k
Forks
37.3k
Avg merge
4d 2h
Merged PRs (30d)
283

Description

Is your feature request related to a problem? Please describe.
Right now there isn't a documented/stable way to use Node as a shared library inside of an application. Were one to be made using N-API, this would open up using Chakra in addition to V8 in an application.

Describe the solution you'd like
I would like for there to be stable APIs in node_api.h for creating/managing a Node environment.

A function that does this could hypothetically look like:

NAPI_EXTERN napi_status napi_create_env(int* argc, const char** argv, napi_env* env);
// Start the node event loop
NAPI_EXTERN napi_status napi_run_env(napi_env env);
// Cleanup (e.g. FreeIsolateData, FreeEnvironment and whatever else needs to be ran on teardown)
NAPI_EXTERN napi_status napi_free_env(napi_env env);

The embedder could get this environment's libuv loop using napi_get_uv_event_loop. But I would also like to have open the possibility of providing my own libuv loop that I have control over to help integrate with other event loops (e.g. Qt's event loop). This could look like:

NAPI_EXTERN napi_status napi_create_env_from_loop(int* argc, const char** argv,
  napi_env* env, struct uv_loop_s* loop);

Keeping the event loop going (using uv_run on the env's loop) would then be the embedder's responsibility.

Also, right now methods like node::CreateEnvironment seem to always jump into a REPL, unless you provide a string to evaluate or a file to run. Tweaks to help make this nicer to use for embedding will have to be made.

These APIs are just hypothetical, and will probably change when an actual attempt to implement them is made.

I am up to trying to implement this, but I would like to see what kind of discussion happens first and what other ideas people have before I start.

Implementation Progress

  • Create a clean non-NAPI way to use Node embedded
  • Create NAPI functions for creating and managing environments
  • Create a NAPI function for evaluating a string (exists in NAPI v1: napi_run_script)
  • Create a NAPI function for running a script from file
  • Investigate if this can play nicely with worker_threads.

Describe alternatives you've considered
I've tried using the unstable APIs, and they aren't fun to keep up with 😅

For discussions on how the shared library can be distributed, see this issue: https://github.com/nodejs/node/issues/24028

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.