Skip to content

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

License

Notifications You must be signed in to change notification settings

xan105/node-addons

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

NAPI Namespace

import {} from "@xan105/addons/napi"

find(module: string, cwd: string): Promise<{ path:string, isPrebuild: boolean }>

Find node bindings by searching in known locations such as build/Release, relative to the specified current working dir.

load(filePath: string): unknown

Load specified node bindings.

WASI Namespace

import {} from "@xan105/addons/wasi"

const VERSION: string[]

WASI version available.

load(filePath: string, version: string): Promise<unknown>

Load specified WASI addon.