{"id":15472,"library":"neon-load-or-build","title":"Neon Bindings Loader with Prebuild Support","description":"neon-load-or-build is a specialized build tool and bindings loader designed for projects utilizing Neon Bindings, providing robust support for precompiled native modules (prebuilds). As of version 2.2.2, it aims to significantly improve the installation experience of Node.js native add-ons by checking for existing builds or prebuilds before initiating a potentially time-consuming compilation process. While no explicit release cadence is documented, its version history suggests a stable and mature project. A key differentiator is its integration with Neon's build system, offering a CLI command similar to `neon build` but with prebuild checks. It's particularly crucial for `nodejs-mobile` environments, where specifying `moduleName` is mandatory for correct module resolution across iOS and Android. The tool is heavily inspired by `node-gyp-build` and `prebuildify`, inheriting their approach to streamlining native module distribution by prioritizing prebuilds over on-the-fly compilation. This design choice enables developers to bundle platform-specific prebuilds (e.g., for `musl` or specific ARM architectures), reducing install-time friction and ensuring compatibility across various Node.js and Electron environments.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/staltz/neon-load-or-build","tags":["javascript"],"install":[{"cmd":"npm install neon-load-or-build","lang":"bash","label":"npm"},{"cmd":"yarn add neon-load-or-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add neon-load-or-build","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports a function directly (CommonJS style) which should be called immediately with configuration options. Attempting a default ESM import may work in some contexts but is not the idiomatic usage shown in documentation.","wrong":"import loadBinding from 'neon-load-or-build'","symbol":"load","correct":"module.exports = require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })"},{"note":"While the package provides a CLI, it's typically used as an npm install script or via `require()`. There are no named JavaScript exports for CLI functionality.","wrong":"import { build } from 'neon-load-or-build'","symbol":"CLI","correct":"npm install neon-load-or-build"},{"note":"The package exports a single function. Configuration is passed as an object to this function, not destructured from the package itself.","wrong":"const { moduleName } = require('neon-load-or-build')","symbol":"ConfigObject","correct":"require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })"}],"quickstart":{"code":"{\n  \"name\": \"my-package\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"install\": \"neon-load-or-build\"\n  },\n  \"dependencies\": {\n    \"neon-load-or-build\": \"^2.2.2\",\n    \"neon-bindings\": \"^0.7.1\" // Assuming your project uses neon-bindings\n  }\n}\n\n// In your native module's lib/index.js\nconst path = require('path');\nconst neonLoader = require('neon-load-or-build');\n\nmodule.exports = neonLoader({\n  moduleName: 'my-package',\n  dir: path.join(__dirname, '..'),\n  // For nodejs-mobile, moduleName is mandatory:\n  // moduleName: 'my-package', \n  // For testing in a browser-like environment (if applicable) or if needing specific environment variables:\n  // process.env.SOME_VAR = process.env.SOME_VAR ?? ''; \n});\n","lang":"javascript","description":"Demonstrates how to integrate `neon-load-or-build` into a Neon project's `package.json` and module loading logic to enable prebuild support."},"warnings":[{"fix":"Always include `moduleName: 'your-package-name'` in the options object for `nodejs-mobile` projects.","message":"When targeting `nodejs-mobile`, the `moduleName` property in the configuration object passed to `neon-load-or-build` is mandatory for correct path resolution on both iOS and Android.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware that `--build-from-source` bypasses prebuilds. Use this flag only when troubleshooting compilation issues or when prebuilds are not available for the target environment.","message":"Users can override prebuild loading and force a local compilation by running `npm install --build-from-source`. This will ignore any available prebuilds.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult `prebuildify` documentation for detailed tag composition and ensure your build pipeline generates a comprehensive set of prebuilds, especially for environments like Alpine Linux (musl) or various ARM architectures.","message":"Prebuild resolution prioritizes more specific flavors (e.g., `abi` over `napi`, specific `libc` or `armv` tags). Ensure your bundled prebuilds cover necessary specific targets.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Try running `npm install --build-from-source` to recompile for your current Node.js version, or ensure prebuilds are available for your specific platform and Node.js ABI. Check for updates to `neon-load-or-build` and `neon-bindings`.","cause":"The native module binding was compiled for a different Node.js ABI than the currently running Node.js process, or no compatible prebuild was found and local compilation failed.","error":"Error: The module 'my-package' was compiled against a different Node.js version. Using NODE_MODULE_VERSION N."},{"fix":"Verify that prebuilds are correctly bundled and available in the `prebuilds` directory, or ensure that the `install` script (`neon-load-or-build`) successfully compiled the module if no prebuilds were found. Check the `dir` and `moduleName` options passed to `neon-load-or-build`.","cause":"The native binding file (`.node`) could not be located at the expected path, possibly due to missing prebuilds for the current environment or a failed local compilation during installation.","error":"Error: Cannot find module 'my-package.node'"}],"ecosystem":"npm"}