Registry / napi-macros

napi-macros

library2.2.2jsnpmunverified

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`.

npm install napi-macros

github ↗package ↗

INSTALL

IMPORT

SIG · NAPI-MACROS

napi-macros

javascriptv2.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

napi-macros include path

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

✗ "include_dirs": [ "node_modules/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.

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) }

Debug

Known issues

gotchaN-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.

affects: >=1.0.0

breakingReliance 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.

affects: >=1.0.0

gotchaC++ 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.

affects: >=1.0.0

breakingIn 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.

affects: <=2.x

Errors

Common errors & fixes

fatal error: 'napi.h' file not found

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!

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

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.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mafintosh/napi-macros ↗

packagehttps://www.npmjs.com/package/napi-macros ↗