{"id":11940,"library":"require-addon","title":"Native Addon Loader","description":"require-addon (version 1.2.0) is a JavaScript utility designed to facilitate the loading of native C++ addons (typically compiled as `.node` files) across various JavaScript runtimes. Its primary function is to extend the standard CommonJS `require` function by adding an `.addon` method. This package simplifies the complex process of locating and loading precompiled or dynamically compiled native modules, particularly in environments beyond standard Node.js, such as the 'bare' engine utilized within the Holepunch/Hypercore ecosystem. It aims to provide a standardized interface for consuming native bindings, abstracting away some of the underlying system-specific calls and linking complexities. The package's release cadence appears to be infrequent, which is common for foundational libraries serving a specific, critical infrastructure role. Its key differentiator is its cross-runtime compatibility, making it suitable for specialized environments where direct native module integration is essential.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/require-addon","tags":["javascript"],"install":[{"cmd":"npm install require-addon","lang":"bash","label":"npm"},{"cmd":"yarn add require-addon","lang":"bash","label":"yarn"},{"cmd":"pnpm add require-addon","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The module exports a function designed to be assigned to `require.addon`. It is a CommonJS module.","wrong":"import addonLoader from 'require-addon';","symbol":"require('require-addon')","correct":"const addonLoader = require('require-addon');"},{"note":"The package's primary interface is exposed by augmenting the global `require` object. This pattern requires careful consideration in modular environments. Attempting named or default ESM imports will fail.","wrong":"import { addon } from 'require-addon';","symbol":"require.addon","correct":"const addonLoader = require('require-addon'); require.addon = addonLoader; const bindings = require.addon('.', __filename);"},{"note":"`bindings` represents the loaded native module, which will expose its C++ functions as JavaScript methods. Its exact structure depends on the native addon itself, typically an object with functions and properties.","symbol":"bindings (the loaded native module)","correct":"const addonLoader = require('require-addon'); require.addon = addonLoader; const bindings = require.addon('.', __filename);"}],"quickstart":{"code":"// This example demonstrates how to set up and use require-addon\n// to load a native C++ module, typically compiled to a .node file.\n// For a real scenario, you would have a precompiled native addon\n// in your project structure.\n\n// Step 1: Import the require-addon module using CommonJS syntax.\n// The package is designed to extend the global 'require' object.\nconst addonLoader = require('require-addon');\n\n// Step 2: Assign the imported function to require.addon.\n// This makes the native addon loading utility available globally via 'require'.\nrequire.addon = addonLoader;\n\n// Step 3: Load the native addon.\n// The first argument is the path to the addon's directory (often '.', meaning current directory).\n// The second argument is typically __filename, providing context for resolving relative paths.\n// This call will attempt to find and load the appropriate .node file for the current platform and architecture.\ntry {\n  const bindings = require.addon('.', __filename);\n  console.log('Native addon loaded successfully!');\n  // Here, 'bindings' would be an object exposing functions from your C++ addon.\n  // For example, if your addon had a 'hello' function:\n  // console.log(bindings.hello()); // Assuming it returns a string like \"Hello from C++!\"\n  console.log('Bindings object:', bindings);\n  // In a real application, you would now call methods on the 'bindings' object.\n} catch (error) {\n  console.error('Failed to load native addon:', error.message);\n  console.error('Ensure your native addon is correctly compiled and located.');\n}\n\n// To make this runnable, you would need an actual native addon compiled.\n// This snippet primarily shows the API usage.","lang":"javascript","description":"Demonstrates the setup and basic usage of `require-addon` to load a native C++ module."},"warnings":[{"fix":"Be aware of potential conflicts and ensure `require-addon` is initialized early or in an isolated context if global modification is a concern. Consider wrapping its usage if strict modularity is required.","message":"This package modifies the global `require` object by adding an `.addon` property. This can lead to conflicts with other libraries that also modify global built-ins or introduce unexpected behavior in complex module environments.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your native addon is compiled against the correct Node.js version and target environment (e.g., using `node-gyp rebuild --target=<NODE_VERSION>`). Verify that the compiled `.node` file is present in the expected location and matches the runtime's requirements.","message":"Native addons (`.node` files) are highly platform-specific and must be compiled for the exact target architecture, operating system, and Node.js ABI (Application Binary Interface) version. Errors often manifest as obscure runtime crashes or 'module not found' issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const addonLoader = require('require-addon');` to import the module. If working in a pure ESM environment, you might need to use `createRequire` from the `module` built-in, though `require-addon`'s global modification pattern might still pose challenges.","message":"The package is written in CommonJS and designed to integrate with `require()`. While Node.js can sometimes load CommonJS modules from ESM, directly using `import ... from 'require-addon'` for its primary functionality is not supported and can lead to errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Bare engine runtime meets the minimum version requirement. Upgrade your Bare engine instance if necessary to `1.10.0` or higher.","message":"The `package.json` specifies an `engines.bare` requirement of `>=1.10.0`. Using this package in the Bare engine runtime below this version may result in undefined behavior or errors.","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 `const addonLoader = require('require-addon'); require.addon = addonLoader;` is executed before any calls to `require.addon(...)`.","cause":"Attempted to call `require.addon()` before assigning the module's export to `require.addon`.","error":"TypeError: require.addon is not a function"},{"fix":"Verify the native addon is correctly compiled for your system (OS, architecture, Node.js version) and located in the directory passed to `require.addon`. Rebuild the addon if necessary.","cause":"The native `.node` file for the addon is either missing, not in the expected path, or incompatible with the current runtime (e.g., wrong architecture, Node.js ABI mismatch).","error":"Error: The specified module could not be found."},{"fix":"Use CommonJS `require()` syntax: `const addonLoader = require('require-addon');`. In strict ESM, consider `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const addonLoader = require('require-addon');` although the global `require.addon` modification might still be problematic.","cause":"Attempting to import `require-addon` using ESM `import` syntax in a pure ESM context, whereas `require-addon` is a CommonJS module.","error":"SyntaxError: Named export 'default' not found (module 'file:///path/to/node_modules/require-addon/index.js')"}],"ecosystem":"npm"}