N-API Macros

Common errors

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

  cause The C++ compiler cannot locate the N-API header files, often because the `include_dirs` in `binding.gyp` is incorrect or missing `napi-macros` path.
  fix Add or correct the `include_dirs` entry in your `binding.gyp` file to include `napi-macros` by dynamically resolving its path: `'include_dirs': [ "<!(node -e \"require('napi-macros')\")" ]`.

• Error: napi_create_threadsafe_function(NULL, callback, 0, async_resource_name, 0, 3, 0, my_finalize, NULL, my_callback, &threadsafe_function) failed!

  cause This specific error indicates that a `napi_status` check failed for the `napi_create_threadsafe_function` call, likely due to passing `NULL` for the `env` parameter, which is typically required. The `NAPI_STATUS_THROWS` macro in `napi-macros` propagates such underlying N-API errors as JavaScript exceptions.
  fix Review the N-API documentation for the specific function causing the error (`napi_create_threadsafe_function` in this case) and ensure all arguments conform to its requirements. The `env` parameter (of type `napi_env`) is crucial and usually obtained from the `napi_callback_info` argument within a `NAPI_METHOD`.

• CXX(target) Release/obj.target/your_module/src/your_file.o
  ... your_file.cc: In function 'void some_method(napi_env, napi_callback_info)':
  ... your_file.cc:XX:YY: error: 'info' was not declared in this scope

  cause The `NAPI_ARGV` macro expects `napi_env env` and `napi_callback_info info` to be in scope, as these are the standard arguments for N-API callback functions. This error typically occurs when `NAPI_ARGV` or other argument macros are used outside of a `NAPI_METHOD` block or if the method signature deviates.
  fix Ensure that NAPI argument parsing macros like `NAPI_ARGV` are used within a `NAPI_METHOD` block, which automatically provides `env` and `info` in the correct scope, or that your custom N-API function explicitly defines `napi_env env, napi_callback_info info` as its parameters.

Warnings

• gotcha N-API macros, by their nature, provide less compile-time type safety compared to C++ wrapper libraries like `node-addon-api`. Errors related to incorrect JavaScript argument types (e.g., passing a string where an integer is expected) will manifest as runtime exceptions in Node.js, rather than compile-time errors in C++.
  Fix: Thoroughly validate JavaScript input types on the Node.js side before calling native methods, or implement explicit runtime checks within the C++ code to handle unexpected types gracefully using N-API's status checks.
• breaking Reliance on `node-gyp` for building N-API modules can lead to significant cross-platform compatibility issues, requiring developers to have specific build tools (e.g., Python, C++ compilers, Visual Studio on Windows) installed and configured correctly. This complexity can be a barrier, especially in CI/CD environments or for end-users.
  Fix: Ensure that development and build environments are fully equipped with the necessary toolchain for `node-gyp`. Consider pre-compiling binaries for different platforms and architectures for distribution, or explore alternatives like `napi-rs` which streamline native addon distribution with prebuilt binaries.
• gotcha C++ macros can sometimes interfere with IDE functionalities like intelligent code completion (LSP) and static analysis, making development and debugging more challenging. The preprocessor expands macros before the compiler sees the code, which can obscure the underlying N-API calls to language servers.
  Fix: Familiarize yourself with the macro expansions to understand the underlying N-API calls. Use a text editor or IDE capable of macro expansion previews if available. Develop thorough unit tests for native modules to catch issues early.
• breaking In rare cases, conflicts can arise if Node.js header files or other N-API related libraries define the same macros (e.g., `NAPI_VERSION`), leading to compilation errors like 'NAPI_VERSION redefined'. This is typically due to environment mismatches or outdated toolchains.
  Fix: Ensure your Node.js version and build environment are consistent. If encountering this, check for conflicting header inclusions or global macro definitions. Upgrading to the latest stable Node.js and `napi-macros` versions might resolve such conflicts.

Install

• npm install napi-macros npm
• yarn add napi-macros yarn
• pnpm add napi-macros pnpm

Imports

• napi-macros include path
  wrong:

  "include_dirs": [ "node_modules/napi-macros" ]

  correct:

  "include_dirs": [ "<!(node -e \"require('napi-macros')\")" ]

  napi-macros is a C/C++ header-only library. Its 'import' into a Node.js project happens via node-gyp's binding.gyp file to provide the include path for the C++ compiler. The correct method uses `node -e "require('napi-macros')"` to dynamically resolve the package path, which is robust against varying `node_modules` structures. Directly hardcoding `node_modules/napi-macros` is fragile and can break across installations or npm versions.

Quickstart

This C++ snippet demonstrates a basic N-API module using `napi-macros`. It defines a `times_two` method that takes a single integer argument from JavaScript, multiplies it by two, and returns the result. It showcases `NAPI_METHOD`, argument parsing (`NAPI_ARGV`, `NAPI_ARGV_INT32`), returning values (`NAPI_RETURN_INT32`), and module initialization/export (`NAPI_INIT`, `NAPI_EXPORT_FUNCTION`).

#include <node_api.h>
#include <napi-macros.h>

NAPI_METHOD(times_two) {
  // Expects 1 argument
  NAPI_ARGV(1)
  // Get the first argument as an int32, named 'number'
  NAPI_ARGV_INT32(number, 0)

  // Perform operation
  number *= 2;

  // Return the result as an int32
  NAPI_RETURN_INT32(number)
}

NAPI_INIT() {
  // Export the 'times_two' function to JavaScript
  NAPI_EXPORT_FUNCTION(times_two)
}