{"id":11407,"library":"node-abi","title":"Node.js and Electron ABI Utility","description":"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.","status":"active","version":"4.28.0","language":"javascript","source_language":"en","source_url":"https://github.com/electron/node-abi","tags":["javascript","node","electron","node_module_version","abi","v8"],"install":[{"cmd":"npm install node-abi","lang":"bash","label":"npm"},{"cmd":"yarn add node-abi","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-abi","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"node-abi provides named exports. Attempting a default import is incorrect. For CommonJS, use `const { getAbi } = require('node-abi');`.","wrong":"import getAbi from 'node-abi';","symbol":"getAbi","correct":"import { getAbi } from 'node-abi';"},{"note":"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.","wrong":"const getTarget = require('node-abi');","symbol":"getTarget","correct":"const { getTarget } = require('node-abi');"},{"note":"`abiMap` is a static array property containing ABI definitions, not a function. Do not call it.","wrong":"const abiMap = require('node-abi')();","symbol":"abiMap","correct":"import { abiMap } from 'node-abi';"}],"quickstart":{"code":"import { getAbi, getTarget, getNodeVersion, getElectronVersion, abiMap } from 'node-abi';\n\n// Example 1: Get ABI for a specific Node.js target version\nconst nodeTargetVersion = '20.0.0';\nconst nodeAbiVersion = getAbi(nodeTargetVersion, 'node');\nconsole.log(`ABI for Node.js ${nodeTargetVersion}: ${nodeAbiVersion}`);\n\n// Example 2: Get target version for a specific ABI and runtime\nconst currentAbi = process.versions.modules; // ABI of the current Node.js runtime\nconst targetNodeVersion = getTarget(currentAbi, 'node');\nconsole.log(`Node.js version for ABI ${currentAbi}: ${targetNodeVersion}`);\n\n// Example 3: Check ABI for an Electron version\nconst electronTargetVersion = '28.0.0';\nconst electronAbiVersion = getAbi(electronTargetVersion, 'electron');\nconsole.log(`ABI for Electron ${electronTargetVersion}: ${electronAbiVersion}`);\n\n// Example 4: Access the raw ABI map\nconsole.log('Partial ABI map entry for Node.js 20:', abiMap.find(entry => entry.runtime === 'node' && entry.target === '20.0.0'));\n\n// Example 5: Get Node.js version from ABI\nconst someAbi = '115'; // Example ABI value for Node.js 20.x\nconst nodeVersionFromAbi = getNodeVersion(someAbi);\nconsole.log(`Node.js version for ABI ${someAbi}: ${nodeVersionFromAbi}`);\n\n// Example 6: Get Electron version from ABI\nconst someElectronAbi = '118'; // This is an example, actual ABI for Electron 28 may vary\nconst electronVersionFromAbi = getElectronVersion(someElectronAbi);\nconsole.log(`Electron version for ABI ${someElectronAbi}: ${electronVersionFromAbi}`);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always provide the `runtime` parameter (e.g., `'node'` or `'electron'`) corresponding to the environment your native module is targeting or running in.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: (0, _nodeAbi.getAbi) is not a function"},{"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.","cause":"The installed `node-abi` version is outdated and does not contain ABI data for the specified Node.js or Electron target version.","error":"Error: No matching ABI found for target 'X.Y.Z' and runtime 'node'"},{"fix":"Install the package using your package manager: `npm install node-abi` or `yarn add node-abi`.","cause":"The `node-abi` package has not been installed in the project's `node_modules` directory.","error":"Module not found: Can't resolve 'node-abi'"},{"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.","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.","error":"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."}],"ecosystem":"npm"}