Node-Addon-API (N-API) is a C++ wrapper library that significantly simplifies the development of Node.js native add-ons. It provides a higher-level, more idiomatic C++ interface over the raw C-based Node-API, leveraging modern C++ features like RAII (Resource Acquisition Is Initialization) and exceptions for safer and more robust native module development. This abstraction layer helps manage memory and resources automatically, reducing common errors associated with manual memory management in C. The current stable version is 8.7.0, with minor feature and bugfix releases occurring every few months. Its primary differentiator is making Node.js native module development accessible to C++ developers by providing familiar C++ paradigms, while maintaining ABI stability across Node.js major versions, ensuring compiled add-ons continue to work without recompilation against newer Node.js releases. It is the recommended path for new native addon development.
npm install node-addon-apiVerified import paths — ran on the pinned version, not inferred.
Demonstrates building a simple 'hello world' native addon in C++ using Node-Addon-API and loading/executing it from a Node.js JavaScript application. Includes the `binding.gyp` configuration.
Always refer to the official changelog and migration guides for `node-addon-api` when updating major versions. Recompile your native addon against the new `node-addon-api` version and target Node.js release.
Ensure your Node.js development and deployment environments meet the `engines.node` requirements. Use a Node.js version manager (e.g., `nvm`) to switch between versions.
Add `"defines": [ "NAPI_CPP_EXCEPTIONS" ]` to your `binding.gyp`. For other build systems (CMake), ensure the equivalent compiler flag for C++ exceptions is enabled. Wrap all C++ code callable from JavaScript in `try-catch` blocks to translate C++ exceptions into JavaScript exceptions.
Use `Napi::Persistent<T>` for any JavaScript values (e.g., functions, objects) that need to persist beyond the immediate N-API callback. Remember to `Reset()` or `SuppressDestruct()` these references when they are no longer needed to allow garbage collection.
Thoroughly review the Node-Addon-API documentation and examples for `Napi::ThreadSafeFunction`. Ensure all `Acquire()`/`Release()` calls are balanced, `BlockingCall()`/`NonBlockingCall()` are used correctly, and the `ThreadSafeFunction`'s lifecycle is managed carefully, especially in shutdown scenarios.
Ensure your `binding.gyp` includes `"<!@(node -p \"require('node-addon-api').include\")"` in the `include_dirs` array. For CMake, ensure you correctly `find_package(node_addon_api CONFIG REQUIRED)` and link against `node_addon_api::node_addon_api`.Check your `binding.gyp` for correct `libraries` and `link_settings` entries. Run `node-gyp rebuild` with increased verbosity (`--verbose`) to inspect linker output. On Linux, use `ldd build/Release/myaddon.node` to identify missing shared library dependencies.
Ensure `NAPI_CPP_EXCEPTIONS` is defined in your build configuration. Wrap potentially throwing C++ code in `try-catch` blocks within your `Napi::CallbackInfo` handlers to convert C++ exceptions into JavaScript exceptions using `Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();`.
Double-check the `Init` function in your C++ code. Ensure `exports.Set(Napi::String::New(env, "myFunction"), Napi::Function::New(env, MyFunctionMethod));` correctly exposes the function with the intended JavaScript name ('myFunction' in this example).