Registry / devops / napi-build-utils

napi-build-utils

JSON →
library2.0.0jsnpmunverified

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.

npm install napi-build-utils
INSTALL
IMPORT
SIG · NAPI-BUILD-UTILS
N
napi-build-utils
devopsjavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

napiBuildUtils
import napiBuildUtils from 'napi-build-utils';
const napiBuildUtils = require('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
import { getNapiVersion } from 'napi-build-utils';
const { getNapiVersion } = require('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
import { getNapiBuildVersions } from 'napi-build-utils';
const getNapiBuildVersions = require('napi-build-utils').getNapiBuildVersions;
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.

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.');
Debug
Known issues
gotchaVersion 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.
affects: >=2.0.0
gotchaNative 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.
affects: >=1.0.0
gotchaThe `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 */ }`
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: napiBuildUtils.getNapiVersion is not a function
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.
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'
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.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
napi-build-utils — npm install napi-build-utils · libregistry