{"id":11410,"library":"node-api-headers","title":"Node-API Headers","description":"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.","status":"active","version":"1.8.0","language":"javascript","source_language":"en","source_url":"git://github.com/nodejs/node-api-headers","tags":["javascript"],"install":[{"cmd":"npm install node-api-headers","lang":"bash","label":"npm"},{"cmd":"yarn add node-api-headers","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-api-headers","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import * as napiHeaders from 'node-api-headers'","symbol":"node-api-headers","correct":"N/A (not a JavaScript module)"},{"note":"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.","wrong":"import { NAPI_VERSION } from 'node-api-headers'","symbol":"NAPI_VERSION","correct":"#include <node_api.h> (in C/C++)"},{"note":"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.","wrong":"import { include_dir } from 'node-api-headers'","symbol":"include_dir","correct":"require('node-api-headers').include_dir"}],"quickstart":{"code":"/* file: myaddon.cc */\n#include <node_api.h>\n\nnapi_value Method(napi_env env, napi_callback_info info) {\n  napi_value greeting;\n  napi_status status;\n\n  status = napi_create_string_utf8(env, \"Hello from Node-API C++ addon!\", NAPI_AUTO_LENGTH, &greeting);\n  if (status != napi_ok) return nullptr;\n  return greeting;\n}\n\nnapi_value Init(napi_env env, napi_value exports) {\n  napi_status status;\n  napi_property_descriptor desc = {\n    \"hello\", 0, Method, 0, 0, 0, napi_default, 0\n  };\n  status = napi_define_properties(env, exports, 1, &desc);\n  if (status != napi_ok) return nullptr;\n  return exports;\n}\n\nNAPI_MODULE(NODE_GYP_MODULE_NAME, Init)\n\n/* file: binding.gyp */\n{\n  \"targets\": [\n    {\n      \"target_name\": \"myaddon\",\n      \"sources\": [ \"myaddon.cc\" ],\n      \"include_dirs\": [\n        \"<!@(node -p \\\"require('node-api-headers').include_dir\\\")\"\n      ]\n    }\n  ]\n}\n\n/* file: index.js */\nconst addon = require('bindings')('myaddon');\nconsole.log(addon.hello());\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Package 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `import` or `require` `node-api-headers` as if it were a JavaScript module.","error":"Module not found: Can't resolve 'node-api-headers'"},{"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.","cause":"Native add-on compilation failed because the Node-API headers were not correctly included or found by the build system.","error":"error: 'NAPI_VERSION' was not declared in this scope"},{"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.","cause":"The native add-on was compiled against Node-API headers for a different Node.js ABI version than the one currently running the application.","error":"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`)."}],"ecosystem":"npm"}