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-buildVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
Locate the `require('bindings')` call in your module's entry point (e.g., `index.js`) and replace it with `require('node-gyp-build')(__dirname)`.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.