Node-API

Owners: @nodejs/node-api. Public docs at doc/api/n-api.md.

Purpose

Provide a stable, ABI-safe C API for native addons. Code compiled against Node-API works on any Node version that supports the requested API version, regardless of the underlying V8 version. This contrasts with the legacy nan/v8::* direct API which couples addon code to a specific V8 release.

Directory layout

src/
  js_native_api.h                  // pure JS-engine-agnostic core
  js_native_api_types.h
  js_native_api_v8.{cc,h}          // V8 implementation
  js_native_api_v8_internals.h
  node_api.{cc,h}                  // Node-specific extensions
  node_api_internals.h
  node_api_types.h
test/
  js-native-api/                   // engine-agnostic conformance tests
  node-api/                        // Node-specific tests
  addons/                          // addon integration
doc/
  api/n-api.md                     // canonical reference

Two layers

• js_native_api.h — the engine-agnostic surface. The same API would work for a JavaScriptCore-backed runtime in theory.
• node_api.h — Node-specific additions: napi_async_work, napi_threadsafe_function, napi_create_buffer_from_data, napi_async_init, etc.

js_native_api_v8.cc (132K) is the V8 backing for the engine-agnostic part. node_api.cc (49K) is the Node bits.

Key abstractions

Type / function	Role
napi_env	Opaque per-Realm context; threads through every API call.
napi_value	Opaque JS value handle; lifetime tied to a napi_handle_scope.
napi_ref	Persistent reference (strong or weak) to a napi_value.
napi_async_work	Wraps a uv_work_t; used for synchronous-API-on-threadpool work.
napi_threadsafe_function	Lock-free ring buffer that lets non-JS threads invoke a JS callback.
napi_callback_info	Describes a function call (this, args, count, data).
napi_module_register	The macro your addon uses to register its init function.
napi_create_buffer_from_data (Node-only)	Wrap external memory as a Node Buffer.

API versioning

Addons declare the highest API version they want with NAPI_VERSION. The runtime exposes function pointers for each version up to NODE_NAPI_VERSION, currently 10. Backwards compatibility is strict: a v6 addon must work on v10 Node.

Threadsafe functions

graph LR
    OtherThread[non-JS thread] --> Q[ring buffer in napi_tsfn]
    Q --> uv[libuv async handle]
    uv --> JS[main thread runs napi_callback]

Threadsafe functions are the integration point for native libraries that produce events on their own threads (audio callbacks, IO threads, mDNS, …).

Integration points

• AsyncWrap: napi_async_init produces an AsyncContext that joins the AsyncWrap async-resource tree.
• Permission model: addons load through process.dlopen which is gated by the addon permission domain.
• TypeScript types: node-addon-api (separate repo) provides a C++ wrapper.

Entry points for modification

• New Node-specific API? Add it to src/node_api.h + src/node_api.cc and bump NODE_NAPI_VERSION if it is a new minor.
• New engine-agnostic API? Edit both src/js_native_api.h and src/js_native_api_v8.cc. Mirror in any non-V8 backends.
• Conformance tests: test/js-native-api/<feature>/.
• Maintainer guide: doc/contributing/adding-new-napi-api.md.