Node.js and Electron ABI Utility

Common errors

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

  cause 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'

  cause 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'

  cause 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.

  cause 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.

Warnings

• breaking Version 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.
• gotcha The `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.
• gotcha The 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.
• gotcha When 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.

Install

• npm install node-abi npm
• yarn add node-abi yarn
• pnpm add node-abi pnpm

Imports

• getAbi
  wrong:

  import getAbi from 'node-abi';

  correct:

  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
  wrong:

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

  correct:

  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
  wrong:

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

  correct:

  import { abiMap } from 'node-abi';

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

Quickstart

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}`);