Neon Bindings Loader with Prebuild Support

2.2.2 · active · verified Tue Apr 21

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.

Common errors

```
Error: The module 'my-package' was compiled against a different Node.js version. Using NODE_MODULE_VERSION N.
```
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.

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`.
```
Error: Cannot find module 'my-package.node'
```
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.

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`.

Warnings

gotcha 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.
Fix: Always include `moduleName: 'your-package-name'` in the options object for `nodejs-mobile` projects.
gotcha Users can override prebuild loading and force a local compilation by running `npm install --build-from-source`. This will ignore any available prebuilds.
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.
gotcha Prebuild resolution prioritizes more specific flavors (e.g., `abi` over `napi`, specific `libc` or `armv` tags). Ensure your bundled prebuilds cover necessary specific targets.
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.

Install

npm install neon-load-or-build npm
yarn add neon-load-or-build yarn
pnpm add neon-load-or-build pnpm

Imports

load
wrong:
```
import loadBinding from 'neon-load-or-build'
```
correct:
```
module.exports = require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })
```
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.
CLI
wrong:
```
import { build } from 'neon-load-or-build'
```
correct:
```
npm install neon-load-or-build
```
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.
ConfigObject
wrong:
```
const { moduleName } = require('neon-load-or-build')
```
correct:
```
require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })
```
The package exports a single function. Configuration is passed as an object to this function, not destructured from the package itself.

Quickstart

Demonstrates how to integrate `neon-load-or-build` into a Neon project's `package.json` and module loading logic to enable prebuild support.

{
  "name": "my-package",
  "version": "1.0.0",
  "scripts": {
    "install": "neon-load-or-build"
  },
  "dependencies": {
    "neon-load-or-build": "^2.2.2",
    "neon-bindings": "^0.7.1" // Assuming your project uses neon-bindings
  }
}

// In your native module's lib/index.js
const path = require('path');
const neonLoader = require('neon-load-or-build');

module.exports = neonLoader({
  moduleName: 'my-package',
  dir: path.join(__dirname, '..'),
  // For nodejs-mobile, moduleName is mandatory:
  // moduleName: 'my-package', 
  // For testing in a browser-like environment (if applicable) or if needing specific environment variables:
  // process.env.SOME_VAR = process.env.SOME_VAR ?? ''; 
});

view raw JSON →