{"id":15359,"library":"napi-build-utils","title":"N-API Build Utilities","description":"napi-build-utils is a pure JavaScript utility library designed specifically for developers creating tools that build Node-API native add-ons. It provides essential functions to programmatically determine the Node-API version supported by the current Node.js instance, read the declared supported N-API versions from a `package.json` file, and validate if a specific N-API version can be built in a given environment. Unlike the native add-ons it helps manage, this module itself is entirely written in JavaScript, ensuring broad compatibility without requiring compilation. The current stable version is 2.0.0, with releases typically occurring as new N-API versions emerge or specific Node.js runtime limitations need addressing. Its key differentiator is simplifying the often complex versioning and compatibility checks inherent in N-API development, preventing common build and runtime errors for native modules.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/inspiredware/napi-build-utils","tags":["javascript","n-api","prebuild","prebuild-install"],"install":[{"cmd":"npm install napi-build-utils","lang":"bash","label":"npm"},{"cmd":"yarn add napi-build-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add napi-build-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` is shown in the quickstart, but ESM `import` is the modern approach. The module exports an object with utility functions.","wrong":"const napiBuildUtils = require('napi-build-utils');","symbol":"napiBuildUtils","correct":"import napiBuildUtils from 'napi-build-utils';"},{"note":"While the primary export is an object, individual functions like `getNapiVersion` can often be destructured for direct use in both CommonJS and ESM environments.","wrong":"const { getNapiVersion } = require('napi-build-utils');","symbol":"getNapiVersion","correct":"import { getNapiVersion } from 'napi-build-utils';"},{"note":"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.","wrong":"const getNapiBuildVersions = require('napi-build-utils').getNapiBuildVersions;","symbol":"getNapiBuildVersions","correct":"import { getNapiBuildVersions } from 'napi-build-utils';"},{"note":"Use this to check if a specific N-API version is supported by the current Node.js runtime and the package's configuration.","symbol":"isSupportedVersion","correct":"import { isSupportedVersion } from 'napi-build-utils';"}],"quickstart":{"code":"import { getNapiVersion, getNapiBuildVersions, isSupportedVersion } from 'napi-build-utils';\nimport { readFileSync } from 'fs';\n\n// Simulate a package.json for demonstration\nconst packageJsonContent = {\n  \"name\": \"my-native-addon\",\n  \"version\": \"1.0.0\",\n  \"binary\": {\n    \"napi_versions\": [2, 3, 4, 5, 6, 7, 8, 9]\n  }\n};\n\n// To use actual package.json, typically you would do:\n// const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));\n\nconsole.log('--- N-API Build Utils Demo ---');\n\n// 1. Get the N-API version supported by the current Node.js runtime\nconst currentNapiVersion = getNapiVersion();\nif (currentNapiVersion) {\n  console.log(`Current Node.js N-API Version: ${currentNapiVersion}`);\n} else {\n  console.log('N-API is not supported by the current Node.js instance.');\n}\n\n// 2. Get N-API versions declared in a package.json (simulated)\n// getNapiBuildVersions expects a package.json object.\nconst declaredNapiVersions = getNapiBuildVersions(packageJsonContent);\nconsole.log(`Declared N-API Versions in package.json: ${declaredNapiVersions.join(', ')}`);\n\n// 3. Check if a specific N-API version is supported by the current environment and package\nconst targetVersion = 3;\nconst isTargetSupported = isSupportedVersion(targetVersion, currentNapiVersion, declaredNapiVersions);\nconsole.log(`Is N-API v${targetVersion} supported by current environment and package? ${isTargetSupported}`);\n\nconst unsupportedVersion = 99;\nconst isUnsupported = isSupportedVersion(unsupportedVersion, currentNapiVersion, declaredNapiVersions);\nconsole.log(`Is N-API v${unsupportedVersion} supported? ${isUnsupported}`);\n\nconsole.log('\\nThis script helps native add-on build tools verify N-API compatibility.');","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 */ }`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`.","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.","error":"TypeError: napiBuildUtils.getNapiVersion is not a function"},{"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.","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.","error":"Error: N-API version X is not supported by current Node.js runtime."},{"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.","cause":"The package `napi-build-utils` has not been installed or is not resolvable in the current project's `node_modules` directory.","error":"Cannot find module 'napi-build-utils'"}],"ecosystem":"npm"}