Node-Addon-API C++ Wrapper for Node.js Native Addons

Common errors

• fatal error: 'napi.h' file not found

  cause The C++ compiler cannot locate the `node-addon-api` header files, meaning the include paths are incorrect or missing in your build configuration.
  fix 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`.

• Error: The specified module could not be found. (on Windows) or Error: libmyaddon.node: undefined symbol: some_napi_function (on Linux/macOS)

  cause The native addon `.node` file could not be loaded due to a missing dependency (e.g., a shared library your addon links against) or a linker error during compilation that resulted in an unusable `.node` file.
  fix 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.

• Node.js crashes with a segmentation fault or unhandled C++ exception when calling a native method.

  cause This often indicates an unhandled C++ exception propagating out of the native code, incorrect memory access (e.g., dangling pointers), or an ABI incompatibility. It can also happen if `NAPI_CPP_EXCEPTIONS` is not defined but C++ exceptions are being used.
  fix 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();`.

• TypeError: addon.myFunction is not a function

  cause The native addon loaded successfully, but the JavaScript environment cannot find the expected function. This means the C++ `Init` function did not correctly expose the function on the `exports` object or exposed it with a different name.
  fix 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).

Warnings

• gotcha Node-API provides ABI stability for its underlying C interface, meaning compiled addons typically work across Node.js major versions without recompilation. However, `node-addon-api` is a C++ wrapper; its C++ API can evolve, and major version bumps (e.g., v7 to v8) may introduce C++ API changes requiring code updates and recompilation.
  Fix: 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.
• breaking Addons built with `node-addon-api` require specific Node.js versions as indicated by the `engines.node` field in the package.json (currently `^18 || ^20 || >= 21`). Building or running on unsupported Node.js versions can lead to build failures or runtime crashes due to incompatible N-API versions or internal changes.
  Fix: 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.
• gotcha Node-Addon-API heavily utilizes C++ exceptions for error handling. It is critical to define `NAPI_CPP_EXCEPTIONS` in your `binding.gyp` (or equivalent build system) and ensure your compiler is configured to handle C++ exceptions. Failing to do so can lead to unexpected crashes, segmentation faults, or silent failures when exceptions are thrown from native code.
  Fix: 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.
• gotcha While RAII is leveraged for many resources, developers must explicitly manage persistent references to JavaScript objects (`Napi::Persistent<T>`) that need to outlive the scope of a single N-API call to prevent them from being garbage collected prematurely by the V8 engine. Forgetting to manage these can lead to use-after-free bugs or incorrect behavior.
  Fix: 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.
• gotcha Using `Napi::ThreadSafeFunction` (TSFN) for asynchronous operations across threads introduces significant complexity. Incorrect usage, particularly around managing `ref()` and `unref()` calls, lifetime management of the `ThreadSafeFunction` object, and proper data transfer between threads, is a common source of deadlocks, memory leaks, or application crashes.
  Fix: 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.

Install

• npm install node-addon-api npm
• yarn add node-addon-api yarn
• pnpm add node-addon-api pnpm

Imports

• myAddon
  wrong:

  import { myAddon } from 'node-addon-api';

  correct:

  const myAddon = require('./build/Release/myaddon.node');

  The 'node-addon-api' package itself is a C++ header library and does not provide JavaScript exports. This entry describes how a native addon compiled *using* node-addon-api is imported into a JavaScript application. The path `./build/Release/myaddon.node` is typical after a successful `node-gyp build`.
• myAddon
  wrong:

  const myAddon = require('node-addon-api');

  correct:

  import myAddon from './build/Release/myaddon.node';

  ESM import for a compiled native addon. Node.js can directly import `.node` files, but ensure your project's `package.json` type is 'module' or use dynamic `import()` if mixing CJS and ESM.
• loadNativeAddon

  import { createRequire } from 'module'; const require = createRequire(import.meta.url); const myAddon = require('./build/Release/myaddon.node');

  When operating in an ES Module environment (e.g., `"type": "module"` in `package.json`), you might need to use `createRequire` to load a CommonJS-style native addon dynamically.

Quickstart

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.

/* C++ source file: hello.cc */
#include <napi.h>

// Simple synchronous method that returns a string
Napi::String Method(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  return Napi::String::New(env, "world");
}

// Initialize the addon
Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set(Napi::String::New(env, "hello"),
              Napi::Function::New(env, Method));
  return exports;
}

// Register the addon module
NODE_API_MODULE(hello, Init)

/* binding.gyp (build configuration for node-gyp) */
{
  "targets": [
    {
      "target_name": "hello",
      "sources": [ "hello.cc" ],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "cflags!": [ "-fno-exceptions" ],
      "cflags_cc!": [ "-fno-exceptions" ],
      "defines": [ "NAPI_CPP_EXCEPTIONS" ],
      "libraries": []
    }
  ]
}

/* JavaScript usage: index.js */
// To build the addon: run `node-gyp rebuild` in your terminal.
// This will create a `build/Release/hello.node` file.

const addon = require('./build/Release/hello.node');

console.log('addon.hello() =', addon.hello()); // Expected output: addon.hello() = world