0
# @node-rs/helper
1
2
@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.
3
4
## Package Information
5
6
- **Package Name**: @node-rs/helper
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @node-rs/helper`
10
11
## Core Imports
12
13
```typescript
14
import { loadBinding } from "@node-rs/helper";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { loadBinding } = require("@node-rs/helper");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { loadBinding } from "@node-rs/helper";
27
28
// Load binding from local directory (common case)
29
const nativeModule = loadBinding(__dirname, 'mymodule', '@my-package/core');
30
31
// Simple usage with just directory and filename
32
const simpleModule = loadBinding(__dirname, 'index');
33
34
// Use the loaded native module
35
nativeModule.someNativeFunction();
36
```
37
38
## Architecture
39
40
@node-rs/helper implements a two-stage binding resolution strategy:
41
42
1. **Package-based Loading**: Attempts to resolve bindings from node_modules using platform-specific package naming
43
2. **Local File Loading**: Falls back to loading from local files using platform-specific file naming
44
3. **Platform Detection**: Uses @napi-rs/triples to determine the current platform's architecture triple
45
4. **Error Aggregation**: Collects and reports detailed information about all failed loading attempts
46
47
The library supports multiple platform architectures including Windows (x64, ia32, arm64), macOS (x64, arm64), Linux (x64, arm64, armv7), FreeBSD, Android, and other platforms.
48
49
## Capabilities
50
51
### Native Binding Loading
52
53
Dynamically loads platform-specific native Node.js bindings with automatic platform detection and fallback strategies.
54
55
```typescript { .api }
56
/**
57
* Load native binding file from dirname with platform-specific resolution
58
* @param dirname - Directory path where the .node binding file is located
59
* @param filename - Optional filename (defaults to 'index'), should match napi.name in package.json
60
* @param packageName - Optional package name (e.g., '@swc/core'), should match name in package.json
61
* @returns The loaded native module
62
* @throws Error with detailed message if no compatible binding can be loaded
63
*/
64
function loadBinding(dirname: string, filename?: string = 'index', packageName?: string): any;
65
```
66
67
**Parameters:**
68
- `dirname: string` - The directory where the native binding file is located
69
- `filename?: string = 'index'` - The base filename for the native binding (without platform suffix and .node extension)
70
- `packageName?: string` - The package name used for node_modules resolution (e.g., '@swc/core')
71
72
**Returns:**
73
- `any` - The loaded native module object with its exported functions and properties
74
75
**Loading Strategy:**
76
1. **Node Modules Resolution**: If `packageName` is provided, attempts to load `${packageName}-${platformArchABI}` from node_modules
77
2. **Local File Resolution**: Attempts to load `${filename}.${platformArchABI}.node` from the specified directory
78
3. **Platform Detection**: Uses @napi-rs/triples to determine platform-specific architecture identifiers
79
80
**Error Handling:**
81
Throws a detailed Error if loading fails, including:
82
- List of attempted file paths and package names
83
- Specific error messages from failed require attempts
84
- List of available packages in node_modules when packageName is provided
85
- Platform architecture information for debugging
86
87
**Platform Support:**
88
- **Windows**: win32-x64, win32-ia32, win32-arm64
89
- **macOS**: darwin-x64, darwin-arm64
90
- **Linux**: linux-x64, linux-arm64, linux-arm, linux-armv7, etc.
91
- **FreeBSD**: freebsd-x64
92
- **Android**: android-arm64, android-arm
93
- Additional platforms supported by @napi-rs/triples
94
95
**Usage Examples:**
96
97
```typescript
98
import { loadBinding } from "@node-rs/helper";
99
100
// Load with package name for node_modules resolution
101
try {
102
const swcModule = loadBinding(__dirname, 'swc', '@swc/core');
103
console.log('SWC native module loaded successfully');
104
} catch (error) {
105
console.error('Failed to load SWC:', error.message);
106
}
107
108
// Load from local file only
109
try {
110
const localModule = loadBinding(__dirname, 'my-native', undefined);
111
const result = localModule.processData('input');
112
} catch (error) {
113
console.error('Failed to load local binding:', error.message);
114
}
115
116
// Typical usage in a package's main entry point
117
module.exports = loadBinding(__dirname, 'package-name', '@my-org/package-name');
118
```
119
120
## Error Scenarios
121
122
The `loadBinding` function provides comprehensive error reporting for common failure scenarios:
123
124
**Missing Platform-Specific Packages:**
125
```
126
Can not load bindings
127
Installed packages: [package-name-win32-x64, package-name-linux-x64]
128
```
129
130
**File Exists But Load Failed:**
131
```
132
Can not load bindings, file: /path/to/binding.linux-x64.node existed but error occurred while require it: Error message
133
```
134
135
**No Compatible Bindings Found:**
136
```
137
Can not load bindings
138
```
139
140