| 1 | # napi-build-utils
|
|---|
| 2 |
|
|---|
| 3 | [](https://www.npmjs.com/package/napi-build-utils)
|
|---|
| 4 | 
|
|---|
| 5 | 
|
|---|
| 6 | [](http://standardjs.com/)
|
|---|
| 7 | [](https://opensource.org/licenses/MIT)
|
|---|
| 8 |
|
|---|
| 9 | A set of utilities to assist developers of tools that build [Node-API](https://nodejs.org/api/n-api.html#n_api_n_api) native add-ons.
|
|---|
| 10 |
|
|---|
| 11 | ## Background
|
|---|
| 12 |
|
|---|
| 13 | This module is targeted to developers creating tools that build Node-API native add-ons.
|
|---|
| 14 |
|
|---|
| 15 | It implements a set of functions that aid in determining the Node-API version supported by the currently running Node instance and the set of Node-API versions against which the Node-API native add-on is designed to be built. Other functions determine whether a particular Node-API version can be built and can issue console warnings for unsupported Node-API versions.
|
|---|
| 16 |
|
|---|
| 17 | Unlike the modules this code is designed to facilitate building, this module is written entirely in JavaScript.
|
|---|
| 18 |
|
|---|
| 19 | ## Quick start
|
|---|
| 20 |
|
|---|
| 21 | ```bash
|
|---|
| 22 | npm install napi-build-utils
|
|---|
| 23 | ```
|
|---|
| 24 |
|
|---|
| 25 | The module exports a set of functions documented [here](./index.md). For example:
|
|---|
| 26 |
|
|---|
| 27 | ```javascript
|
|---|
| 28 | var napiBuildUtils = require('napi-build-utils');
|
|---|
| 29 | var napiVersion = napiBuildUtils.getNapiVersion(); // Node-API version supported by Node, or undefined.
|
|---|
| 30 | ```
|
|---|
| 31 |
|
|---|
| 32 | ## Declaring supported Node-API versions
|
|---|
| 33 |
|
|---|
| 34 | Native modules that are designed to work with [Node-API](https://nodejs.org/api/n-api.html#n_api_n_api) must explicitly declare the Node-API version(s) against which they are coded to build. This is accomplished by including a `binary.napi_versions` property in the module's `package.json` file. For example:
|
|---|
| 35 |
|
|---|
| 36 | ```json
|
|---|
| 37 | "binary": {
|
|---|
| 38 | "napi_versions": [2,3]
|
|---|
| 39 | }
|
|---|
| 40 | ```
|
|---|
| 41 |
|
|---|
| 42 | In the absence of a need to compile against a specific Node-API version, the value `3` is a good choice as this is the Node-API version that was supported when Node-API left experimental status.
|
|---|
| 43 |
|
|---|
| 44 | Modules that are built against a specific Node-API version will continue to operate indefinitely, even as later versions of Node-API are introduced.
|
|---|
| 45 |
|
|---|
| 46 | ## History
|
|---|
| 47 |
|
|---|
| 48 | **v2.0.0** This version was introduced to address a limitation when the Node-API version reached `10` in NodeJS `v23.6.0`. There was no change in the API, but a SemVer bump to `2.0.0` was made out of an abundance of caution.
|
|---|
| 49 |
|
|---|
| 50 | ## Support
|
|---|
| 51 |
|
|---|
| 52 | If you run into problems or limitations, please file an issue and we'll take a look. Pull requests are also welcome.
|
|---|
