Node.js and Electron N-API Version Checker

0.2.1 · active · verified Sun Apr 19

The `node-api-version` package provides a programmatic way to determine the maximum Node-API (N-API) version supported by specific Node.js or Electron runtime versions. This utility is critical for developers working with native Node.js addons, enabling them to ensure compatibility and manage prebuilt binaries efficiently across different runtime environments. By querying N-API support directly, it helps avoid ABI mismatches and streamlines the native module compilation and distribution process. The current stable version is 0.2.1, indicating a stable but early-stage utility, likely with an infrequent release cadence tied to updates in Node.js and Electron. Its primary differentiator is offering a simple, automated lookup without requiring manual maintenance of N-API version tables.

Common errors

```
TypeError: fromNodeVersion is not a function
```
cause Incorrect CommonJS import syntax, attempting to call a function directly from `require('pkg')` instead of destructuring.

fix Use `const { fromNodeVersion } = require('node-api-version');` for CommonJS.
```
fromNodeVersion(...) returns undefined
```
cause The input Node.js or Electron version is either too old to support Node-API or is not recognized/mapped by the library.

fix Verify the version string for typos and ensure it's a version that is expected to have N-API support. Handle the `undefined` return explicitly in your code.
```
TS2305: Module '"node-api-version"' has no exported member 'default'.
```
cause Attempting to use a default import (`import nodeApiVersion from 'node-api-version';`) when the package only provides named exports.

fix Use named imports: `import { fromNodeVersion, fromElectronVersion } from 'node-api-version';`

Warnings

gotcha The functions `fromNodeVersion` and `fromElectronVersion` return `undefined` when the provided version does not support Node-API or when the version is unknown/unsupported by the library's internal mapping. Always handle `undefined` results.
Fix: Implement explicit checks for `undefined` results: `const napiVersion = fromNodeVersion('...'); if (napiVersion === undefined) { /* handle unsupported */ }`
breaking As a pre-1.0.0 package (current version 0.2.1), `node-api-version` follows semantic versioning but with the understanding that minor versions *can* introduce breaking changes. Developers should review release notes carefully before upgrading minor versions.
Fix: Pin to exact versions for production environments (`"node-api-version": "0.2.1"`) and manually verify functionality after any upgrade, even for minor version bumps.
gotcha While the package ships TypeScript types, its `package.json` primarily specifies a CommonJS `main` entry point. While modern bundlers and TypeScript can usually resolve ESM `import` statements, direct Node.js execution might require specific ESM configuration or the use of `require()` for older Node.js versions.
Fix: For pure Node.js ESM projects, ensure your `package.json` has `"type": "module"` and consider using bundlers or transpilers for consistency. Otherwise, stick to `require()` for CommonJS contexts.

Install

npm install node-api-version npm
yarn add node-api-version yarn
pnpm add node-api-version pnpm

Imports

fromNodeVersion
wrong:
```
const fromNodeVersion = require('node-api-version').fromNodeVersion;
```
correct:
```
import { fromNodeVersion } from 'node-api-version';
```
For CommonJS, use `const { fromNodeVersion } = require('node-api-version');`. Package ships TypeScript types.
fromElectronVersion
wrong:
```
const fromElectronVersion = require('node-api-version').fromElectronVersion;
```
correct:
```
import { fromElectronVersion } from 'node-api-version';
```
This function specifically targets Electron versions. Ensure correct import syntax for your module system (ESM or CommonJS).
All functions (CJS)
wrong:
```
import nodeApiVersion from 'node-api-version';
```
correct:
```
const { fromNodeVersion, fromElectronVersion } = require('node-api-version');
```
The package exports named functions, not a default export. Use destructuring for CommonJS and named imports for ESM.

Quickstart

This quickstart demonstrates how to use `fromNodeVersion` and `fromElectronVersion` to query Node-API compatibility for various runtime versions, showing results for both supported and unsupported inputs.

import { fromNodeVersion, fromElectronVersion } from 'node-api-version';

// Determine the Node-API version for specific Node.js releases
const napiNode9 = fromNodeVersion('9.0.0');
console.log(`Node 9.0.0 N-API version: ${napiNode9 || 'N/A'}`);

const napiNode12 = fromNodeVersion('12.13.0');
console.log(`Node 12.13.0 N-API version: ${napiNode12 || 'N/A'}`);

const napiNode16 = fromNodeVersion('16.0.0');
console.log(`Node 16.0.0 N-API version: ${napiNode16 || 'N/A'}`);

// Determine the Node-API version for specific Electron releases
const napiElectron2 = fromElectronVersion('2.0.0');
console.log(`Electron 2.0.0 N-API version: ${napiElectron2 || 'N/A'}`);

const napiElectron13 = fromElectronVersion('13.0.0');
console.log(`Electron 13.0.0 N-API version: ${napiElectron13 || 'N/A'}`);

const napiElectron15Nightly = fromElectronVersion('15.0.0-nightly.20210629');
console.log(`Electron 15.0.0-nightly N-API version: ${napiElectron15Nightly || 'N/A'}`);

// Example of an unsupported version
const napiUnknown = fromNodeVersion('0.10.0');
console.log(`Node 0.10.0 N-API version: ${napiUnknown || 'N/A'}`);

view raw JSON →