webpack-node-externals

3.0.0 verified Sat Apr 25 auth: no javascript

Webpack plugin to automatically exclude node_modules from the bundle when building Node.js backends. Current stable version is 3.0.0, actively maintained with releases every few months. Unlike manual externals configuration, it scans node_modules and generates exclusions automatically, supporting allowlisting, custom import types, and reading dependencies from package.json. Key differentiator: zero-config for the common case, yet fully configurable. Requires Webpack (tested with v4 and v5).

Common errors

error Error: Cannot find module 'webpack-node-externals' ↓

cause The package is not installed.

fix

npm install webpack-node-externals --save-dev

error TypeError: nodeExternals is not a function ↓

cause Incorrect import style, e.g., import { nodeExternals } from ...

fix

Use const nodeExternals = require('webpack-node-externals');

error Critical dependency: the request of a dependency is an expression ↓

cause Webpack cannot statically analyze require() calls when node_modules are included in the bundle.

fix

Use nodeExternals() in the externals configuration.

Warnings

breaking In v2.0.0, the 'whitelist' option was renamed to 'allowlist' and the old name is no longer supported. ↓

fix Replace 'whitelist' with 'allowlist' in your configuration.

breaking In v3.0.0, support for Node.js < 6 was dropped and the code syntax changed to ES6. ↓

fix Ensure your Node.js version is >= 6. No code changes required for users; the API remains compatible.

deprecated Using 'target: 'node'' for Webpack 5 is discouraged. ↓

fix Use 'externalsPresets: { node: true }' instead.

gotcha If you have aliases in your webpack config with the same name as a node_module, the module will be excluded unless explicitly allowlisted. ↓

fix Add the alias name to the 'allowlist' array.

Install

npm install webpack-node-externals

yarn add webpack-node-externals

pnpm add webpack-node-externals

Imports

nodeExternals
wrong
```
import nodeExternals from 'webpack-node-externals';
```
correct
```
const nodeExternals = require('webpack-node-externals');
```
This package uses CommonJS exports even in v3. For ESM projects, use dynamic import or keep require().
nodeExternals (named import attempt)
wrong
```
import { nodeExternals } from 'webpack-node-externals';
```
correct
```
const nodeExternals = require('webpack-node-externals');
```
There is no named export; the default export is a function. Named import will result in undefined.
nodeExternals with allowlist
wrong
```
externals: nodeExternals({ allowlist: ['module'] })
```
correct
```
externals: [nodeExternals({ allowlist: ['module'] })]
```
The result must be placed inside an array in the webpack externals configuration unless it's the only entry.

Quickstart

Minimal webpack configuration to bundle a Node.js application while excluding node_modules.

// webpack.config.js
const path = require('path');
const nodeExternals = require('webpack-node-externals');

module.exports = {
  target: 'node', // required for Node.js built-ins (path, fs, etc.)
  externals: [nodeExternals()], // exclude all node_modules
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

// For Webpack 5, replace target with:
// externalsPresets: { node: true }