Node-API Headers

Common errors

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

  cause 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

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

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-api-headers npm
• yarn add node-api-headers yarn
• pnpm add node-api-headers pnpm

Imports

• node-api-headers
  wrong:

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

  correct:

  N/A (not a JavaScript module)

  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
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

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

  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.

Quickstart

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());