Registry / devops / neon-load-or-build

neon-load-or-build

library2.2.2jsnpmunverified

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.

devops serialization http-networking testing

npm install neon-load-or-build

github ↗package ↗

INSTALL

IMPORT

SIG · NEON-LOAD-OR-BUILD

neon-load-or-build

devopsjavascriptv2.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

load

✓ module.exports = require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })

✗ import loadBinding from 'neon-load-or-build'

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

✓ npm install neon-load-or-build

✗ import { build } from '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

✓ require('neon-load-or-build')({ moduleName: 'my-package', dir: __dirname + '/..' })

✗ const { moduleName } = require('neon-load-or-build')

The package exports a single function. Configuration is passed as an object to this function, not destructured from the package itself.

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 ?? ''; });

neon --version

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: The module 'my-package' was compiled against a different Node.js version. Using NODE_MODULE_VERSION N.

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'

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

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/staltz/neon-load-or-build ↗

packagehttps://www.npmjs.com/package/neon-load-or-build ↗