{"id":11436,"library":"node-loader","title":"Webpack Node.js Addon Loader","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/webpack-contrib/node-loader","tags":["javascript","webpack"],"install":[{"cmd":"npm install node-loader","lang":"bash","label":"npm"},{"cmd":"yarn add node-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Webpack loader and requires Webpack to function.","package":"webpack","optional":false}],"imports":[{"note":"Webpack loaders are configured within `webpack.config.js` in the `module.rules` array, not directly imported into application code.","wrong":"import NodeLoader from 'node-loader';","symbol":"NodeLoader Rule","correct":"module: {\n  rules: [\n    {\n      test: /\\.node$/,\n      loader: 'node-loader',\n    },\n  ],\n}"},{"note":"Loader options should be passed via the `options` property of the rule object for clarity and type safety, rather than query parameters.","wrong":"loader: 'node-loader?name=[path][name].[ext]'","symbol":"NodeLoader with Options","correct":"module: {\n  rules: [\n    {\n      test: /\\.node$/,\n      loader: 'node-loader',\n      options: {\n        name: '[path][name].[ext]',\n        flags: 2 // os.constants.dlopen.RTLD_NOW\n      },\n    },\n  ],\n}"},{"note":"While a `module.rules` configuration is generally preferred, `node-loader` can be applied inline by prefixing the import path. This requires the `!` syntax.","wrong":"import nativeModule from './path/to/my-native-module.node';","symbol":"Inline Loader Application","correct":"import nativeModule from 'node-loader!./path/to/my-native-module.node';"}],"quickstart":{"code":"const path = require('path');\nconst fs = require('fs');\n\n// Create a dummy .node file for the quickstart\nconst dummyNodeModulePath = path.resolve(__dirname, 'dummy.node');\nfs.writeFileSync(dummyNodeModulePath, '// This is a placeholder for a native Node.js module');\n\n// webpack.config.js\nmodule.exports = {\n  mode: 'development',\n  entry: './index.js',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n  },\n  resolve: {\n    extensions: ['...', '.node'],\n  },\n  target: 'node', // Crucial for node-loader\n  node: {\n    __dirname: false, // Crucial for node-loader\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.node$/,\n        loader: 'node-loader',\n        options: {\n          name: '[name].[ext]'\n        }\n      },\n    ],\n  },\n};\n\n// index.js (application entry point)\n// For demonstration, we'll pretend 'dummy.node' is a real native module\n// In a real scenario, this would be a compiled C++ addon.\nconst nativeModule = require('./dummy.node'); \n\nconsole.log('Native module loaded:', nativeModule); \n// Expected output: Native module loaded: {}\n// (Since dummy.node is empty, but the loader successfully processed it)\n\n// To run:\n// 1. npm install webpack webpack-cli node-loader\n// 2. Save the webpack config above as `webpack.config.js`\n// 3. Save the index.js content above as `index.js`\n// 4. Create a dummy.node file (as shown in the config comments)\n// 5. Run `npx webpack`\n// 6. Then `node dist/bundle.js`","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your project's webpack version to `^5.0.0` or higher, or explicitly install `node-loader@^1.0.0`.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"Version 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Set `target: 'node'` (or an appropriate Electron target) in your `webpack.config.js` when bundling code that uses native Node.js modules.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `node: { __dirname: false, __filename: false }` to your `webpack.config.js` configuration.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import a `.node` file without `node-loader` configured or the loader failing to process the file.","error":"Module parse failed: Unexpected character '�' (1:0)"},{"fix":"Change `target` in `webpack.config.js` to `node`, `async-node`, `electron-main`, `electron-renderer`, or `electron-preload`.","cause":"The Webpack `target` option is set to a non-Node.js compatible value (e.g., 'web', 'browserslist').","error":"Error: 'node-loader' can only be used with target 'node', 'async-node', 'electron-main', 'electron-renderer', or 'electron-preload'."},{"fix":"Add `node: { __dirname: false, __filename: false }` to your `webpack.config.js` to prevent Webpack from polyfilling these globals.","cause":"Webpack's default behavior for `__dirname` in Node.js environments (especially ESM) can interfere with native modules expecting standard Node.js global behavior.","error":"ReferenceError: __dirname is not defined in ES module scope"},{"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.","cause":"The `flags` option for `node-loader` was provided with a non-numeric value, or a string that could not be parsed as a number.","error":"TypeError: The 'flags' option must be a number. Received type string."}],"ecosystem":"npm"}