@node-rs/helper

@node-rs/helper is a TypeScript utility library that provides a robust solution for loading native Node.js bindings (.node files) in node-rs projects. It dynamically resolves and loads platform-specific native modules based on the current system architecture and platform, with comprehensive error reporting and support for multiple loading strategies.

Package Information

• Package Name: @node-rs/helper
• Package Type: npm
• Language: TypeScript
• Installation: npm install @node-rs/helper

Core Imports

import { loadBinding } from "@node-rs/helper";

For CommonJS:

const { loadBinding } = require("@node-rs/helper");

Basic Usage

import { loadBinding } from "@node-rs/helper";

// Load binding from local directory (common case)
const nativeModule = loadBinding(__dirname, 'mymodule', '@my-package/core');

// Simple usage with just directory and filename
const simpleModule = loadBinding(__dirname, 'index');

// Use the loaded native module
nativeModule.someNativeFunction();

Architecture

@node-rs/helper implements a two-stage binding resolution strategy:

1. Package-based Loading: Attempts to resolve bindings from node_modules using platform-specific package naming
2. Local File Loading: Falls back to loading from local files using platform-specific file naming
3. Platform Detection: Uses @napi-rs/triples to determine the current platform's architecture triple
4. Error Aggregation: Collects and reports detailed information about all failed loading attempts

The library supports multiple platform architectures including Windows (x64, ia32, arm64), macOS (x64, arm64), Linux (x64, arm64, armv7), FreeBSD, Android, and other platforms.

Capabilities

Native Binding Loading

Dynamically loads platform-specific native Node.js bindings with automatic platform detection and fallback strategies.

/**
 * Load native binding file from dirname with platform-specific resolution
 * @param dirname - Directory path where the .node binding file is located
 * @param filename - Optional filename (defaults to 'index'), should match napi.name in package.json
 * @param packageName - Optional package name (e.g., '@swc/core'), should match name in package.json
 * @returns The loaded native module
 * @throws Error with detailed message if no compatible binding can be loaded
 */
function loadBinding(dirname: string, filename?: string = 'index', packageName?: string): any;

Parameters:

• dirname: string - The directory where the native binding file is located
• filename?: string = 'index' - The base filename for the native binding (without platform suffix and .node extension)
• packageName?: string - The package name used for node_modules resolution (e.g., '@swc/core')

Returns:

• any - The loaded native module object with its exported functions and properties

Loading Strategy:

1. Node Modules Resolution: If packageName is provided, attempts to load ${packageName}-${platformArchABI} from node_modules
2. Local File Resolution: Attempts to load ${filename}.${platformArchABI}.node from the specified directory
3. Platform Detection: Uses @napi-rs/triples to determine platform-specific architecture identifiers

Error Handling: Throws a detailed Error if loading fails, including:

• List of attempted file paths and package names
• Specific error messages from failed require attempts
• List of available packages in node_modules when packageName is provided
• Platform architecture information for debugging

Platform Support:

• Windows: win32-x64, win32-ia32, win32-arm64
• macOS: darwin-x64, darwin-arm64
• Linux: linux-x64, linux-arm64, linux-arm, linux-armv7, etc.
• FreeBSD: freebsd-x64
• Android: android-arm64, android-arm
• Additional platforms supported by @napi-rs/triples

Usage Examples:

import { loadBinding } from "@node-rs/helper";

// Load with package name for node_modules resolution
try {
  const swcModule = loadBinding(__dirname, 'swc', '@swc/core');
  console.log('SWC native module loaded successfully');
} catch (error) {
  console.error('Failed to load SWC:', error.message);
}

// Load from local file only
try {
  const localModule = loadBinding(__dirname, 'my-native', undefined);
  const result = localModule.processData('input');
} catch (error) {
  console.error('Failed to load local binding:', error.message);
}

// Typical usage in a package's main entry point
module.exports = loadBinding(__dirname, 'package-name', '@my-org/package-name');

Error Scenarios

The loadBinding function provides comprehensive error reporting for common failure scenarios:

Missing Platform-Specific Packages:

Can not load bindings
Installed packages: [package-name-win32-x64, package-name-linux-x64]

File Exists But Load Failed:

Can not load bindings, file: /path/to/binding.linux-x64.node existed but error occurred while require it: Error message

No Compatible Bindings Found:

Can not load bindings