Why N-API Is Revolutionizing Node.js Add‑On Development

Introduction

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 is supported by all LTS releases; Node.js 15.x already supports N‑API v7, making it a good time to revisit the add‑on development experience.

Work on N‑API began in 2016 and has been a long‑term effort; migration of existing packages will take time, but significant progress has been made and N‑API is now the default, recommended way to write Node.js add‑ons.

New APIs continue to be added to N‑API while maintaining stability and forward compatibility, and the community has responded positively.

New Features

More developers are using N‑API and node‑addon‑api, prompting the addition of key features and improvements.

These improvements fall into three main categories:

Multithreading and Asynchronous Programming

Node.js runs a single JavaScript thread, so heavy CPU work blocks the event loop. N‑API and node‑addon‑api now provide mechanisms such as AsyncWorker, AsyncProgressWorker, and thread‑safe functions to safely call back into JavaScript from worker threads.

AsyncWorker : one‑time callback with result or error.

AsyncProgressWorker : like AsyncWorker but also reports progress.

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

Multiple Node.js Context Support

Worker threads introduce independent JavaScript execution contexts, meaning add‑ons can be loaded and unloaded multiple times. Because workers share the same process memory, global state must be avoided. N‑API v6 adds per‑instance storage via NAPI_MODULE_INIT(), napi_get_instance_data(), and napi_set_instance_data(), and node‑addon‑api offers the Addon<T> class to manage this storage safely.

Other Helper Functions

Commonly needed utilities include Date objects, BigInts, retrieving arbitrary keys from JavaScript objects (including Symbols), and detaching ArrayBuffer storage.

Build

The build workflow is crucial for add‑on maintainers and users, with tools such as CMake.js, node‑pre‑gyp, prebuild, and prebuildify helping to produce pre‑built binaries and avoid the need for a local C/C++ toolchain during npm install.

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 provides tools, migration guides, and build‑system comparisons.

Conclusion

Since Node.js’s inception, native add‑ons have extended JavaScript capabilities. N‑API addresses the difficulties of implementing, maintaining, and distributing add‑ons by offering an ABI‑stable C API that works across major Node.js versions and even alternative runtimes such as Babylon Native, IoT.js, and Electron.

No recompilation needed after major Node.js upgrades.

Cross‑runtime compatibility.

Language‑agnostic C API enables bindings from Go, Rust, etc.

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

Getting Involved

Contributions are welcome: migrate your add‑on, help others migrate, propose or implement new features, fix bugs, or add tests to node‑addon‑api or the example repository. Join the weekly working‑group meetings via the provided link.