@xan105/addons NPM

About

ESM loader to integrate native code into Node.js with prebuild support.

This library helps dealing with finding and loading your bindings when using ESM.

Currently supports:

N-API Native addon
WASI WebAssembly System Interface

📦 Scoped @xan105 packages are for my own personal use but feel free to use them.

NB: This library was previously named node-gyp-load

Example

import { dlopen } from "@xan105/addons";

const { foo } = await dlopen("bar.node", {
  cwd: import.meta.dirname
});

foo();

CLI

Prebuild (node-gyp)

Add addons as an install script to your native project:

{
  "scripts": {
    "install": "addons"
  }
}

Install script will check for prebuild(s) before building your project with node-gyp rebuild. You can force compile by doing npm install --build-from-source

Prebuild(s) are expected to be found in the prebuild or prebuilds folder; Organized in subfolders "platform-arch". They should be N-API native addons with the .node file extension.

Example:

MODULE_PATH/
  -prebuilds/
    -win32-x64/
      -targetname.node
      -targetname2.node
    -win32-ia32/
      -targetname.node
      -targetname2.node

NB: Install script is also available with its old name node-gyp-load for backward compatibility.

SRI

This library API has an option to verify hash integrity using Subresource Integrity (SRI) string.

As such there is a convenience script named addons-sri to generate hash for every .node or .wasm files in the current working dir (excluding node_modules).

{
  "scripts": {
    "sri": "addons-sri --algo sha384"
  }
}

You can specify the algo hash through the --algo argument; if omitted it defaults to sha384.

API

⚠️ This module is only available as an ECMAScript module (ESM).

Named export

`dlopen(filePath: string, option?: object): Promise<unknown>`

Find and load specified addon based on its extention (.node, .wasm, ...).

When loading NAPI addons, if you only provide the bindings name (basename) this will automatically search the bindings in known locations such as build/Release, relative to the current working dir. You can change this directory using the cwd option.
When loading WASI addons, you can specify the WASI version with the option version.

⚙️ Options

cwd?: string (current working dir)
Current working dir where the node bindings is searched for.
version?: string (preview1)
WASI version. Currently only unstable and preview1 are available.
integrity?: string (none)
Verify the addon hash against specified Subresource Integrity (SRI) string (eg: sha384-base64...).
In case of NAPI gyp compilation (= no prebuild) this check is skipped.