Registry / devops / node-gyp-build

node-gyp-build

JSON →
library4.8.4jsnpmunverified

node-gyp-build is a critical utility for distributing Node.js native addons, acting as a wrapper around node-gyp to support prebuilt binaries. Its primary function is to check for and load prebuilt native modules, or fall back to compiling from source using node-gyp if no suitable prebuild is found. This significantly reduces installation times and improves cross-platform compatibility by avoiding local compilation for many users. It works in tandem with 'prebuildify' to generate and bundle these prebuilds, handling various target environments including Node.js and Electron, and accommodating different libc (e.g., glibc, musl) and ARM architectures. The current stable version is 4.8.4, with releases generally following the node-gyp and prebuildify ecosystem, focusing on stability and compatibility with new Node.js ABIs and platforms. Key differentiators include its robust prebuild discovery mechanism, seamless integration into npm install scripts, and support for complex prebuild tagging.

npm install node-gyp-build
INSTALL
IMPORT
SIG · NODE-GYP-BUILD
N
node-gyp-build
devopsjavascriptv4.8.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

<default function>
const loadBinding = require('node-gyp-build'); const binding = loadBinding(__dirname);
import loadBinding from 'node-gyp-build'; const binding = loadBinding(__dirname);
The package exports a CommonJS function. It should be invoked with the path to the module's directory (__dirname) to locate and load the native addon. Direct ESM imports often lead to errors as the package is fundamentally designed for CommonJS and native addon loading.
<default function invocation>
const binding = require('node-gyp-build')(__dirname);
import { build } from 'node-gyp-build';
This is the most common and concise way to load native bindings using node-gyp-build in a CommonJS context. There are no named exports for this module, as it provides a single default function.

Demonstrates how to configure node-gyp-build as an npm 'install' script within `package.json` and use its loader function in `index.js` to load a native addon. This setup prioritizes prebuilt binaries and provides a fallback for local compilation.

// package.json - configure the 'install' script and dependencies { "name": "my-native-hello-world", "version": "1.0.0", "description": "A sample native module using node-gyp-build and prebuildify", "main": "index.js", "scripts": { "install": "node-gyp-build", "prebuild": "prebuildify --strip", // Requires 'prebuildify' to be installed locally "postinstall": "node index.js" // To test if the binding loads after install }, "dependencies": { "node-gyp-build": "^4.0.0" } } // index.js - load the native binding const path = require('path'); console.log("Attempting to load native binding..."); let helloBinding; try { helloBinding = require('node-gyp-build')(__dirname); console.log("Native binding loaded successfully!"); // Assuming the native addon exports a 'hello' function if (typeof helloBinding.hello === 'function') { const message = helloBinding.hello(); console.log(`Native greeting: ${message}`); // Expected: 'Hello from native!' } else { console.warn("Native binding does not export a 'hello' function."); } } catch (e) { console.error(`Failed to load native binding: ${e.message}`); console.warn("Consider running 'npm install --build-from-source' if prebuilds are missing or incompatible."); // You might want to provide a fallback or re-throw based on your application's needs } /* // Example of a minimal C++ source file for 'hello.cc' (requires a binding.gyp) // Save this as hello.cc in your project root. #include <napi.h> Napi::String Method(const Napi::CallbackInfo& info) { Napi::Env env = info.Env(); return Napi::String::New(env, "Hello from native!"); } Napi::Object Init(Napi::Env env, Napi::Object exports) { exports.Set(Napi::String::New(env, "hello"), Napi::Function::New(env, Method)); return exports; } NODE_API_MODULE(hello, Init) // Example binding.gyp for 'hello.cc' // Save this as binding.gyp in your project root. { "targets": [ { "target_name": "hello", "sources": [ "hello.cc" ] } ] } */
Debug
Known issues
breakingThe naming conventions for prebuilt binaries underwent significant changes starting with node-gyp-build v4 and prebuildify v3. Prebuilds generated with older versions of prebuildify will not be recognized or loaded correctly by node-gyp-build v4+.
fix
Ensure both 'node-gyp-build' and 'prebuildify' (if used) are updated to their latest major versions (>=4.0.0 for node-gyp-build, >=3.0.0 for prebuildify). Regenerate all your project's prebuilds after updating.
affects: >=4.0.0
gotchaWhen `node-gyp-build` is configured as the `install` script, users can explicitly force a compilation from source by running `npm install --build-from-source`. This bypasses prebuilds and attempts a local compilation.
fix
Be aware that this flag exists. It's useful for debugging compilation issues or supporting niche environments where prebuilds are unavailable, but it will increase installation time significantly compared to using prebuilds.
affects: >=1.0.0
gotchaDetection of specific prebuild flavors (e.g., `musl` for Alpine Linux, or specific ARM architecture versions like `armv7`) relies on `node-gyp-build`'s auto-detection or explicit environment variables (`LIBC`, `ARM_VERSION`). Incorrect settings or detection can lead to loading a less optimal prebuild or an unnecessary source compilation.
fix
Verify that your build environment correctly sets relevant environment variables if you are targeting specific flavors. For most common scenarios, `node-gyp-build`'s auto-detection works well. Consult `prebuildify` documentation for detailed tag management.
affects: >=4.0.0
gotchaNative addons built with N-API typically offer better forward compatibility across Node.js versions. Older NAN-based (Native Abstractions for Node.js) addons are more susceptible to ABI breakage with new Node.js major versions, potentially requiring frequent prebuild updates.
fix
When developing native addons, strongly prefer N-API (Node-API) over NAN for greater ABI stability. This will reduce the frequency of needing to regenerate prebuilds for new Node.js major releases.
affects: >=1.0.0
Errors
Common errors & fixes
Error: No native build was found for platform <platform> architecture <arch> abi <abi> and libstdc++ <glibc|musl> (where applicable)
The required prebuilt binary for the current operating system, architecture, Node.js ABI, or libc environment is either missing from the bundled prebuilds or uses an outdated naming convention not recognized by node-gyp-build v4+.
fix
Ensure your project's `prebuild` script (using `prebuildify v3+`) successfully generates prebuilds for all target environments. If you are a user, try `npm install --build-from-source` to force local compilation, or ensure the library maintainers provide the necessary prebuilds.
Error: Cannot find module 'bindings'
The native module's JavaScript wrapper is still attempting to use the `bindings` package to load the native addon, rather than `node-gyp-build`.
fix
Locate the `require('bindings')` call in your module's entry point (e.g., `index.js`) and replace it with `require('node-gyp-build')(__dirname)`.
npm ERR! Failed at the <package-name>@<version> install script. node-gyp-build
The `node-gyp-build` command, executed via the `install` script in `package.json`, encountered an error. This usually indicates a problem with native compilation (if falling back to source) or an inability to find prebuilds.
fix
Examine the npm output preceding this error for more specific details from `node-gyp-build` or `node-gyp`. Common issues include missing build tools (e.g., Python, C++ compiler), incorrect `binding.gyp` configuration, or lack of matching prebuilds.
Upgrade
Version history
4.8.4latest on npm
Audit
Dependencies
node-gypoptionalProvides the underlying build system for compiling native addons from source when prebuilds are not available. It's an implicit dependency managed by node-gyp-build.
prebuildifyoptionalCompanion tool used to generate and bundle the prebuilt native addons that node-gyp-build consumes. While not a direct runtime dependency, it is essential for the common workflow.
Agent activity
8 hits · last 30 days
node
8
Resources