Registry / devops / node-loader

node-loader

JSON →
library2.1.0jsnpmunverified

node-loader is a Webpack loader designed to facilitate the bundling and usage of Node.js native add-ons (files with the `.node` extension) within Webpack-powered applications. It is particularly useful for projects targeting Node.js environments, including Electron's main and renderer processes. The current stable version is `2.1.0`, released in November 2024. The project generally follows an irregular release cadence, focusing on compatibility with newer Webpack and Node.js versions, as well as addressing specific issues like platform compatibility (e.g., macOS dlopen). Its primary differentiator is its specific focus on handling native Node.js modules, a niche that requires careful configuration within Webpack due to the binaries involved. It handles copying the native module to the output directory and ensures it can be dynamically loaded at runtime.

devops
npm install node-loader
github ↗package ↗
INSTALL
IMPORT
SIG · NODE-LOADER
N
node-loader
devopsjavascriptv2.1.0
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.

NodeLoader Rule
✓ module: { rules: [ { test: /\.node$/, loader: 'node-loader', }, ], }
✗ import NodeLoader from 'node-loader';
Webpack loaders are configured within `webpack.config.js` in the `module.rules` array, not directly imported into application code.
NodeLoader with Options
✓ module: { rules: [ { test: /\.node$/, loader: 'node-loader', options: { name: '[path][name].[ext]', flags: 2 // os.constants.dlopen.RTLD_NOW }, }, ], }
✗ loader: 'node-loader?name=[path][name].[ext]'
Loader options should be passed via the `options` property of the rule object for clarity and type safety, rather than query parameters.
Inline Loader Application
✓ import nativeModule from 'node-loader!./path/to/my-native-module.node';
✗ import nativeModule from './path/to/my-native-module.node';
While a `module.rules` configuration is generally preferred, `node-loader` can be applied inline by prefixing the import path. This requires the `!` syntax.

This quickstart demonstrates how to configure webpack with `node-loader` to process native `.node` modules. It includes the essential `target: 'node'` and `node: { __dirname: false }` settings, and an example of importing a native module in application code.

const path = require('path'); const fs = require('fs'); // Create a dummy .node file for the quickstart const dummyNodeModulePath = path.resolve(__dirname, 'dummy.node'); fs.writeFileSync(dummyNodeModulePath, '// This is a placeholder for a native Node.js module'); // webpack.config.js module.exports = { mode: 'development', entry: './index.js', output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist'), }, resolve: { extensions: ['...', '.node'], }, target: 'node', // Crucial for node-loader node: { __dirname: false, // Crucial for node-loader }, module: { rules: [ { test: /\.node$/, loader: 'node-loader', options: { name: '[name].[ext]' } }, ], }, }; // index.js (application entry point) // For demonstration, we'll pretend 'dummy.node' is a real native module // In a real scenario, this would be a compiled C++ addon. const nativeModule = require('./dummy.node'); console.log('Native module loaded:', nativeModule); // Expected output: Native module loaded: {} // (Since dummy.node is empty, but the loader successfully processed it) // To run: // 1. npm install webpack webpack-cli node-loader // 2. Save the webpack config above as `webpack.config.js` // 3. Save the index.js content above as `index.js` // 4. Create a dummy.node file (as shown in the config comments) // 5. Run `npx webpack` // 6. Then `node dist/bundle.js`
Debug
Known issues
breakingVersion 2.0.0 introduced a breaking change by requiring Webpack 5 or higher. Projects on Webpack 4 or earlier must upgrade Webpack or remain on `node-loader` v1.x.
fix
Upgrade your project's webpack version to `^5.0.0` or higher, or explicitly install `node-loader@^1.0.0`.
affects: >=2.0.0
breakingVersion 1.0.0 raised the minimum supported Node.js version to 10.13 and the minimum supported Webpack version to 4. Projects using older Node.js runtimes or Webpack 3 will need to upgrade.
fix
Ensure your Node.js runtime is `10.13.0` or newer and your Webpack version is `4.0.0` or newer. If not, use `node-loader@^0.6.0`.
affects: >=1.0.0
gotcha`node-loader` is strictly designed for Node.js environments. It will only work correctly when Webpack's `target` option is set to `node`, `async-node`, `electron-main`, `electron-renderer`, or `electron-preload`. Using it with browser targets will lead to runtime errors.
fix
Set `target: 'node'` (or an appropriate Electron target) in your `webpack.config.js` when bundling code that uses native Node.js modules.
affects: >=1.0.0
gotchaWhen using `node-loader`, it is critical to disable Webpack's polyfill for `__dirname` and `__filename` global variables to ensure native modules can correctly locate their dependencies. Failing to do so will result in `ReferenceError` or incorrect module loading paths.
fix
Add `node: { __dirname: false, __filename: false }` to your `webpack.config.js` configuration.
affects: >=1.0.0
Errors
Common errors & fixes
Module parse failed: Unexpected character '�' (1:0)
Attempting to import a `.node` file without `node-loader` configured or the loader failing to process the file.
fix
Ensure you have a `module.rules` entry for `test: /\.node$/` with `loader: 'node-loader'` in your `webpack.config.js`. Also, verify `target: 'node'` and `node: { __dirname: false }` are set.
Error: 'node-loader' can only be used with target 'node', 'async-node', 'electron-main', 'electron-renderer', or 'electron-preload'.
The Webpack `target` option is set to a non-Node.js compatible value (e.g., 'web', 'browserslist').
fix
Change `target` in `webpack.config.js` to `node`, `async-node`, `electron-main`, `electron-renderer`, or `electron-preload`.
ReferenceError: __dirname is not defined in ES module scope
Webpack's default behavior for `__dirname` in Node.js environments (especially ESM) can interfere with native modules expecting standard Node.js global behavior.
fix
Add `node: { __dirname: false, __filename: false }` to your `webpack.config.js` to prevent Webpack from polyfilling these globals.
TypeError: The 'flags' option must be a number. Received type string.
The `flags` option for `node-loader` was provided with a non-numeric value, or a string that could not be parsed as a number.
fix
Ensure the `flags` option in `node-loader` configuration is a number, typically from `os.constants.dlopen` (e.g., `os.constants.dlopen.RTLD_NOW`). Remember to `require('os')` if using these constants.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies
webpackrequiredThis is a Webpack loader and requires Webpack to function.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/webpack-contrib/node-loader ↗
packagehttps://www.npmjs.com/package/node-loader ↗
node-loader — npm install node-loader · libregistry