node-abi

library4.28.0jsnpmunverified

node-abi is a utility library designed to retrieve and match Node.js and Electron Application Binary Interface (ABI) versions with their corresponding target versions and runtimes. It is critical for developers working with native Node.js modules that need to be compiled against specific Node.js or Electron environments, ensuring compatibility and preventing runtime errors due to ABI mismatches. The package maintains a comprehensive and frequently updated registry of ABI data. Currently, the stable version is 4.28.0, with a parallel 3.x branch (e.g., 3.89.0) also being actively maintained. Releases are frequent, typically occurring multiple times a month, primarily to incorporate the latest ABI changes from new Node.js and Electron releases. Its key differentiator is its consistent and up-to-date ABI registry, making it an indispensable tool for projects utilizing `node-gyp` or similar native module compilation processes, especially within the Electron ecosystem.

devops

npm install node-abi

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-ABI

node-abi

devopsjavascriptv4.28.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

getAbi

✓ import { getAbi } from 'node-abi';

✗ import getAbi from 'node-abi';

node-abi provides named exports. Attempting a default import is incorrect. For CommonJS, use `const { getAbi } = require('node-abi');`.

getTarget

✓ const { getTarget } = require('node-abi');

✗ const getTarget = require('node-abi');

This is the standard CommonJS named import. ESM users can use `import { getTarget } from 'node-abi';`. The package exports named functions, not a default export.

abiMap

✓ import { abiMap } from 'node-abi';

✗ const abiMap = require('node-abi')();

`abiMap` is a static array property containing ABI definitions, not a function. Do not call it.

This quickstart demonstrates how to use `node-abi` to retrieve ABI versions for given Node.js and Electron target versions, find target versions from ABIs, and inspect the underlying ABI map, covering common use cases for native module compatibility.

import { getAbi, getTarget, getNodeVersion, getElectronVersion, abiMap } from 'node-abi'; // Example 1: Get ABI for a specific Node.js target version const nodeTargetVersion = '20.0.0'; const nodeAbiVersion = getAbi(nodeTargetVersion, 'node'); console.log(`ABI for Node.js ${nodeTargetVersion}: ${nodeAbiVersion}`); // Example 2: Get target version for a specific ABI and runtime const currentAbi = process.versions.modules; // ABI of the current Node.js runtime const targetNodeVersion = getTarget(currentAbi, 'node'); console.log(`Node.js version for ABI ${currentAbi}: ${targetNodeVersion}`); // Example 3: Check ABI for an Electron version const electronTargetVersion = '28.0.0'; const electronAbiVersion = getAbi(electronTargetVersion, 'electron'); console.log(`ABI for Electron ${electronTargetVersion}: ${electronAbiVersion}`); // Example 4: Access the raw ABI map console.log('Partial ABI map entry for Node.js 20:', abiMap.find(entry => entry.runtime === 'node' && entry.target === '20.0.0')); // Example 5: Get Node.js version from ABI const someAbi = '115'; // Example ABI value for Node.js 20.x const nodeVersionFromAbi = getNodeVersion(someAbi); console.log(`Node.js version for ABI ${someAbi}: ${nodeVersionFromAbi}`); // Example 6: Get Electron version from ABI const someElectronAbi = '118'; // This is an example, actual ABI for Electron 28 may vary const electronVersionFromAbi = getElectronVersion(someElectronAbi); console.log(`Electron version for ABI ${someElectronAbi}: ${electronVersionFromAbi}`);

Debug

Known issues

breakingVersion 4.0.0 of `node-abi` dropped support for older Node.js and Electron versions. Specifically, it requires Node.js >= 16 and Electron >= 11.

fix

Ensure your project's Node.js and Electron environments meet the minimum requirements for `node-abi` v4.x. If you need to support older runtimes, consider using a compatible `node-abi` v3.x release.

affects: >=4.0.0

gotchaThe `node-abi` package often maintains multiple parallel major versions (e.g., v3.x and v4.x) simultaneously. Developers must ensure they install the correct major version compatible with their project's Node.js or Electron target version to get accurate ABI information.

fix

Always check the `node-abi` release notes or documentation to determine the appropriate major version for your specific Node.js or Electron runtime environment before installing.

affects: >=3.0.0

gotchaThe ABI registry data within `node-abi` updates frequently with new Node.js and Electron releases. Relying on an outdated version of `node-abi` can lead to build failures or runtime ABI mismatch errors when compiling or loading native modules for newer environments.

fix

Regularly update `node-abi` to its latest patch or minor version (`npm update node-abi` or `yarn upgrade node-abi`) to ensure you have the most current ABI definitions.

affects: >=3.0.0

gotchaWhen using `getAbi` or `getTarget`, it's crucial to specify the correct `runtime` ('node' or 'electron') to obtain accurate ABI information. Mismatched runtimes can lead to incorrect ABI lookups.

fix

Always provide the `runtime` parameter (e.g., `'node'` or `'electron'`) corresponding to the environment your native module is targeting or running in.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: (0, _nodeAbi.getAbi) is not a function

Incorrect import syntax for a CommonJS module in an ES Module context, or attempting to use a default import where only named exports exist.

fix

Ensure you are using named imports: `import { getAbi } from 'node-abi';` or for CommonJS: `const { getAbi } = require('node-abi');`. The package does not have a default export.

Error: No matching ABI found for target 'X.Y.Z' and runtime 'node'

The installed `node-abi` version is outdated and does not contain ABI data for the specified Node.js or Electron target version.

fix

Update `node-abi` to the latest version (`npm install node-abi@latest` or `yarn upgrade node-abi`). If the issue persists, ensure you are using the correct major version of `node-abi` for your project's runtime compatibility.

Module not found: Can't resolve 'node-abi'

The `node-abi` package has not been installed in the project's `node_modules` directory.

fix

Install the package using your package manager: `npm install node-abi` or `yarn add node-abi`.

Error: The module '/path/to/native_module.node' was compiled against a different Node.js version using NODE_MODULE_VERSION XXX. This version of Node.js requires NODE_MODULE_VERSION YYY.

A native module was compiled with an ABI (Application Binary Interface) that does not match the Node.js or Electron runtime where it is being executed. This often happens if `node-abi` was used with incorrect parameters or was outdated during compilation.

fix

Recompile the native module using `node-gyp` or `electron-rebuild` with the correct `target` and `runtime` flags that match your intended deployment environment. Verify `node-abi` is up-to-date and correctly integrated into your build scripts.

Upgrade

Version history

4.28.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/electron/node-abi ↗

packagehttps://www.npmjs.com/package/node-abi ↗