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-utilsVerified import paths — ran on the pinned version, not inferred.
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`.
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.
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.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 */ }`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');`.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.
Run `npm install napi-build-utils` or `yarn add napi-build-utils` in your project directory to ensure the package is installed and accessible.
No dependency data recorded yet.