{"id":11426,"library":"node-gyp-build","title":"Node-GYP Build (Prebuild-aware Native Addon Loader)","description":"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.","status":"active","version":"4.8.4","language":"javascript","source_language":"en","source_url":"https://github.com/prebuild/node-gyp-build","tags":["javascript"],"install":[{"cmd":"npm install node-gyp-build","lang":"bash","label":"npm"},{"cmd":"yarn add node-gyp-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-gyp-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides 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.","package":"node-gyp","optional":true},{"reason":"Companion 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.","package":"prebuildify","optional":true}],"imports":[{"note":"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.","wrong":"import loadBinding from 'node-gyp-build';\nconst binding = loadBinding(__dirname);","symbol":"<default function>","correct":"const loadBinding = require('node-gyp-build');\nconst binding = loadBinding(__dirname);"},{"note":"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.","wrong":"import { build } from 'node-gyp-build';","symbol":"<default function invocation>","correct":"const binding = require('node-gyp-build')(__dirname);"}],"quickstart":{"code":"// package.json - configure the 'install' script and dependencies\n{\n  \"name\": \"my-native-hello-world\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A sample native module using node-gyp-build and prebuildify\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"install\": \"node-gyp-build\",\n    \"prebuild\": \"prebuildify --strip\", // Requires 'prebuildify' to be installed locally\n    \"postinstall\": \"node index.js\" // To test if the binding loads after install\n  },\n  \"dependencies\": {\n    \"node-gyp-build\": \"^4.0.0\"\n  }\n}\n\n// index.js - load the native binding\nconst path = require('path');\n\nconsole.log(\"Attempting to load native binding...\");\nlet helloBinding;\ntry {\n  helloBinding = require('node-gyp-build')(__dirname);\n  console.log(\"Native binding loaded successfully!\");\n\n  // Assuming the native addon exports a 'hello' function\n  if (typeof helloBinding.hello === 'function') {\n    const message = helloBinding.hello();\n    console.log(`Native greeting: ${message}`); // Expected: 'Hello from native!'\n  } else {\n    console.warn(\"Native binding does not export a 'hello' function.\");\n  }\n} catch (e) {\n  console.error(`Failed to load native binding: ${e.message}`);\n  console.warn(\"Consider running 'npm install --build-from-source' if prebuilds are missing or incompatible.\");\n  // You might want to provide a fallback or re-throw based on your application's needs\n}\n\n/*\n  // Example of a minimal C++ source file for 'hello.cc' (requires a binding.gyp)\n  // Save this as hello.cc in your project root.\n\n  #include <napi.h>\n\n  Napi::String Method(const Napi::CallbackInfo& info) {\n    Napi::Env env = info.Env();\n    return Napi::String::New(env, \"Hello from native!\");\n  }\n\n  Napi::Object Init(Napi::Env env, Napi::Object exports) {\n    exports.Set(Napi::String::New(env, \"hello\"), Napi::Function::New(env, Method));\n    return exports;\n  }\n\n  NODE_API_MODULE(hello, Init)\n\n  // Example binding.gyp for 'hello.cc'\n  // Save this as binding.gyp in your project root.\n\n  {\n    \"targets\": [\n      {\n        \"target_name\": \"hello\",\n        \"sources\": [ \"hello.cc\" ]\n      }\n    ]\n  }\n*/","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The 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+.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"When `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Detection 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Native 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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+.","error":"Error: No native build was found for platform <platform> architecture <arch> abi <abi> and libstdc++ <glibc|musl> (where applicable)"},{"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)`.","cause":"The native module's JavaScript wrapper is still attempting to use the `bindings` package to load the native addon, rather than `node-gyp-build`.","error":"Error: Cannot find module 'bindings'"},{"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.","cause":"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.","error":"npm ERR! Failed at the <package-name>@<version> install script. node-gyp-build"}],"ecosystem":"npm"}