{"id":11381,"library":"napi-macros","title":"N-API Macros","description":"napi-macros is a lightweight, header-only C/C++ library providing a set of utility macros designed to simplify the development of Node.js N-API modules. It aims to reduce boilerplate code commonly associated with N-API, particularly for argument parsing, return value handling, and function/constant exports. As of April 2026, the current stable version is 2.2.2. This package is maintained by mafintosh, a prominent figure in the Node.js ecosystem, and typically sees updates in response to N-API specification changes or user contributions, rather than a fixed release cadence. Its key differentiator is its direct, macro-based approach, offering a minimal abstraction layer over the raw N-API C functions, making it suitable for developers who prefer fine-grained control and low-level C/C++ integration compared to higher-level C++ wrappers like `node-addon-api` or Rust-based solutions such as `napi-rs`.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/mafintosh/napi-macros","tags":["javascript"],"install":[{"cmd":"npm install napi-macros","lang":"bash","label":"npm"},{"cmd":"yarn add napi-macros","lang":"bash","label":"yarn"},{"cmd":"pnpm add napi-macros","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"\"include_dirs\": [ \"node_modules/napi-macros\" ]","symbol":"napi-macros include path","correct":"\"include_dirs\": [ \"<!(node -e \\\"require('napi-macros')\\\")\" ]"}],"quickstart":{"code":"#include <node_api.h>\n#include <napi-macros.h>\n\nNAPI_METHOD(times_two) {\n  // Expects 1 argument\n  NAPI_ARGV(1)\n  // Get the first argument as an int32, named 'number'\n  NAPI_ARGV_INT32(number, 0)\n\n  // Perform operation\n  number *= 2;\n\n  // Return the result as an int32\n  NAPI_RETURN_INT32(number)\n}\n\nNAPI_INIT() {\n  // Export the 'times_two' function to JavaScript\n  NAPI_EXPORT_FUNCTION(times_two)\n}","lang":"c++","description":"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`)."},"warnings":[{"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.","message":"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++.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<=2.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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')\\\")\" ]`.","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.","error":"fatal error: 'napi.h' file not found"},{"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`.","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.","error":"Error: napi_create_threadsafe_function(NULL, callback, 0, async_resource_name, 0, 3, 0, my_finalize, NULL, my_callback, &threadsafe_function) failed!"},{"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.","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.","error":"CXX(target) Release/obj.target/your_module/src/your_file.o\n... your_file.cc: In function 'void some_method(napi_env, napi_callback_info)':\n... your_file.cc:XX:YY: error: 'info' was not declared in this scope"}],"ecosystem":"npm"}