webpack-node-externals

What is webpack-node-externals?

The webpack-node-externals package is a utility for Webpack that allows you to exclude node_modules from your Webpack bundle. This is particularly useful for Node.js applications where you want to keep your bundle size small and avoid bundling dependencies that are already available in the node_modules directory.

What are webpack-node-externals's main functionalities?

Exclude node_modules

This feature allows you to exclude all modules in the node_modules directory from your Webpack bundle. This is useful for server-side applications where you don't want to bundle dependencies that are already available in the node_modules directory.

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

module.exports = {
  // Other webpack configuration options
  externals: [nodeExternals()]
};

Whitelist specific modules

This feature allows you to specify certain modules that should not be excluded from the bundle, even if they are in the node_modules directory. This is useful if you have a module that you want to include in your bundle for some reason.

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

module.exports = {
  // Other webpack configuration options
  externals: [nodeExternals({
    whitelist: ['module-name']
  })]
};

Custom file extensions

This feature allows you to read the list of modules to exclude from a file, such as package.json. This can be useful for more complex configurations where you want to manage the list of external modules in a separate file.

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

module.exports = {
  // Other webpack configuration options
  externals: [nodeExternals({
    modulesFromFile: true
  })]
};

Other packages similar to webpack-node-externals

webpack-externals-plugin

The webpack-externals-plugin is another Webpack plugin that allows you to specify external dependencies that should not be bundled. It provides more flexibility in defining externals, including the ability to use regular expressions. However, it may require more configuration compared to webpack-node-externals.

webpack-common-shake

The webpack-common-shake plugin is designed to perform tree-shaking on CommonJS modules. While it is not a direct replacement for webpack-node-externals, it can help reduce bundle size by eliminating unused code. It is more focused on optimizing the code that is included in the bundle rather than excluding entire modules.

README

Webpack node modules externals

Easily exclude node modules in Webpack

Webpack allows you to define externals - modules that should not be bundled.

When bundling with Webpack for the backend - you usually wouldn't want to bundle its node_modules dependencies. This library creates an externals function that ignores node_modules when bundling in Webpack.
(Inspired by the great Backend apps with Webpack series)

Quick usage

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

In your webpack.config.js:

var nodeExternals = require('webpack-node-externals');
...
module.exports = {
    ...
    target: 'node', // in order to ignore built-in modules like path, fs, etc.
    externals: [nodeExternals()], // in order to ignore all modules in node_modules folder
    ...
};

And that's it. All node modules will no longer be bundled but will be left as require('module').

Detailed overview

Description

This library scans the node_modules folder for all node_modules names, and builds an externals function that tells Webpack not to bundle those modules, or any sub-modules of theirs.

Configuration

This library accepts an options object.

options.whitelist (=[])

An array of paths for the externals to whitelist, so they will be included in the bundle. Can accept regex patterns.

options.importType (='commonjs')

The method in which unbundled modules will be required in the code. Best to leave as commonjs for node modules.

options.modulesDir (='node_modules')

The folder in which to search for the node modules.

options.modulesFromFile (=false)

Read the modules from the package.json file instead of the node_modules folder.

Example

var nodeExternals = require('webpack-node-externals');
...
module.exports = {
    ...
    target: 'node', // important in order not to bundle built-in modules like path, fs, etc.
    externals: [nodeExternals({
        // this WILL include `jquery` and `webpack/hot/dev-server` in the bundle, as well as `lodash/*`
        whitelist: ['jquery', 'webpack/hot/dev-server', /^lodash/]
    })],
    ...
};

For most use cases, the defaults of importType and modulesDir should be used.

Q&A

Why not just use a regex in the Webpack config?

Webpack allows inserting regex in the externals array, to capture non-relative modules:

{
    externals: [
        // Every non-relative module is external
        // abc -> require("abc")
        /^[a-z\-0-9]+$/
    ]
}

However, this will leave unbundled all non-relative requires, so it does not account for aliases that may be defined in webpack itself. This library scans the node_modules folder, so it only leaves unbundled the actual node modules that are being used.

Contribute

Contributions and pull requests are welcome. Please run the tests to make sure nothing breaks.

Test

npm run test

License

MIT