Registry / devops / node-api-headers

node-api-headers

library1.8.0jsnpmunverified

The `node-api-headers` package provides the essential C/C++ header files required for building Node.js native add-ons using the Node-API (formerly N-API). These headers enable developers to create native modules that benefit from ABI stability across different Node.js versions, simplifying maintenance and ensuring forward compatibility. The package, currently at version 1.8.0, maintains a frequent release cadence, often monthly or bi-monthly, specifically tracking and incorporating updates from the Node.js core repository. This package is crucial for build tools like `node-gyp` and `CMake.js`, which rely on these headers to compile native C/C++ code into `.node` files runnable within Node.js applications. It differentiates itself by being the official source for these headers, abstracting away the need to download full Node.js source distributions for native module development.

devops

npm install node-api-headers

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-API-HEADERS

node-api-headers

devopsjavascriptv1.8.0

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.

node-api-headers

✓ N/A (not a JavaScript module)

✗ import * as napiHeaders from 'node-api-headers'

This package provides C/C++ header files, not JavaScript exports. It is intended for use by native add-on build systems like `node-gyp` during compilation.

NAPI_VERSION

✓ #include <node_api.h> (in C/C++)

✗ import { NAPI_VERSION } from 'node-api-headers'

C/C++ macros and types, such as `NAPI_VERSION` or `napi_env`, are defined within the header files. They are accessed directly in C/C++ source code and are not available through JavaScript `import` or `require` statements.

include_dir

✓ require('node-api-headers').include_dir

✗ import { include_dir } from 'node-api-headers'

While not directly importing C/C++ symbols, the `node-api-headers` npm package itself exports a JavaScript object with properties like `include_dir` and `symbols`. These properties are used programmatically by build tools to locate the necessary header files.

This quickstart demonstrates how to create a basic Node.js native add-on using Node-API headers. It includes a C++ source file (`myaddon.cc`), a `binding.gyp` file for `node-gyp` to compile the add-on, and a JavaScript file (`index.js`) to load and use the compiled native module. The `binding.gyp` file dynamically fetches the header path from the `node-api-headers` package.

/* file: myaddon.cc */ #include <node_api.h> napi_value Method(napi_env env, napi_callback_info info) { napi_value greeting; napi_status status; status = napi_create_string_utf8(env, "Hello from Node-API C++ addon!", NAPI_AUTO_LENGTH, &greeting); if (status != napi_ok) return nullptr; return greeting; } napi_value Init(napi_env env, napi_value exports) { napi_status status; napi_property_descriptor desc = { "hello", 0, Method, 0, 0, 0, napi_default, 0 }; status = napi_define_properties(env, exports, 1, &desc); if (status != napi_ok) return nullptr; return exports; } NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) /* file: binding.gyp */ { "targets": [ { "target_name": "myaddon", "sources": [ "myaddon.cc" ], "include_dirs": [ "<!@(node -p \"require('node-api-headers').include_dir\")" ] } ] } /* file: index.js */ const addon = require('bindings')('myaddon'); console.log(addon.hello());

Debug

Known issues

gotchaThe `node-api-headers` package is not a JavaScript module and does not export any JavaScript functions or objects for direct `import` or `require` in application code. It exclusively provides C/C++ header files.

fix

Do not attempt to import or require `node-api-headers` in your JavaScript/TypeScript files. Instead, use it as a build-time dependency for native add-ons, allowing tools like `node-gyp` to locate the necessary C/C++ headers.

affects: >=1.0.0

gotchaPackage versions of `node-api-headers` are decoupled from Node.js runtime versions. While new releases often align with Node.js core updates, the package's version (e.g., 1.x.x) does not directly correspond to Node.js major versions (e.g., v20, v21). Always ensure the Node-API C ABI version used in your native add-on is compatible with your target Node.js runtime.

fix

Refer to the Node-API version matrix (often found in Node.js documentation or `node-addon-api` resources) to confirm compatibility between your native add-on's `NAPI_VERSION` and the Node.js runtime version. Ensure your build system correctly uses the `node-api-headers` appropriate for your target Node-API version.

affects: >=1.0.0

gotchaWhen building native add-ons, including extraneous Node.js C++ headers (e.g., `<node.h>`, `<v8.h>`) in addition to Node-API headers (`<node_api.h>`) can break ABI stability. Node-API provides stability, but other internal Node.js C++ APIs do not guarantee compatibility across major Node.js versions.

fix

For ABI-stable native add-ons, exclusively use Node-API headers (`<node_api.h>`, `<js_native_api.h>`) and the `node-addon-api` C++ wrapper where applicable. Avoid direct includes of non-Node-API Node.js internal headers unless you specifically intend to bind to a particular Node.js version and accept the lack of ABI stability.

affects: >=1.0.0

Errors

Common errors & fixes

Module not found: Can't resolve 'node-api-headers'

Attempting to `import` or `require` `node-api-headers` as if it were a JavaScript module.

fix

This package is not a JavaScript module. It provides C/C++ headers for native add-on compilation. It should not be imported directly into JS/TS application code.

error: 'NAPI_VERSION' was not declared in this scope

Native add-on compilation failed because the Node-API headers were not correctly included or found by the build system.

fix

Ensure your `binding.gyp` (or equivalent build configuration) correctly specifies the `include_dirs` to point to `require('node-api-headers').include_dir`. Verify `node-gyp` is installed and configured correctly. For CMake.js, ensure your `CMakeLists.txt` is set up to find the Node-API headers.

Error: The module '\path\to\your\addon.node' was compiled against a different Node.js version using NODE_MODULE_VERSION NNN. This version of Node.js requires NODE_MODULE_VERSION MMM. Please try re-compiling or re-installing the module (for instance, using `npm rebuild`).

The native add-on was compiled against Node-API headers for a different Node.js ABI version than the one currently running the application.

fix

The Node-API aims for ABI stability, but issues can still arise if toolchains are mismatched or `node-gyp` picks up incorrect headers. Run `npm rebuild` to recompile all native add-ons against the currently installed Node.js version. Ensure `node-api-headers` is updated to a compatible version.

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/nodejs/node-api-headers ↗

packagehttps://www.npmjs.com/package/node-api-headers ↗