N-API Build Utilities

Common errors

• TypeError: napiBuildUtils.getNapiVersion is not a function

  cause Incorrect CommonJS `require` syntax when expecting named exports or attempting to destructure a module that doesn't provide named exports via `module.exports = { ... }`. The primary export of `napi-build-utils` is an object containing functions.
  fix Ensure you are either using `const napiBuildUtils = require('napi-build-utils'); const napiVersion = napiBuildUtils.getNapiVersion();` or if using ESM or a compatible CJS setup, `const { getNapiVersion } = require('napi-build-utils');`.

• Error: N-API version X is not supported by current Node.js runtime.

  cause This error likely originates from a native add-on's build or runtime process, informed by `napi-build-utils` checking the compatibility between the add-on's declared N-API versions (in `package.json`) and the current Node.js runtime's N-API support.
  fix Verify that the `binary.napi_versions` array in your `package.json` includes N-API versions compatible with your target Node.js environments. Update or rebuild your native add-on against a supported N-API version for the Node.js runtime in question.

• Cannot find module 'napi-build-utils'

  cause The package `napi-build-utils` has not been installed or is not resolvable in the current project's `node_modules` directory.
  fix Run `npm install napi-build-utils` or `yarn add napi-build-utils` in your project directory to ensure the package is installed and accessible.

Warnings

• gotcha Version 2.0.0 introduced a SemVer major bump "out of an abundance of caution" to address a limitation when the N-API version reached 10 in Node.js v23.6.0. However, the API itself did not change. Users upgrading might expect breaking changes that are not present in the public API.
  Fix: No specific code fix is needed if API compatibility is the concern. Simply upgrade and verify functionality. The bump was for internal consistency with future N-API numbering, not API breaking changes.
• gotcha Native add-ons built with N-API must explicitly declare their supported N-API versions within a `binary.napi_versions` property in their `package.json` file. Tools using `napi-build-utils` rely on this declaration for compatibility checks. Omitting or incorrectly configuring this property can lead to build failures or runtime issues for end-users.
  Fix: Ensure your `package.json` includes `"binary": { "napi_versions": [2, 3, /* ... */] }`. Version `3` is a good minimum choice as it was the version when Node-API left experimental status.
• gotcha The `getNapiVersion()` function returns `undefined` if N-API is not supported by the currently running Node.js instance. This indicates an environment where N-API native add-ons cannot function, which is critical information for build tools.
  Fix: Always check the return value of `getNapiVersion()`. If `undefined`, gracefully handle the lack of N-API support, e.g., by skipping native add-on compilation or informing the user. Example: `if (typeof currentNapiVersion === 'undefined') { /* handle no N-API */ }`

Install

• npm install napi-build-utils npm
• yarn add napi-build-utils yarn
• pnpm add napi-build-utils pnpm

Imports

• napiBuildUtils
  wrong:

  const napiBuildUtils = require('napi-build-utils');

  correct:

  import napiBuildUtils from 'napi-build-utils';

  CommonJS `require` is shown in the quickstart, but ESM `import` is the modern approach. The module exports an object with utility functions.
• getNapiVersion
  wrong:

  const { getNapiVersion } = require('napi-build-utils');

  correct:

  import { getNapiVersion } from 'napi-build-utils';

  While the primary export is an object, individual functions like `getNapiVersion` can often be destructured for direct use in both CommonJS and ESM environments.
• getNapiBuildVersions
  wrong:

  const getNapiBuildVersions = require('napi-build-utils').getNapiBuildVersions;

  correct:

  import { getNapiBuildVersions } from 'napi-build-utils';

  This function reads the `binary.napi_versions` from `package.json`. It's a key utility for determining an add-on's declared N-API compatibility.
• isSupportedVersion

  import { isSupportedVersion } from 'napi-build-utils';

  Use this to check if a specific N-API version is supported by the current Node.js runtime and the package's configuration.

Quickstart

This quickstart demonstrates how to programmatically retrieve the current Node.js N-API version, read declared N-API versions from a package.json, and check if a specific N-API version is compatible with both the runtime and the package's configuration. It simulates a package.json to illustrate the usage of `getNapiBuildVersions` and `isSupportedVersion`.

import { getNapiVersion, getNapiBuildVersions, isSupportedVersion } from 'napi-build-utils';
import { readFileSync } from 'fs';

// Simulate a package.json for demonstration
const packageJsonContent = {
  "name": "my-native-addon",
  "version": "1.0.0",
  "binary": {
    "napi_versions": [2, 3, 4, 5, 6, 7, 8, 9]
  }
};

// To use actual package.json, typically you would do:
// const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));

console.log('--- N-API Build Utils Demo ---');

// 1. Get the N-API version supported by the current Node.js runtime
const currentNapiVersion = getNapiVersion();
if (currentNapiVersion) {
  console.log(`Current Node.js N-API Version: ${currentNapiVersion}`);
} else {
  console.log('N-API is not supported by the current Node.js instance.');
}

// 2. Get N-API versions declared in a package.json (simulated)
// getNapiBuildVersions expects a package.json object.
const declaredNapiVersions = getNapiBuildVersions(packageJsonContent);
console.log(`Declared N-API Versions in package.json: ${declaredNapiVersions.join(', ')}`);

// 3. Check if a specific N-API version is supported by the current environment and package
const targetVersion = 3;
const isTargetSupported = isSupportedVersion(targetVersion, currentNapiVersion, declaredNapiVersions);
console.log(`Is N-API v${targetVersion} supported by current environment and package? ${isTargetSupported}`);

const unsupportedVersion = 99;
const isUnsupported = isSupportedVersion(unsupportedVersion, currentNapiVersion, declaredNapiVersions);
console.log(`Is N-API v${unsupportedVersion} supported? ${isUnsupported}`);

console.log('\nThis script helps native add-on build tools verify N-API compatibility.');