Unlocking Stable Node.js Add‑ons: N-API Features, Threading, and Build Strategies

About N-API

N-API provides an ABI‑stable add‑on API for Node.js, simplifying the development of add‑ons that work across Node.js versions.

Node‑addon‑api, the C++ wrapper for N-API, now exceeds 2.5 million weekly downloads, and all Node.js LTS releases support N-API v3 or higher, with Node.js 15.x supporting N-API v7.

Since the initial proposal in December 2016, the migration to N-API has been a long‑term effort due to the large existing ecosystem.

Today N-API is the default, recommended way to write Node.js add‑ons.

New Features

Recent years have seen many new APIs added to N-API to meet the evolving needs of module authors while maintaining stability and forward compatibility.

Multithreading and Asynchronous Programming

Node.js runs JavaScript on a single main thread, so heavy CPU work blocks the event loop. N-API and node‑addon‑api introduce several mechanisms to safely call back into JavaScript from worker threads:

AsyncWorker : one‑off task with a single callback for result or error.

AsyncProgressWorker : like AsyncWorker but also reports progress to JavaScript.

Thread‑safe functions : allow callbacks from any thread at any time.

Multiple Node.js Context Support

The introduction of worker_threads enables independent JavaScript execution contexts. Add‑ons can be loaded and unloaded in each worker, but must avoid unsafe global state because all workers share the same process memory.

N-API v6 adds per‑instance storage via NAPI_MODULE_INIT(), napi_get_instance_data(), and napi_set_instance_data(), allowing add‑ons to store data unique to each Node.js instance. The C++ class Addon<T> wraps these functions for easier use.

Other Helper Functions

Additional frequently used utilities include support for Date objects, BigInts, retrieving arbitrary keys (e.g., Symbols) from JavaScript objects, and detaching ArrayBuffer storage.

Build

Building add‑ons is crucial. Tools such as CMake.js, node‑pre‑gyp, prebuild, and prebuildify help produce pre‑compiled binaries, avoiding the need for end‑users to have a C/C++ toolchain.

Getting Started

Numerous examples are available in the node-addon-examples repository. To try a simple hello‑world add‑on using node‑addon‑api:

$ git clone https://github.com/nodejs/node-addon-examples.git
$ cd node-addon-examples/1_hello_world/node-addon-api/
$ npm i
$ node .

The N‑API Resource site offers comprehensive documentation, migration guides from NAN, and comparisons of build systems.

Conclusion

N‑API has become essential for stable, cross‑version Node.js add‑ons, enabling compatibility with alternative runtimes (Babylon Native, IoT.js, Electron), and allowing development in languages beyond C/C++ such as Go or Rust.

Popular add‑ons like sharp , bcrypt , and sqlite3 have already migrated to N‑API.

Start Contributing

Ways to help include migrating existing add‑ons to N‑API, contributing new features, fixing bugs, adding tests, and improving documentation. Interested developers can join the weekly work‑group meetings via the provided GitHub link.