Configuration

Out of the box, webpack won't require you to use a configuration file. However, it will assume the entry point of your project is src/index.js and will output the result in dist/main.js minified and optimized for production.

Usually, your projects will need to extend this functionality, for this you can create a webpack.config.js file in the root folder and webpack will automatically use it.

All the available configuration options are specified below.

Use a different configuration file

If for some reason you want to use a different configuration file depending on certain situations, you can change this via command line by using the --config flag.

package.json

"scripts": {
  "build": "webpack --config prod.config.js"
}

Set up a new webpack project

Webpack has a huge set of options which might be overwhelming to you, please take advantage of webpack-cli's init command which could rapidly generate webpack configuration files for your project requirements, it will ask you a couple of questions before creating a configuration file.

npx webpack init

npx might prompt you to install @webpack-cli/generators if it is not yet installed in the project or globally. You might also get additional packages installed to your project depending on the choices you've made during the configuration generation.

$ npx webpack init

[webpack-cli] For using this command you need to install: '@webpack-cli/generators' package.
[webpack-cli] Would you like to install '@webpack-cli/generators' package? (That will run 'npm install -D @webpack-cli/generators') (Y/n)
devDependencies:
+ @webpack-cli/generators 2.5.0
? Which of the following JS solutions do you want to use? ES6
? Do you want to use webpack-dev-server? Yes
? Do you want to simplify the creation of HTML files for your bundle? Yes
? Do you want to add PWA support? No
? Which of the following CSS solutions do you want to use? CSS only
? Will you be using PostCSS in your project? Yes
? Do you want to extract CSS for every file? Only for Production
? Do you like to install prettier to format generated configuration? Yes
? Pick a package manager: pnpm
[webpack-cli] ℹ INFO  Initialising project...

devDependencies:
+ @babel/core 7.19.3
+ @babel/preset-env 7.19.4
+ autoprefixer 10.4.12
+ babel-loader 8.2.5
+ css-loader 6.7.1
+ html-webpack-plugin 5.5.0
+ mini-css-extract-plugin 2.6.1
+ postcss 8.4.17
+ postcss-loader 7.0.1
+ prettier 2.7.1
+ style-loader 3.3.1
+ webpack-dev-server 4.11.1
[webpack-cli] Project has been initialised with webpack!

Configuration Languages

Webpack accepts configuration files written in multiple programming and data languages. The list of supported file extensions can be found in the node-interpret package. Using node-interpret, webpack can handle many different types of configuration files.

TypeScript

To write the webpack configuration in TypeScript, you would first install the necessary dependencies, i.e., TypeScript and the relevant type definitions from the DefinitelyTyped project:

npm install --save-dev typescript ts-node @types/node @types/webpack
# and, if using webpack-dev-server < v4.7.0
npm install --save-dev @types/webpack-dev-server

and then proceed to write your configuration:

webpack.config.ts

import path from 'path';
import webpack from 'webpack';
// in case you run into any typescript error when configuring `devServer`
import 'webpack-dev-server';

const config: webpack.Configuration = {
  mode: 'production',
  entry: './foo.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'foo.bundle.js',
  },
};

export default config;

tsconfig.json

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

The above sample assumes version >= 2.7 or newer of TypeScript is used with the new esModuleInterop and allowSyntheticDefaultImports compiler options in your tsconfig.json file.

Note that you'll also need to check your tsconfig.json file. If the module in compilerOptions in tsconfig.json is commonjs, the setting is complete, else webpack will fail with an error. This occurs because ts-node does not support any module syntax other than commonjs.

There are three solutions to this issue:

• Modify tsconfig.json.
• Modify tsconfig.json and add settings for ts-node.
• Install tsconfig-paths.

The first option is to open your tsconfig.json file and look for compilerOptions. Set target to "ES5" and module to "CommonJS" (or completely remove the module option).

The second option is to add settings for ts-node:

You can keep "module": "ESNext" for tsc, and if you use webpack, or another build tool, set an override for ts-node. ts-node config

{
  "compilerOptions": {
    "module": "ESNext",
  },
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}

The third option is to install the tsconfig-paths package:

npm install --save-dev tsconfig-paths

And create a separate TypeScript configuration specifically for your webpack configs:

tsconfig-for-webpack-config.json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "esModuleInterop": true
  }
}

Then set the environment variable process.env.TS_NODE_PROJECT provided by tsconfig-paths like so:

package.json

{
  "scripts": {
    "build": "cross-env TS_NODE_PROJECT=\"tsconfig-for-webpack-config.json\" webpack"
  }
}

CoffeeScript

Similarly, to use CoffeeScript, you would first install the necessary dependencies:

npm install --save-dev coffeescript

and then proceed to write your configuration:

webpack.config.coffee

HtmlWebpackPlugin = require('html-webpack-plugin')
webpack = require('webpack')
path = require('path')

config =
  mode: 'production'
  entry: './path/to/my/entry/file.js'
  output:
    path: path.resolve(__dirname, 'dist')
    filename: 'my-first-webpack.bundle.js'
  module: rules: [ {
    test: /\.(js|jsx)$/
    use: 'babel-loader'
  } ]
  plugins: [
    new HtmlWebpackPlugin(template: './src/index.html')
  ]

module.exports = config

Babel and JSX

In the example below JSX (React JavaScript Markup) and Babel are used, to create a JSON configuration that webpack can understand.

Courtesy of Jason Miller

First, install the necessary dependencies:

npm install --save-dev babel-register jsxobj babel-preset-es2015

.babelrc

{
  "presets": ["es2015"]
}

webpack.config.babel.js

import jsxobj from 'jsxobj';

// example of an imported plugin
const CustomPlugin = (config) => ({
  ...config,
  name: 'custom-plugin',
});

export default (
  <webpack target="web" watch mode="production">
    <entry path="src/index.js" />
    <resolve>
      <alias
        {...{
          react: 'preact-compat',
          'react-dom': 'preact-compat',
        }}
      />
    </resolve>
    <plugins>
      <CustomPlugin foo="bar" />
    </plugins>
  </webpack>
);

Configuration Types

Besides exporting a single configuration object, there are a few more ways that cover other needs as well.

Exporting a Function

Eventually you will find the need to disambiguate in your webpack.config.js between development and production builds. There are multiple ways to do that. One option is to export a function from your webpack configuration instead of exporting an object. The function will be invoked with two arguments:

• An environment as the first parameter. See the environment options CLI documentation for syntax examples.
• An options map (argv) as the second parameter. This describes the options passed to webpack, with keys such as output-path and mode.

-module.exports = {
+module.exports = function(env, argv) {
+  return {
+    mode: env.production ? 'production' : 'development',
+    devtool: env.production ? 'source-map' : 'eval',
     plugins: [
       new TerserPlugin({
         terserOptions: {
+          compress: argv.mode === 'production' // only if `--mode production` was passed
         }
       })
     ]
+  };
};

Exporting a Promise

Webpack will run the function exported by the configuration file and wait for a Promise to be returned. Handy when you need to asynchronously load configuration variables.

module.exports = () => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({
        entry: './app.js',
        /* ... */
      });
    }, 5000);
  });
};

Exporting multiple configurations

Instead of exporting a single configuration object/function, you may export multiple configurations (multiple functions are supported since webpack 3.1.0). When running webpack, all configurations are built. For instance, this is useful for bundling a library for multiple targets such as AMD and CommonJS:

module.exports = [
  {
    output: {
      filename: './dist-amd.js',
      libraryTarget: 'amd',
    },
    name: 'amd',
    entry: './app.js',
    mode: 'production',
  },
  {
    output: {
      filename: './dist-commonjs.js',
      libraryTarget: 'commonjs',
    },
    name: 'commonjs',
    entry: './app.js',
    mode: 'production',
  },
];

dependencies

In case you have a configuration that depends on the output of another configuration, you can specify a list of dependencies using the dependencies array.

webpack.config.js

module.exports = [
  {
    name: 'client',
    target: 'web',
    // …
  },
  {
    name: 'server',
    target: 'node',
    dependencies: ['client'],
  },
];

parallelism

In case you export multiple configurations, you can use the parallelism option on the configuration array to specify the maximum number of compilers that will compile in parallel.

• Type: number
• Available: 5.22.0+

webpack.config.js

module.exports = [
  {
    //config-1
  },
  {
    //config-2
  },
];
module.exports.parallelism = 1;

Entry and Context

The entry object is where webpack looks to start building the bundle. The context is an absolute string to the directory that contains the entry files.

context

string

The base directory, an absolute path, for resolving entry points and loaders from the configuration.

const path = require('path');

module.exports = {
  //...
  context: path.resolve(__dirname, 'app'),
};

By default, the current working directory of Node.js is used, but it's recommended to pass a value in your configuration. This makes your configuration independent from CWD (current working directory).

---

entry

string [string] object = { <key> string | [string] | object = { import string | [string], dependOn string | [string], filename string, layer string, runtime string | false }} (function() => string | [string] | object = { <key> string | [string] } | object = { import string | [string], dependOn string | [string], filename string, layer string, runtime string | false })

The point or points where to start the application bundling process. If an array is passed then all items will be processed.

A dynamically loaded module is not an entry point.

A rule to consider: one entry point per HTML page. SPA: one entry point, MPA: multiple entry points.

module.exports = {
  //...
  entry: {
    home: './home.js',
    about: './about.js',
    contact: './contact.js',
  },
};

Naming

If a string or array of strings is passed, the chunk is named main. If an object is passed, each key is the name of a chunk, and the value describes the entry point for the chunk.

Entry descriptor

If an object is passed the value might be a string, array of strings, or a descriptor:

module.exports = {
  //...
  entry: {
    home: './home.js',
    shared: ['react', 'react-dom', 'redux', 'react-redux'],
    catalog: {
      import: './catalog.js',
      filename: 'pages/catalog.js',
      dependOn: 'shared',
      chunkLoading: false, // Disable chunks that are loaded on demand and put everything in the main chunk.
    },
    personal: {
      import: './personal.js',
      filename: 'pages/personal.js',
      dependOn: 'shared',
      chunkLoading: 'jsonp',
      asyncChunks: true, // Create async chunks that are loaded on demand.
      layer: 'name of layer', // set the layer for an entry point
    },
  },
};

Descriptor syntax might be used to pass additional options to an entry point.

Output filename

By default, the output filename for the entry chunk is extracted from output.filename but you can specify a custom output filename for a specific entry:

module.exports = {
  //...
  entry: {
    app: './app.js',
    home: { import: './contact.js', filename: 'pages/[name].js' },
    about: { import: './about.js', filename: 'pages/[name].js' },
  },
};

Descriptor syntax was used here to pass filename-option to the specific entry points.

Dependencies

By default, every entry chunk stores all the modules that it uses. With dependOn option you can share the modules from one entry chunk to another:

module.exports = {
  //...
  entry: {
    app: { import: './app.js', dependOn: 'react-vendors' },
    'react-vendors': ['react', 'react-dom', 'prop-types'],
  },
};

The app chunk will not contain the modules that react-vendors have.

dependOn option can also accept an array of strings:

module.exports = {
  //...
  entry: {
    moment: { import: 'moment-mini', runtime: 'runtime' },
    reactvendors: { import: ['react', 'react-dom'], runtime: 'runtime' },
    testapp: {
      import: './wwwroot/component/TestApp.tsx',
      dependOn: ['reactvendors', 'moment'],
    },
  },
};

Also, you can specify multiple files per entry using an array:

module.exports = {
  //...
  entry: {
    app: { import: ['./app.js', './app2.js'], dependOn: 'react-vendors' },
    'react-vendors': ['react', 'react-dom', 'prop-types'],
  },
};

Dynamic entry

If a function is passed then it will be invoked on every make event.

Note that the make event triggers when webpack starts and for every invalidation when watching for file changes.

module.exports = {
  //...
  entry: () => './demo',
};

or

module.exports = {
  //...
  entry: () => new Promise((resolve) => resolve(['./demo', './demo2'])),
};

For example: you can use dynamic entries to get the actual entries from an external source (remote server, file system content or database):

webpack.config.js

module.exports = {
  entry() {
    return fetchPathsFromSomeExternalSource(); // returns a promise that will be resolved with something like ['src/main-layout.js', 'src/admin-layout.js']
  },
};

When combining with the output.library option: If an array is passed only the last item is exported.

Runtime chunk

It allows setting the runtime chunk for an entry point and setting it to false to avoid a new runtime chunk since webpack v5.43.0.

optimization.runtimeChunk allows setting it globally for unspecified entry points.

module.exports = {
  //...
  entry: {
    home: {
      import: './home.js',
      runtime: 'home-runtime',
    },
    about: {
      import: './about.js',
      runtime: false,
    },
  },
};

Mode

Providing the mode configuration option tells webpack to use its built-in optimizations accordingly.

string = 'production': 'none' | 'development' | 'production'

Usage

Provide the mode option in the config:

module.exports = {
  mode: 'development',
};

or pass it as a CLI argument:

webpack --mode=development

The following string values are supported:

Option	Description
development	Sets process.env.NODE_ENV on DefinePlugin to value development. Enables useful names for modules and chunks.
production	Sets process.env.NODE_ENV on DefinePlugin to value production. Enables deterministic mangled names for modules and chunks, FlagDependencyUsagePlugin, FlagIncludedChunksPlugin, ModuleConcatenationPlugin, NoEmitOnErrorsPlugin and TerserPlugin.
none	Opts out of any default optimization options

If not set, webpack sets production as the default value for mode.

Mode: development

// webpack.development.config.js
module.exports = {
  mode: 'development',
};

Mode: production

// webpack.production.config.js
module.exports = {
  mode: 'production',
};

Mode: none

// webpack.custom.config.js
module.exports = {
  mode: 'none',
};

If you want to change the behavior according to the mode variable inside the webpack.config.js, you have to export a function instead of an object:

var config = {
  entry: './app.js',
  //...
};

module.exports = (env, argv) => {
  if (argv.mode === 'development') {
    config.devtool = 'source-map';
  }

  if (argv.mode === 'production') {
    //...
  }

  return config;
};

Output

The top-level output key contains a set of options instructing webpack on how and where it should output your bundles, assets, and anything else you bundle or load with webpack.

output.assetModuleFilename

string = '[hash][ext][query]' function (pathData, assetInfo) => string

The same as output.filename but for Asset Modules.

[name], [file], [query], [fragment], [base], and [path] are set to an empty string for the assets built from data URI replacements.

output.asyncChunks

boolean = true

Create async chunks that are loaded on demand.

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    asyncChunks: true,
  },
};

output.auxiliaryComment

string object

When used in tandem with output.library and output.libraryTarget, this option allows users to insert comments within the export wrapper. To insert the same comment for each libraryTarget type, set auxiliaryComment to a string:

webpack.config.js

module.exports = {
  //...
  output: {
    library: 'someLibName',
    libraryTarget: 'umd',
    filename: 'someLibName.js',
    auxiliaryComment: 'Test Comment',
  },
};

which will yield the following:

someLibName.js

(function webpackUniversalModuleDefinition(root, factory) {
  // Test Comment
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory(require('lodash'));
  // Test Comment
  else if (typeof define === 'function' && define.amd)
    define(['lodash'], factory);
  // Test Comment
  else if (typeof exports === 'object')
    exports['someLibName'] = factory(require('lodash'));
  // Test Comment
  else root['someLibName'] = factory(root['_']);
})(this, function (__WEBPACK_EXTERNAL_MODULE_1__) {
  // ...
});

For fine-grained control over each libraryTarget comment, pass an object:

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    auxiliaryComment: {
      root: 'Root Comment',
      commonjs: 'CommonJS Comment',
      commonjs2: 'CommonJS2 Comment',
      amd: 'AMD Comment',
    },
  },
};

output.charset

boolean = true

Tells webpack to add charset="utf-8" to the HTML <script> tag.

output.chunkFilename

string = '[id].js' function (pathData, assetInfo) => string

This option determines the name of non-initial chunk files. See output.filename option for details on the possible values.

Note that these filenames need to be generated at runtime to send the requests for chunks. Because of this, placeholders like [name] and [chunkhash] need to add a mapping from chunk id to placeholder value to the output bundle with the webpack runtime. This increases the size and may invalidate the bundle when placeholder value for any chunk changes.

By default [id].js is used or a value inferred from output.filename ([name] is replaced with [id] or [id]. is prepended).

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    chunkFilename: '[id].js',
  },
};

Usage as a function:

webpack.config.js

module.exports = {
  //...
  output: {
    chunkFilename: (pathData) => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};

output.chunkFormat

false string: 'array-push' | 'commonjs' | 'module' | <any string>

The format of chunks (formats included by default are 'array-push' (web/WebWorker), 'commonjs' (node.js), 'module' (ESM), but others might be added by plugins).

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    chunkFormat: 'commonjs',
  },
};

output.chunkLoadTimeout

number = 120000

The Number of milliseconds before chunk request expires. This option is supported since webpack 2.6.0.

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    chunkLoadTimeout: 30000,
  },
};

output.chunkLoadingGlobal

string = 'webpackChunkwebpack'

The global variable is used by webpack for loading chunks.

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    chunkLoadingGlobal: 'myCustomFunc',
  },
};

output.chunkLoading

false string: 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import' | <any string>

The method to load chunks (methods included by default are 'jsonp' (web), 'import' (ESM), 'importScripts' (WebWorker), 'require' (sync node.js), 'async-node' (async node.js), but others might be added by plugins).

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    chunkLoading: 'async-node',
  },
};

output.clean

5.20.0+

boolean { dry?: boolean, keep?: RegExp | string | ((filename: string) => boolean) }

module.exports = {
  //...
  output: {
    clean: true, // Clean the output directory before emit.
  },
};

module.exports = {
  //...
  output: {
    clean: {
      dry: true, // Log the assets that should be removed instead of deleting them.
    },
  },
};

module.exports = {
  //...
  output: {
    clean: {
      keep: /ignored\/dir\//, // Keep these assets under 'ignored/dir'.
    },
  },
};

// or

module.exports = {
  //...
  output: {
    clean: {
      keep(asset) {
        return asset.includes('ignored/dir');
      },
    },
  },
};

You can also use it with hook:

webpack.CleanPlugin.getCompilationHooks(compilation).keep.tap(
  'Test',
  (asset) => {
    if (/ignored\/dir\//.test(asset)) return true;
  }
);

output.compareBeforeEmit

boolean = true

Tells webpack to check if to be emitted file already exists and has the same content before writing to the output file system.

module.exports = {
  //...
  output: {
    compareBeforeEmit: false,
  },
};

output.crossOriginLoading

boolean = false string: 'anonymous' | 'use-credentials'

Tells webpack to enable cross-origin loading of chunks. Only takes effect when the target is set to 'web', which uses JSONP for loading on-demand chunks, by adding script tags.

• 'anonymous' - Enable cross-origin loading without credentials
• 'use-credentials' - Enable cross-origin loading with credentials

output.cssChunkFilename

string function (pathData, assetInfo) => string

This option determines the name of non-initial CSS output files on disk. See output.filename option for details on the possible values.

You must not specify an absolute path here. However, feel free to include folders separated by '/'. This specified path combines with the output.path value to pinpoint the location on the disk.

output.cssFilename

string function (pathData, assetInfo) => string

This option determines the name of CSS output files on disk. See output.filename option for details on the possible values.

You must not specify an absolute path here. However, feel free to include folders separated by '/'. This specified path combines with the output.path value to pinpoint the location on the disk.

output.cssHeadDataCompression

5.91.0+

boolean

This option determines whether to compress the metadata generated in the head tag of CSS files. This option defaults to true in production and false in development mode respectively.

output.devtoolFallbackModuleFilenameTemplate

string function (info)

A fallback is used when the template string or function above yields duplicates.

See output.devtoolModuleFilenameTemplate.

output.devtoolModuleFilenameTemplate

string = 'webpack://[namespace]/[resource-path]?[loaders]' function (info) => string

This option is only used when devtool uses an option that requires module names.

Customize the names used in each source map's sources array. This can be done by passing a template string or function. For example, when using devtool: 'eval'.

webpack.config.js

module.exports = {
  //...
  output: {
    devtoolModuleFilenameTemplate:
      'webpack://[namespace]/[resource-path]?[loaders]',
  },
};

The following substitutions are available in template strings (via webpack's internal ModuleFilenameHelpers):

Template	Description
[absolute-resource-path]	The absolute filename
[all-loaders]	Automatic and explicit loaders and params up to the name of the first loader
[hash]	The hash of the module identifier
[id]	The module identifier
[loaders]	Explicit loaders and params up to the name of the first loader
[resource]	The path used to resolve the file and any query params used on the first loader
[resource-path]	The path used to resolve the file without any query params
[namespace]	The modules namespace. This is usually the library name when building as a library, empty otherwise

When using a function, the same options are available camel-cased via the info parameter:

module.exports = {
  //...
  output: {
    devtoolModuleFilenameTemplate: (info) => {
      return `webpack:///${info.resourcePath}?${info.loaders}`;
    },
  },
};

If multiple modules would result in the same name, output.devtoolFallbackModuleFilenameTemplate is used instead for these modules.

output.devtoolNamespace

string

This option determines the module's namespace used with the output.devtoolModuleFilenameTemplate. When not specified, it will default to the value of: output.uniqueName. It's used to prevent source file path collisions in sourcemaps when loading multiple libraries built with webpack.

For example, if you have 2 libraries, with namespaces library1 and library2, which both have a file ./src/index.js (with potentially different contents), they will expose these files as webpack://library1/./src/index.js and webpack://library2/./src/index.js.

You can use template strings like [name] to dynamically generate namespaces based on the build context, providing additional flexibility.

webpack.config.js

module.exports = {
  //...
  output: {
    filename: "[name]-bundle.js",
		library: "library-[name]",
		libraryTarget: "commonjs",
		devtoolNamespace: "library-[name]" // Sets a unique namespace for each library
  },
};

output.enabledChunkLoadingTypes

[string: 'jsonp' | 'import-scripts' | 'require' | 'async-node' | <any string>]

List of chunk loading types enabled for use by entry points. Will be automatically filled by webpack. Only needed when using a function as entry option and returning chunkLoading option from there.

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    enabledChunkLoadingTypes: ['jsonp', 'require'],
  },
};

output.enabledLibraryTypes

[string]

List of library types enabled for use by entry points.

module.exports = {
  //...
  output: {
    enabledLibraryTypes: ['module'],
  },
};

output.enabledWasmLoadingTypes

[string]

List of wasm loading types enabled for use by entry points.

module.exports = {
  //...
  output: {
    enabledWasmLoadingTypes: ['fetch'],
  },
};

output.environment

Tell webpack what kind of ES-features may be used in the generated runtime-code.

module.exports = {
  output: {
    environment: {
      // The environment supports arrow functions ('() => { ... }').
      arrowFunction: true,
      // The environment supports async function and await ('async function () { await ... }').
      asyncFunction: true,
      // The environment supports BigInt as literal (123n).
      bigIntLiteral: false,
      // The environment supports const and let for variable declarations.
      const: true,
      // The environment supports destructuring ('{ a, b } = obj').
      destructuring: true,
      // The environment supports 'document' variable.
      document: true,
      // The environment supports an async import() function to import EcmaScript modules.
      dynamicImport: false,
      // The environment supports an async import() when creating a worker, only for web targets at the moment.
      dynamicImportInWorker: false,
      // The environment supports 'for of' iteration ('for (const x of array) { ... }').
      forOf: true,
      // The environment supports 'globalThis'.
      globalThis: true,
      // The environment supports ECMAScript Module syntax to import ECMAScript modules (import ... from '...').
      module: false,
      // Determines if the node: prefix is generated for core module imports in environments that support it.
      // This is only applicable to Webpack runtime code.
      nodePrefixForCoreModules: false,
      // The environment supports optional chaining ('obj?.a' or 'obj?.()').
      optionalChaining: true,
      // The environment supports template literals.
      templateLiteral: true,
    },
  },
};

output.filename

string function (pathData, assetInfo) => string

This option determines the name of each output bundle. The bundle is written to the directory specified by the output.path option.

For a single entry point, this can be a static name.

webpack.config.js

module.exports = {
  //...
  output: {
    filename: 'bundle.js',
  },
};

However, when creating multiple bundles via more than one entry point, code splitting, or various plugins, you should use one of the following substitutions to give each bundle a unique name...

Using entry name:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[name].bundle.js',
  },
};

Using internal chunk id:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[id].bundle.js',
  },
};

Using hashes generated from the generated content:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[contenthash].bundle.js',
  },
};

Combining multiple substitutions:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[name].[contenthash].bundle.js',
  },
};

Using the function to return the filename:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: (pathData) => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};

Make sure to read the Caching guide for details. There are more steps involved than only setting this option.

Note this option is called filename but you are still allowed to use something like 'js/[name]/bundle.js' to create a folder structure.

Template strings

The following substitutions are available in template strings (via webpack's internal TemplatedPathPlugin):

Substitutions available on Compilation-level:

Template	Description
[fullhash]	The full hash of compilation
[hash]	Same, but deprecated

Substitutions available on Chunk-level:

Template	Description
[id]	The ID of the chunk
[name]	The name of the chunk, if set, otherwise the ID of the chunk
[chunkhash]	The hash of the chunk, including all elements of the chunk
[contenthash]	The hash of the chunk, including only elements of this content type (affected by optimization.realContentHash)

Substitutions available on Module-level:

Template	Description
[id]	The ID of the module
[moduleid]	Same, but deprecated
[hash]	The hash of the module
[modulehash]	Same, but deprecated
[contenthash]	The hash of the content of the module

Substitutions available on File-level:

Template	Description
[file]	Filename and path, without query or fragment
[query]	Query with leading ?
[fragment]	Fragment with leading #
[base]	Only filename (including extensions), without path
[filebase]	Same, but deprecated
[path]	Only path, without filename
[name]	Only filename without extension or path
[ext]	Extension with leading . (not available for output.filename)

Substitutions available on URL-level:

Template	Description
[url]	URL

The length of hashes ([hash], [contenthash] or [chunkhash]) can be specified using [hash:16] (defaults to 20). Alternatively, specify output.hashDigestLength to configure the length globally.

It is possible to filter out placeholder replacement when you want to use one of the placeholders in the actual file name. For example, to output a file [name].js, you have to escape the [name] placeholder by adding backslashes between the brackets. So that [\name\] generates [name] instead of getting replaced with the name of the asset.

Example: [\id\] generates [id] instead of getting replaced with the id.

If using a function for this option, the function will be passed an object containing data for the substitutions in the table above. Substitutions will be applied to the returned string too. The passed object will have this type: (properties available depending on context)

type PathData = {
  hash: string;
  hashWithLength: (number) => string;
  chunk: Chunk | ChunkPathData;
  module: Module | ModulePathData;
  contentHashType: string;
  contentHash: string;
  contentHashWithLength: (number) => string;
  filename: string;
  url: string;
  runtime: string | SortableSet<string>;
  chunkGraph: ChunkGraph;
};
type ChunkPathData = {
  id: string | number;
  name: string;
  hash: string;
  hashWithLength: (number) => string;
  contentHash: Record<string, string>;
  contentHashWithLength: Record<string, (number) => string>;
};
type ModulePathData = {
  id: string | number;
  hash: string;
  hashWithLength: (number) => string;
};

output.globalObject

string = 'self'

When targeting a library, especially when library.type is 'umd', this option indicates what global object will be used to mount the library. To make UMD build available on both browsers and Node.js, set output.globalObject option to 'this'. Defaults to self for Web-like targets.

The return value of your entry point will be assigned to the global object using the value of output.library.name. Depending on the value of the type option, the global object could change respectively, e.g., self, global, or globalThis.

For example:

webpack.config.js

module.exports = {
  // ...
  output: {
    library: {
      name: 'myLib',
      type: 'umd',
    },
    filename: 'myLib.js',
    globalObject: 'this',
  },
};

output.hashDigest

string = 'hex'

The encoding to use when generating the hash. All encodings from Node.JS' hash.digest are supported. Using 'base64' for filenames might be problematic since it has the character / in its alphabet. Likewise 'latin1' could contain any character.

output.hashDigestLength

number = 20

The prefix length of the hash digest to use.

output.hashFunction

string = 'md4' function

The hashing algorithm to use. All functions from Node.JS' crypto.createHash are supported. Since 4.0.0-alpha2, the hashFunction can now be a constructor to a custom hash function. You can provide a non-crypto hash function for performance reasons.

module.exports = {
  //...
  output: {
    hashFunction: require('metrohash').MetroHash64,
  },
};

Make sure that the hashing function will have an update and digest methods available.

output.hashSalt

An optional salt to update the hash via Node.JS' hash.update.

output.hotUpdateChunkFilename

string = '[id].[fullhash].hot-update.js'

Customize the filenames of hot update chunks. See output.filename option for details on the possible values.

The only placeholders allowed here are [id] and [fullhash], the default being:

webpack.config.js

module.exports = {
  //...
  output: {
    hotUpdateChunkFilename: '[id].[fullhash].hot-update.js',
  },
};

output.hotUpdateGlobal

string

Only used when target is set to 'web', which uses JSONP for loading hot updates.

A JSONP function is used to asynchronously load hot-update chunks.

For details see output.chunkLoadingGlobal.

output.hotUpdateMainFilename

string = '[runtime].[fullhash].hot-update.json' function

Customize the main hot update filename. [fullhash] and [runtime] are available as placeholder.

output.iife

boolean = true

Tells webpack to add IIFE wrapper around emitted code.

module.exports = {
  //...
  output: {
    iife: true,
  },
};

output.ignoreBrowserWarnings

5.81.0+

boolean = false

Hide warnings from the browser console in production. This option does not affect the terminal/console output.

webpack.config.js

module.exports = {
  //...
  output: {
    ignoreBrowserWarnings: true,
  },
};

output.importFunctionName

string = 'import'

The name of the native import() function. Can be used for polyfilling, e.g. with dynamic-import-polyfill.

webpack.config.js

module.exports = {
  //...
  output: {
    importFunctionName: '__import__',
  },
};

output.importMetaName

string

The name of the native import.meta object (can be exchanged for a polyfill).

webpack.config.js

module.exports = {
  //...
  output: {
    importMetaName: 'pseudoImport.meta',
  },
};

output.library

Output a library exposing the exports of your entry point.

• Type: string | string[] | object

Let's take a look at an example.

webpack.config.js

module.exports = {
  // …
  entry: './src/index.js',
  output: {
    library: 'MyLibrary',
  },
};

Say you have exported a function in your src/index.js entry:

export function hello(name) {
  console.log(`hello ${name}`);
}

Now the variable MyLibrary will be bound with the exports of your entry file, and here's how to consume the webpack bundled library:

<script src="https://example.org/path/to/my-library.js"></script>
<script>
  MyLibrary.hello('webpack');
</script>

In the above example, we're passing a single entry file to entry, however, webpack can accept many kinds of entry point, e.g., an array, or an object.

1. If you provide an array as the entry point, only the last one in the array will be exposed.

   module.exports = {
     // …
     entry: ['./src/a.js', './src/b.js'], // only exports in b.js will be exposed
     output: {
       library: 'MyLibrary',
     },
   };

2. If an object is provided as the entry point, all entries can be exposed using the array syntax of library:

   module.exports = {
     // …
     entry: {
       a: './src/a.js',
       b: './src/b.js',
     },
     output: {
       filename: '[name].js',
       library: ['MyLibrary', '[name]'], // name is a placeholder here
     },
   };

   Assuming that both a.js and b.js export a function hello, here's how to consume the libraries:

   <script src="https://example.org/path/to/a.js"></script>
   <script src="https://example.org/path/to/b.js"></script>
   <script>
     MyLibrary.a.hello('webpack');
     MyLibrary.b.hello('webpack');
   </script>

   See this example for more.

   Note that the above configuration won't work as expected if you're going to configure library options per entry point. Here is how to do it under each of your entries:

   module.exports = {
     // …
     entry: {
       main: {
         import: './src/index.js',
         library: {
           // all options under `output.library` can be used here
           name: 'MyLibrary',
           type: 'umd',
           umdNamedDefine: true,
         },
       },
       another: {
         import: './src/another.js',
         library: {
           name: 'AnotherLibrary',
           type: 'commonjs2',
         },
       },
     },
   };

output.library.amdContainer

5.78.0+

Use a container(defined in global space) for calling define/require functions in an AMD module.

module.exports = {
  // …
  output: {
    library: {
      amdContainer: 'window["clientContainer"]',
      type: 'amd', // or 'amd-require'
    },
  },
};

Which will result in the following bundle:

window['clientContainer'].define(/*define args*/); // or 'amd-require' window['clientContainer'].require(/*require args*/);

output.library.name

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
    },
  },
};

Specify a name for the library.

• Type:

  string | string[] | {amd?: string, commonjs?: string, root?: string | string[]}

output.library.type

Configure how the library will be exposed.

• Type: string

  Types included by default are 'var', 'module', 'modern-module', 'assign', 'assign-properties', 'this', 'window', 'self', 'global', 'commonjs', 'commonjs2', 'commonjs-module', 'commonjs-static', 'amd', 'amd-require', 'umd', 'umd2', 'jsonp' and 'system', but others might be added by plugins.

For the following examples, we'll use _entry_return_ to indicate the values returned by the entry point.

Expose a Variable

These options assign the return value of the entry point (e.g. whatever the entry point exported) to the name provided by output.library.name at whatever scope the bundle was included at.

type: 'var'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
    },
  },
};

When your library is loaded, the return value of your entry point will be assigned to a variable:

var MyLibrary = _entry_return_;

// In a separate script with `MyLibrary` loaded…
MyLibrary.doSomething();

type: 'assign'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'assign',
    },
  },
};

This will generate an implied global which has the potential to reassign an existing value (use with caution):

MyLibrary = _entry_return_;

Be aware that if MyLibrary isn't defined earlier your library will be set in global scope.

type: 'assign-properties'

5.16.0+

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'assign-properties',
    },
  },
};

Similar to type: 'assign' but a safer option as it will reuse MyLibrary if it already exists:

// only create MyLibrary if it doesn't exist
MyLibrary = typeof MyLibrary === 'undefined' ? {} : MyLibrary;
// then copy the return value to MyLibrary
// similarly to what Object.assign does

// for instance, you export a `hello` function in your entry as follow
export function hello(name) {
  console.log(`Hello ${name}`);
}

// In another script with MyLibrary loaded
// you can run `hello` function like so
MyLibrary.hello('World');

Expose Via Object Assignment

These options assign the return value of the entry point (e.g. whatever the entry point exported) to a specific object under the name defined by output.library.name.

type: 'this'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'this',
    },
  },
};

The return value of your entry point will be assigned to this under the property named by output.library.name. The meaning of this is up to you:

this['MyLibrary'] = _entry_return_;

// In a separate script...
this.MyLibrary.doSomething();
MyLibrary.doSomething(); // if `this` is window

type: 'window'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'window',
    },
  },
};

The return value of your entry point will be assigned to the window object using the output.library.name value.

window['MyLibrary'] = _entry_return_;

window.MyLibrary.doSomething();

type: 'global'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'global',
    },
  },
};

The return value of your entry point will be assigned to the global object using the output.library.name value. Depending on the target value, the global object could change respectively, e.g., self, global or globalThis.

global['MyLibrary'] = _entry_return_;

global.MyLibrary.doSomething();

type: 'commonjs'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'commonjs',
    },
  },
};

The return value of your entry point will be assigned to the exports object using the output.library.name value. As the name implies, this is used in CommonJS environments.

exports['MyLibrary'] = _entry_return_;

require('MyLibrary').doSomething();

Module Definition Systems

These options will result in a bundle that comes with a complete header to ensure compatibility with various module systems. The output.library.name option will take on a different meaning under the following output.library.type options.

type: 'module'

module.exports = {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: 'module',
    },
  },
};

Output ES Module.

However this feature is still experimental and not fully supported yet, so make sure to enable experiments.outputModule beforehand. In addition, you can track the development progress in this thread.

type: 'modern-module'

v5.93.0+

module.exports = {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: 'modern-module',
    },
  },
};

This configuration generates tree-shakable output for ES Modules.

However this feature is still experimental and not fully supported yet, so make sure to enable experiments.outputModule beforehand.

type: 'commonjs2'

module.exports = {
  // …
  output: {
    library: {
      // note there's no `name` here
      type: 'commonjs2',
    },
  },
};

The return value of your entry point will be assigned to the module.exports. As the name implies, this is used in Node.js (CommonJS) environments:

module.exports = _entry_return_;

require('MyLibrary').doSomething();

If we specify output.library.name with type: commmonjs2, the return value of your entry point will be assigned to the module.exports.[output.library.name].

type: 'commonjs-module'

commonjs-module is equivalent to commonjs2. We may remove commonjs-module in future versions.

type: 'commonjs-static'

5.66.0+

module.exports = {
  // …
  output: {
    library: {
      // note there's no `name` here
      type: 'commonjs-static',
    },
  },
};

Individual exports will be set as properties on module.exports. The "static" in the name refers to the output being statically analysable, and thus named exports are importable into ESM via Node.js:

Input:

export function doSomething() {}

Output:

function doSomething() {}

// …

exports.doSomething = __webpack_exports__.doSomething;

Consumption (CommonJS):

const { doSomething } = require('./output.cjs'); // doSomething => [Function: doSomething]

Consumption (ESM):

import { doSomething } from './output.cjs'; // doSomething => [Function: doSomething]

type: 'amd'

This will expose your library as an AMD module.

AMD modules require that the entry chunk (e.g. the first script loaded by the <script> tag) be defined with specific properties, such as to define and require which is typically provided by RequireJS or any compatible loaders (such as almond). Otherwise, loading the resulting AMD bundle directly will result in an error like define is not defined.

With the following configuration...

module.exports = {
  //...
  output: {
    library: {
      name: 'MyLibrary',
      type: 'amd',
    },
  },
};

The generated output will be defined with the name "MyLibrary", i.e.:

define('MyLibrary', [], function () {
  return _entry_return_;
});

The bundle can be included as part of a script tag, and the bundle can be invoked like so:

require(['MyLibrary'], function (MyLibrary) {
  // Do something with the library...
});

If output.library.name is undefined, the following is generated instead.

define(function () {
  return _entry_return_;
});

This bundle will not work as expected, or not work at all (in the case of the almond loader) if loaded directly with a <script> tag. It will only work through a RequireJS compatible asynchronous module loader through the actual path to that file, so in this case, the output.path and output.filename may become important for this particular setup if these are exposed directly on the server.

type: 'amd-require'

module.exports = {
  //...
  output: {
    library: {
      name: 'MyLibrary',
      type: 'amd-require',
    },
  },
};

This packages your output with an immediately executed AMD require(dependencies, factory) wrapper.

The 'amd-require' type allows for the use of AMD dependencies without needing a separate later invocation. As with the 'amd' type, this depends on the appropriate require function being available in the environment in which the webpack output is loaded.

With this type, the library name can't be used.

type: 'umd'

This exposes your library under all the module definitions, allowing it to work with CommonJS, AMD, and as global variable. Take a look at the UMD Repository to learn more.

In this case, you need the library.name property to name your module:

module.exports = {
  //...
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
    },
  },
};

And finally the output is:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else if (typeof exports === 'object') exports['MyLibrary'] = factory();
  else root['MyLibrary'] = factory();
})(global, function () {
  return _entry_return_;
});

Note that omitting library.name will result in the assignment of all properties returned by the entry point be assigned directly to the root object, as documented under the object assignment section. Example:

module.exports = {
  //...
  output: {
    type: 'umd',
  },
};

The output will be:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else {
    var a = factory();
    for (var i in a) (typeof exports === 'object' ? exports : root)[i] = a[i];
  }
})(global, function () {
  return _entry_return_;
});

You may specify an object for library.name for differing names per targets:

module.exports = {
  //...
  output: {
    library: {
      name: {
        root: 'MyLibrary',
        amd: 'my-library',
        commonjs: 'my-common-library',
      },
      type: 'umd',
    },
  },
};

type: 'system'

This will expose your library as a System.register module. This feature was first released in webpack 4.30.0.

System modules require that a global variable System is present in the browser when the webpack bundle is executed. Compiling to System.register format allows you to System.import('/bundle.js') without additional configuration and has your webpack bundle loaded into the System module registry.

module.exports = {
  //...
  output: {
    library: {
      type: 'system',
    },
  },
};

Output:

System.register([], function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
  return {
    execute: function () {
      // ...
    },
  };
});

By adding output.library.name to configuration in addition to having output.library.type set to system, the output bundle will have the library name as an argument to System.register:

System.register(
  'MyLibrary',
  [],
  function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
    return {
      execute: function () {
        // ...
      },
    };
  }
);

Other Types

type: 'jsonp'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'jsonp',
    },
  },
};

This will wrap the return value of your entry point into a jsonp wrapper.

MyLibrary(_entry_return_);

The dependencies for your library will be defined by the externals config.

output.library.export

Specify which export should be exposed as a library.

• Type: string | string[]

It is undefined by default, which will export the whole (namespace) object. The examples below demonstrate the effect of this configuration when using output.library.type: 'var'.

module.exports = {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
      export: 'default',
    },
  },
};

The default export of your entry point will be assigned to the library name:

// if your entry has a default export
var MyLibrary = _entry_return_.default;

You can pass an array to output.library.export as well, it will be interpreted as a path to a module to be assigned to the library name:

module.exports = {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
      export: ['default', 'subModule'],
    },
  },
};

And here's the library code:

var MyLibrary = _entry_return_.default.subModule;

output.library.auxiliaryComment

Add a comment in the UMD wrapper.

• Type: string | { amd?: string, commonjs?: string, commonjs2?: string, root?: string }

To insert the same comment for each umd type, set auxiliaryComment to a string:

module.exports = {
  // …
  mode: 'development',
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      auxiliaryComment: 'Test Comment',
    },
  },
};

which will yield the following:

(function webpackUniversalModuleDefinition(root, factory) {
  //Test Comment
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  //Test Comment
  else if (typeof define === 'function' && define.amd) define([], factory);
  //Test Comment
  else if (typeof exports === 'object') exports['MyLibrary'] = factory();
  //Test Comment
  else root['MyLibrary'] = factory();
})(self, function () {
  return _entry_return_;
});

For fine-grained control, pass an object:

module.exports = {
  // …
  mode: 'development',
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      auxiliaryComment: {
        root: 'Root Comment',
        commonjs: 'CommonJS Comment',
        commonjs2: 'CommonJS2 Comment',
        amd: 'AMD Comment',
      },
    },
  },
};

output.library.umdNamedDefine

boolean

When using output.library.type: "umd", setting output.library.umdNamedDefine to true will name the AMD module of the UMD build. Otherwise, an anonymous define is used.

module.exports = {
  //...
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      umdNamedDefine: true,
    },
  },
};

The AMD module will be:

define('MyLibrary', [], factory);

output.libraryExport

string [string]

Configure which module or modules will be exposed via the libraryTarget. It is undefined by default, same behaviour will be applied if you set libraryTarget to an empty string e.g. '' it will export the whole (namespace) object. The examples below demonstrate the effect of this configuration when using libraryTarget: 'var'.

The following configurations are supported:

libraryExport: 'default' - The default export of your entry point will be assigned to the library target:

// if your entry has a default export of `MyDefaultModule`
var MyDefaultModule = _entry_return_.default;

libraryExport: 'MyModule' - The specified module will be assigned to the library target:

var MyModule = _entry_return_.MyModule;

libraryExport: ['MyModule', 'MySubModule'] - The array is interpreted as a path to a module to be assigned to the library target:

var MySubModule = _entry_return_.MyModule.MySubModule;

With the libraryExport configurations specified above, the resulting libraries could be utilized as such:

MyDefaultModule.doSomething();
MyModule.doSomething();
MySubModule.doSomething();

output.libraryTarget

string = 'var'

Configure how the library will be exposed. Any one of the following options can be used. Please note that this option works in conjunction with the value assigned to output.library. For the following examples, it is assumed that the value of output.library is configured as MyLibrary.

Expose a Variable

These options assign the return value of the entry point (e.g. whatever the entry point exported) to the name provided by output.library at whatever scope the bundle was included at.

libraryTarget: 'var'

When your library is loaded, the return value of your entry point will be assigned to a variable:

var MyLibrary = _entry_return_;

// In a separate script...
MyLibrary.doSomething();

libraryTarget: 'assign'

This will generate an implied global which has the potential to reassign an existing value (use with caution):

MyLibrary = _entry_return_;

Be aware that if MyLibrary isn't defined earlier your library will be set in the global scope.

libraryTarget: 'assign-properties'

5.16.0+

Copy the return value to a target object if it exists, otherwise create the target object first:

// create the target object if it doesn't exist
MyLibrary = typeof MyLibrary === 'undefined' ? {} : MyLibrary;
// then copy the return value to MyLibrary
// similarly to what Object.assign does

// for instance, you export a `hello` function in your entry as follow
export function hello(name) {
  console.log(`Hello ${name}`);
}

// In another script running MyLibrary
// you can run `hello` function like so
MyLibrary.hello('World');

Expose Via Object Assignment

These options assign the return value of the entry point (e.g. whatever the entry point exported) to a specific object under the name defined by output.library.

If output.library is not assigned a non-empty string, the default behavior is that all properties returned by the entry point will be assigned to the object as defined for the particular output.libraryTarget, via the following code fragment:

(function (e, a) {
  for (var i in a) {
    e[i] = a[i];
  }
})(output.libraryTarget, _entry_return_);

libraryTarget: 'this'

The return value of your entry point will be assigned to this under the property named by output.library. The meaning of this is up to you:

this['MyLibrary'] = _entry_return_;

// In a separate script...
this.MyLibrary.doSomething();
MyLibrary.doSomething(); // if this is window

libraryTarget: 'window'

The return value of your entry point will be assigned to the window object using the output.library value.

window['MyLibrary'] = _entry_return_;

window.MyLibrary.doSomething();

libraryTarget: 'global'

The return value of your entry point will be assigned to the global object using the output.library value.

global['MyLibrary'] = _entry_return_;

global.MyLibrary.doSomething();

libraryTarget: 'commonjs'

The return value of your entry point will be assigned to the exports object using the output.library value. As the name implies, this is used in CommonJS environments.

exports['MyLibrary'] = _entry_return_;

require('MyLibrary').doSomething();

Module Definition Systems

These options will result in a bundle that comes with a complete header to ensure compatibility with various module systems. The output.library option will take on a different meaning under the following output.libraryTarget options.

libraryTarget: 'module'

Output ES Module. Make sure to enable experiments.outputModule beforehand.

Note that this feature is not fully supported yet, please track the progress in this thread.

libraryTarget: 'commonjs2'

The return value of your entry point will be assigned to the module.exports. As the name implies, this is used in CommonJS environments:

module.exports = _entry_return_;

require('MyLibrary').doSomething();

Note that output.library can't be used with this particular output.libraryTarget, for further details, please read this issue.

libraryTarget: 'amd'

This will expose your library as an AMD module.

AMD modules require that the entry chunk (e.g. the first script loaded by the <script> tag) be defined with specific properties, such as to define and require which is typically provided by RequireJS or any compatible loaders (such as almond). Otherwise, loading the resulting AMD bundle directly will result in an error like define is not defined.

With the following configuration...

module.exports = {
  //...
  output: {
    library: 'MyLibrary',
    libraryTarget: 'amd',
  },
};

The generated output will be defined with the name "MyLibrary", i.e.

define('MyLibrary', [], function () {
  return _entry_return_;
});

The bundle can be included as part of a script tag, and the bundle can be invoked like so:

require(['MyLibrary'], function (MyLibrary) {
  // Do something with the library...
});

If output.library is undefined, the following is generated instead.

define([], function () {
  return _entry_return_;
});

This bundle will not work as expected, or not work at all (in the case of the almond loader) if loaded directly with a <script> tag. It will only work through a RequireJS compatible asynchronous module loader through the actual path to that file, so in this case, the output.path and output.filename may become important for this particular setup if these are exposed directly on the server.

libraryTarget: 'amd-require'

This packages your output with an immediately executed AMD require(dependencies, factory) wrapper.

The 'amd-require' target allows for the use of AMD dependencies without needing a separate later invocation. As with the 'amd' target, this depends on the appropriate require function being available in the environment in which the webpack output is loaded.

With this target, the library name is ignored.

libraryTarget: 'umd'

This exposes your library under all the module definitions, allowing it to work with CommonJS, AMD and as a global variable. Take a look at the UMD Repository to learn more.

In this case, you need the library property to name your module:

module.exports = {
  //...
  output: {
    library: 'MyLibrary',
    libraryTarget: 'umd',
  },
};

And finally the output is:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else if (typeof exports === 'object') exports['MyLibrary'] = factory();
  else root['MyLibrary'] = factory();
})(typeof self !== 'undefined' ? self : this, function () {
  return _entry_return_;
});

Note that omitting the library will result in the assignment of all properties returned by the entry point be assigned directly to the root object, as documented under the object assignment section. Example:

module.exports = {
  //...
  output: {
    libraryTarget: 'umd',
  },
};

The output will be:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else {
    var a = factory();
    for (var i in a) (typeof exports === 'object' ? exports : root)[i] = a[i];
  }
})(typeof self !== 'undefined' ? self : this, function () {
  return _entry_return_;
});

Since webpack 3.1.0, you may specify an object for library for differing names per targets:

module.exports = {
  //...
  output: {
    library: {
      root: 'MyLibrary',
      amd: 'my-library',
      commonjs: 'my-common-library',
    },
    libraryTarget: 'umd',
  },
};

libraryTarget: 'system'

This will expose your library as a System.register module. This feature was first released in webpack 4.30.0.

System modules require that a global variable System is present in the browser when the webpack bundle is executed. Compiling to System.register format allows you to System.import('/bundle.js') without additional configuration and has your webpack bundle loaded into the System module registry.

module.exports = {
  //...
  output: {
    libraryTarget: 'system',
  },
};

Output:

System.register([], function (_export) {
  return {
    setters: [],
    execute: function () {
      // ...
    },
  };
});

By adding output.library to configuration in addition to having output.libraryTarget set to system, the output bundle will have the library name as an argument to System.register:

System.register('my-library', [], function (_export) {
  return {
    setters: [],
    execute: function () {
      // ...
    },
  };
});

You can access SystemJS context via __system_context__:

// Log the URL of the current SystemJS module
console.log(__system_context__.meta.url);

// Import a SystemJS module, with the current SystemJS module's url as the parentUrl
__system_context__.import('./other-file.js').then((m) => {
  console.log(m);
});

Other Targets

libraryTarget: 'jsonp'

This will wrap the return value of your entry point into a jsonp wrapper.

MyLibrary(_entry_return_);

The dependencies for your library will be defined by the externals config.

output.module

boolean = false

Output JavaScript files as module type. Disabled by default as it's an experimental feature.

When enabled, webpack will set output.iife to false, output.scriptType to 'module' and terserOptions.module to true internally.

If you're using webpack to compile a library to be consumed by others, make sure to set output.libraryTarget to 'module' when output.module is true.

module.exports = {
  //...
  experiments: {
    outputModule: true,
  },
  output: {
    module: true,
  },
};

output.path

string = path.join(process.cwd(), 'dist')

The output directory as an absolute path.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  output: {
    path: path.resolve(__dirname, 'dist/assets'),
  },
};

Note that [fullhash] in this parameter will be replaced with a hash of the compilation. See the Caching guide for details.

output.pathinfo

boolean=true string: 'verbose'

Tells webpack to include comments in bundles with information about the contained modules. This option defaults to true in development and false in production mode respectively. 'verbose' shows more information like exports, runtime requirements and bailouts.

webpack.config.js

module.exports = {
  //...
  output: {
    pathinfo: true,
  },
};

output.publicPath

• Type:

  • function

  • string

    output.publicPath defaults to 'auto' with web and web-worker targets, see this guide for its use cases.

This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.

This option specifies the public URL of the output directory when referenced in a browser. A relative URL is resolved relative to the HTML page (or <base> tag). Server-relative URLs, protocol-relative URLs or absolute URLs are also possible and sometimes required, i. e. when hosting assets on a CDN.

The value of the option is prefixed to every URL created by the runtime or loaders. Because of this the value of this option ends with / in most cases.

A rule to consider: The URL of your output.path from the view of the HTML page.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  output: {
    path: path.resolve(__dirname, 'public/assets'),
    publicPath: 'https://cdn.example.com/assets/',
  },
};

For this configuration:

webpack.config.js

module.exports = {
  //...
  output: {
    publicPath: '/assets/',
    chunkFilename: '[id].chunk.js',
  },
};

A request to a chunk will look like /assets/4.chunk.js.

A loader outputting HTML might emit something like this:

<link href="/assets/spinner.gif" />

or when loading an image in CSS:

background-image: url(/assets/spinner.gif);

The webpack-dev-server also takes a hint from publicPath, using it to determine where to serve the output files from.

Note that [fullhash] in this parameter will be replaced with a hash of the compilation. See the Caching guide for details.

Examples:

module.exports = {
  //...
  output: {
    // One of the below
    publicPath: 'auto', // It automatically determines the public path from either `import.meta.url`, `document.currentScript`, `<script />` or `self.location`.
    publicPath: 'https://cdn.example.com/assets/', // CDN (always HTTPS)
    publicPath: '//cdn.example.com/assets/', // CDN (same protocol)
    publicPath: '/assets/', // server-relative
    publicPath: 'assets/', // relative to HTML page
    publicPath: '../assets/', // relative to HTML page
    publicPath: '', // relative to HTML page (same directory)
  },
};

In cases where the publicPath of output files can't be known at compile time, it can be left blank and set dynamically at runtime in the entry file using the free variable __webpack_public_path__.

__webpack_public_path__ = myRuntimePublicPath;

// rest of your application entry

See this discussion for more information on __webpack_public_path__.

output.scriptType

string: 'module' | 'text/javascript' boolean = false

This option allows loading asynchronous chunks with a custom script type, such as <script type="module" ...>.

module.exports = {
  //...
  output: {
    scriptType: 'module',
  },
};

output.sourceMapFilename

string = '[file].map[query]'

Configure how source maps are named. Only takes effect when devtool is set to 'source-map', which writes an output file.

The [name], [id], [fullhash] and [chunkhash] substitutions from output.filename can be used. In addition to those, you can use substitutions listed under Filename-level in Template strings.

output.sourcePrefix

string = ''

Change the prefix for each line in the output bundles.

webpack.config.js

module.exports = {
  //...
  output: {
    sourcePrefix: '\t',
  },
};

output.strictModuleErrorHandling

Handle error in module loading as per EcmaScript Modules spec at a performance cost.

• Type: boolean
• Available: 5.25.0+

module.exports = {
  //...
  output: {
    strictModuleErrorHandling: true,
  },
};

output.strictModuleExceptionHandling

boolean = false

Tell webpack to remove a module from the module instance cache (require.cache) if it throws an exception when it is required.

It defaults to false for performance reasons.

When set to false, the module is not removed from cache, which results in the exception getting thrown only on the first require call (making it incompatible with node.js).

For instance, consider module.js:

throw new Error('error');

With strictModuleExceptionHandling set to false, only the first require throws an exception:

// with strictModuleExceptionHandling = false
require('module'); // <- throws
require('module'); // <- doesn't throw

Instead, with strictModuleExceptionHandling set to true, all requires of this module throw an exception:

// with strictModuleExceptionHandling = true
require('module'); // <- throws
require('module'); // <- also throws

output.trustedTypes

true string object

5.37.0+

Controls Trusted Types compatibility. When enabled, webpack will detect Trusted Types support and, if they are supported, use Trusted Types policies to create script URLs it loads dynamically. Use when the application runs under a require-trusted-types-for Content Security Policy directive.

It is disabled by default (no compatibility, script URLs are strings).

• When set to true, webpack will use output.uniqueName as the Trusted Types policy name.
• When set to a non-empty string, its value will be used as a policy name.
• When set to an object, the policy name is taken from the object's policyName property.

webpack.config.js

module.exports = {
  //...
  output: {
    //...
    trustedTypes: {
      policyName: 'my-application#webpack',
    },
  },
};

output.trustedTypes.onPolicyCreationFailure

string = 'stop': 'continue' | 'stop'

5.82.0+

Determine whether to proceed with loading in anticipation that require-trusted-types-for 'script' has not been enforced or to immediately fail when the call to trustedTypes.createPolicy(...) fails due to the policy name being absent from the CSP trusted-types list or being a duplicate.

module.exports = {
  //...
  output: {
    //...
    trustedTypes: {
      policyName: 'my-application#webpack',
      onPolicyCreationFailure: 'continue',
    },
  },
};

output.umdNamedDefine

boolean

When using libraryTarget: "umd", setting output.umdNamedDefine to true will name the AMD module of the UMD build. Otherwise an anonymous define is used.

module.exports = {
  //...
  output: {
    umdNamedDefine: true,
  },
};

output.uniqueName

string

A unique name of the webpack build to avoid multiple webpack runtimes to conflict when using globals. It defaults to output.library name or the package name from package.json in the context, if both aren't found, it is set to an ''.

output.uniqueName will be used to generate unique globals for:

• output.chunkLoadingGlobal

webpack.config.js

module.exports = {
  // ...
  output: {
    uniqueName: 'my-package-xyz',
  },
};

output.wasmLoading

false 'fetch-streaming' | 'fetch' | 'async-node' string

Option to set the method of loading WebAssembly Modules. Methods included by default are 'fetch' (web/WebWorker), 'async-node' (Node.js), but others might be added by plugins.

The default value can be affected by different target:

• Defaults to 'fetch' if target is set to 'web', 'webworker', 'electron-renderer' or 'node-webkit'.
• Defaults to 'async-node' if target is set to 'node', 'async-node', 'electron-main' or 'electron-preload'.

module.exports = {
  //...
  output: {
    wasmLoading: 'fetch',
  },
};

output.webassemblyModuleFilename

string = '[hash].module.wasm'

Specifies the filename of WebAssembly modules. It should be provided as a relative path within the output.path directory

module.exports = {
  //...
  output: {
    webassemblyModuleFilename: '[id].[hash].wasm',
  },
};

output.workerChunkLoading

string: 'require' | 'import-scripts' | 'async-node' | 'import' | 'universal' boolean: false

The new option workerChunkLoading controls the chunk loading of workers.

webpack.config.js

module.exports = {
  //...
  output: {
    workerChunkLoading: false,
  },
};

output.workerPublicPath

string

Set a public path for Worker, defaults to value of output.publicPath. Only use this option if your worker scripts are located in a different path from your other scripts.

webpack.config.js

module.exports = {
  //...
  output: {
    workerPublicPath: '/workerPublicPath2/',
  },
};

output.workerWasmLoading

false 'fetch-streaming' | 'fetch' | 'async-node' string

Option to set the method of loading WebAssembly Modules in workers, defaults to the value of output.wasmLoading.

webpack.config.js

module.exports = {
  //...
  output: {
    workerWasmLoading: 'fetch',
  },
};

Module

These options determine how the different types of modules within a project will be treated.

module.defaultRules

An array of rules applied by default for modules.

See source code for details.

module.exports = {
  module: {
    defaultRules: [
      '...', // you can use "..." to reference those rules applied by webpack by default
    ],
  },
};

Starting with webpack 5.87.0, falsy values including 0, "", false, null and undefined are allowed to pass to module.defaultRules to conditionally disable specific rules.

module.exports = {
  module: {
    defaultRules: [
      false &&
        {
          // this rule will be disabled
        },
    ],
  },
};

module.generator

5.12.0+

It's possible to configure all generators' options in one place with a module.generator.

webpack.config.js

module.exports = {
  module: {
    generator: {
      asset: {
        // Generator options for asset modules

        // Indicates if this asset should be treated as binary. Set to 'false' to handle it as text instead. Available since webpack 5.93.0
        binary: false,

        // The options for data url generator.
        dataUrl: {
          // Asset encoding (defaults to "base64")
          // type: 'base64' | false
          encoding: 'base64',
          // Asset mimetype (getting from file extension by default).
          // type: string
          mimetype: 'image/png',
        },

        // Emit an output asset from this asset module. This can be set to 'false' to omit emitting e. g. for SSR.
        // type: boolean
        emit: true,

        // Customize filename for this asset module
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        filename: 'static/[path][name][ext]',

        // Customize publicPath for asset modules, available since webpack 5.28.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        publicPath: 'https://cdn/assets/',

        // Emit the asset in the specified folder relative to 'output.path', available since webpack 5.67.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        outputPath: 'cdn-assets/',
      },
      'asset/inline': {
        // Generator options for asset/inline modules

        // Indicates if this asset should be treated as binary. Set to 'false' to handle it as text instead. Available since webpack 5.93.0
        binary: false,

        // The options for data url generator.
        dataUrl: {
          // Asset encoding (defaults to "base64")
          // type: 'base64' | false
          encoding: 'base64',
          // Asset mimetype (getting from file extension by default).
          // type: string
          mimetype: 'image/png',
        },
      },
      'asset/resource': {
        // Generator options for asset/resource modules

        // Indicates if this asset should be treated as binary. Set to 'false' to handle it as text instead. Available since webpack 5.93.0
        binary: false,

        // Emit an output asset from this asset module. This can be set to 'false' to omit emitting e. g. for SSR.
        // type: boolean
        emit: true,

        // Customize filename for this asset module
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        filename: 'static/[path][name][ext]',

        // Customize publicPath for asset/resource modules, available since webpack 5.28.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        publicPath: 'https://cdn/assets/',

        // Emit the asset in the specified folder relative to 'output.path', available since webpack 5.67.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        outputPath: 'cdn-assets/',
      },
      javascript: {
        // No generator options are supported for this module type yet
      },
      'javascript/auto': {
        // ditto
      },
      'javascript/dynamic': {
        // ditto
      },
      'javascript/esm': {
        // ditto
      },
      css: {
        // Generator options for css modules

        // Avoid generating and loading a stylesheet and only embed exports from css into output javascript files.
        // type: boolean, available since webpack 5.90.0
        exportsOnly: true,

        // Customize how css export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.
        // type: 'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only' | ((name: string) => string)
        // available since webpack 5.90.4
        exportsConvention: 'camel-case-only',
      },
      'css/auto': {
        // Generator options for css/auto modules

        // Avoid generating and loading a stylesheet and only embed exports from css into output javascript files.
        // type: boolean, available since webpack 5.90.0
        exportsOnly: true,

        // Customize how css export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.
        // type: 'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only' | ((name: string) => string)
        // available since webpack 5.90.4
        exportsConvention: 'camel-case-only',

        // Customize the format of the local class names generated for css modules.
        // type: string, besides the substitutions at File-level and Module-level in https://webpack.js.org/configuration/output/#template-strings, also include [uniqueName] and [local].
        // available since webpack 5.90.4
        localIdentName: '[uniqueName]-[id]-[local]',
      },
      'css/global': {
        // ditto
      },
      'css/module': {
        // ditto
      },
      // others…
    },
  },
};

module.parser

5.12.0+

Similar to the module.generator, you can configure all parsers' options in one place with a module.parser.

webpack.config.js

module.exports = {
  module: {
    parser: {
      asset: {
        // Parser options for asset modules

        // The options for data url generator.
        dataUrl: {
          // Asset encoding (defaults to "base64")
          // type: 'base64' | false
          encoding: 'base64',
          // Asset mimetype (getting from file extension by default).
          // type: string
          mimetype: 'image/png',
        },

        // Emit an output asset from this asset module. This can be set to 'false' to omit emitting e. g. for SSR.
        // type: boolean
        emit: true,

        // Customize filename for this asset module
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        filename: 'static/[path][name][ext]',

        // Customize publicPath for asset modules, available since webpack 5.28.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        publicPath: 'https://cdn/assets/',

        // Emit the asset in the specified folder relative to 'output.path', available since webpack 5.67.0
        // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
        outputPath: 'cdn-assets/',
      },
      'asset/inline': {
        // No parser options are supported for this module type yet
      },
      'asset/resource': {
        // ditto
      },
      'asset/source': {
        // ditto
      },
      javascript: {
        // Parser options for javascript modules
        // e.g, enable parsing of require.ensure syntax
        requireEnsure: true,
        // Set the module to `'strict'` or `'non-strict'` mode. This can affect the module's behavior, as some behaviors differ between strict and non-strict modes.
        overrideStrict: 'non-strict',
      },
      'javascript/auto': {
        // ditto
      },
      'javascript/dynamic': {
        // ditto
      },
      'javascript/esm': {
        // ditto
      },
      css: {
        // Parser options for css modules

        // Use ES modules named export for css exports, available since webpack 5.90.0
        // type: boolean
        namedExports: true,
      },
      'css/auto': {
        // ditto
      },
      'css/global': {
        // ditto
      },
      'css/module': {
        // ditto
      },
      // others…
    },
  },
};

module.parser.css.namedExports

This option enables the use of ES modules named export for CSS exports. When set to true, the CSS module will export its classes and styles using named exports.

• Type: boolean

• Available: 5.90.0+

• Example:

  module.exports = {
    module: {
      parser: {
        css: {
          namedExports: true,
        },
      },
    },
  };

When namedExports is false for CSS modules, you can retrieve CSS classes using various import methods. Named exports are redirected to improve developer experience (DX), facilitating a smooth transition from default exports to named exports:

import * as styles from './styles.module.css';
import styles1 from './styles.module.css';
import { foo } from './styles.module.css';

console.log(styles.default.foo); // Access via styles.default
console.log(styles.foo); // Access directly from styles
console.log(styles1.foo); // Access via default import styles1
console.log(foo); // Direct named import

When namedExports is enabled (default behavior), you can use only named exports to import CSS classes.

/* styles.css */
.header {
  color: blue;
}

.footer {
  color: green;
}

import { header, footer } from './styles.module.css';

By enabling namedExports, you adopt a more modular and maintainable approach to managing CSS in JavaScript projects, leveraging ES module syntax for clearer and more explicit imports.

module.parser.javascript

Configure options for JavaScript parser.

module.exports = {
  module: {
    parser: {
      javascript: {
        // ...
        commonjsMagicComments: true,
      },
    },
  },
};

It's allowed to configure those options in Rule.parser as well to target specific modules.

module.parser.javascript.commonjsMagicComments

Enable magic comments support for CommonJS.

• Type: boolean

• Available: 5.17.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          commonjsMagicComments: true,
        },
      },
    },
  };

Note that only webpackIgnore comment is supported at the moment:

const x = require(/* webpackIgnore: true */ 'x');

module.parser.javascript.dynamicImportFetchPriority

Specify the global fetchPriority for dynamic import.

• Type: 'low' | 'high' | 'auto' | false

• Available: 5.87.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          dynamicImportFetchPriority: 'high',
        },
      },
    },
  };

module.parser.javascript.dynamicImportMode

Specifies global mode for dynamic import.

• Type: 'eager' | 'weak' | 'lazy' | 'lazy-once'

• Available: 5.73.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          dynamicImportMode: 'lazy',
        },
      },
    },
  };

module.parser.javascript.dynamicImportPrefetch

Specifies global prefetch for dynamic import.

• Type: number | boolean

• Available: 5.73.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          dynamicImportPrefetch: false,
        },
      },
    },
  };

module.parser.javascript.dynamicImportPreload

Specifies global preload for dynamic import.

• Type: number | boolean

• Available: 5.73.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          dynamicImportPreload: false,
        },
      },
    },
  };

module.parser.javascript.exportsPresence

Specifies the behavior of invalid export names in \"import ... from ...\" and \"export ... from ...\".

• Type: 'error' | 'warn' | 'auto' | false

• Available: 5.62.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          exportsPresence: 'error',
        },
      },
    },
  };

module.parser.javascript.importExportsPresence

Specifies the behavior of invalid export names in \"import ... from ...\".

• Type: 'error' | 'warn' | 'auto' | false

• Available: 5.62.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          importExportsPresence: 'error',
        },
      },
    },
  };

module.parser.javascript.importMeta

Enable or disable evaluating import.meta.

• Type: boolean = true

• Available: 5.68.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          importMeta: false,
        },
      },
    },
  };

module.parser.javascript.importMetaContext

Enable/disable evaluating import.meta.webpackContext.

• Type: boolean

• Available: 5.70.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          importMetaContext: true,
        },
      },
    },
  };

module.parser.javascript.overrideStrict

Set the module to 'strict' or 'non-strict' mode. This can affect the module's behavior, as some behaviors differ between strict and non-strict modes.

• Type: 'strict' | 'non-strict'

• Available: 5.93.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          overrideStrict: 'non-strict',
        },
      },
    },
  };

module.parser.javascript.reexportExportsPresence

Specifies the behavior of invalid export names in \"export ... from ...\". This might be useful to disable during the migration from \"export ... from ...\" to \"export type ... from ...\" when reexporting types in TypeScript.

• Type: 'error' | 'warn' | 'auto' | false

• Available: 5.62.0+

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          reexportExportsPresence: 'error',
        },
      },
    },
  };

module.parser.javascript.url

Enable parsing of new URL() syntax.

• Type: boolean = true | 'relative'

• Example:

  module.exports = {
    module: {
      parser: {
        javascript: {
          url: false, // disable parsing of `new URL()` syntax
        },
      },
    },
  };

The 'relative' value for module.parser.javascript.url is available since webpack 5.23.0. When used, webpack would generate relative URLs for new URL() syntax, i.e., there's no base URL included in the result URL:

<!-- with 'relative' -->
<img src="c43188443804f1b1f534.svg" />

<!-- without 'relative' -->
<img src="file:///path/to/project/dist/c43188443804f1b1f534.svg" />

1. This is useful for SSR (Server side rendering) when base URL is not known by server (and it saves a few bytes). To be identical it must also be used for the client build.
2. Also for static site generators, mini-css-plugin and html-plugin, etc. where server side rendering is commonly needed.

module.noParse

RegExp [RegExp] function(resource) string [string]

Prevent webpack from parsing any files matching the given regular expression(s). Ignored files should not have calls to import, require, define or any other importing mechanism. This can boost build performance when ignoring large libraries.

noParse can be also used as a way to deliberately prevent expansion of all import, require, define etc. calls for cases when those calls are unreachable at runtime. For example, when building a project for 'browser' target and using a third-party library that was prebuilt for both browser and Node.js and it requires Node.js built-ins e.g. require('os').

webpack.config.js

module.exports = {
  //...
  module: {
    noParse: /jquery|lodash|src[\\/]vendor[\\/]somelib/,
  },
};

module.exports = {
  //...
  module: {
    noParse: (content) =>
      /jquery|lodash|src[\\/]vendor[\\/]somelib/.test(content),
  },
};

module.unsafeCache

boolean function (module)

Cache the resolution of module requests. There are a couple of defaults for module.unsafeCache:

• false if cache is disabled.
• true if cache is enabled and the module appears to come from node modules, false otherwise.

webpack.config.js

module.exports = {
  //...
  module: {
    unsafeCache: false,
  },
};

module.rules

(Rule | undefined | null | false | "" | 0 | "...")[]

An array of Rules which are matched to requests when modules are created. These rules can modify how the module is created. They can apply loaders to the module, or modify the parser.

As of webpack 5.87.0, falsy values such as false, undefined, null and 0 can be used to conditionally disable a rule.

Rule

object

A Rule can be separated into three parts — Conditions, Results and nested Rules.

Rule Conditions

There are two input values for the conditions:

1. The resource: An absolute path to the file requested. It's already resolved according to the resolve rules.

2. The issuer: An absolute path to the file of the module which requested the resource. It's the location of the import.

Example: When we import './style.css' within app.js, the resource is /path/to/style.css and the issuer is /path/to/app.js.

In a Rule the properties test, include, exclude and resource are matched with the resource and the property issuer is matched with the issuer.

When using multiple conditions, all conditions must match.

Rule results

Rule results are used only when the Rule condition matches.

There are two output values of a Rule:

1. Applied loaders: An array of loaders applied to the resource.
2. Parser options: An options object which should be used to create the parser for this module.

These properties affect the loaders: loader, options, use.

For compatibility also these properties: query, loaders.

The enforce property affects the loader category. Whether it's a normal, pre- or post- loader.

The parser property affects the parser options.

Nested rules

Nested rules can be specified under the properties rules and oneOf.

These rules are evaluated only when the parent Rule condition matches. Each nested rule can contain its own conditions.

The order of evaluation is as follows:

1. The parent rule
2. rules
3. oneOf

Rule.assert

A Condition that allows you to match the import assertion of a dependency and apply specific rules based on the assertion type.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        // Handles imports with the assertion "assert { type: 'json' }"
        assert: { type: 'json' },
        loader: require.resolve('./loader-assert.js'),
      },
    ],
  },
};

index.js

import one from './pkg-1.json' assert { type: 'json' };

In this example, Rule.assert is used to apply loader-assert.js to any module imported with the assertion assert { type: "json" }, ensuring that JSON files are processed correctly.

Rule.compiler

A Condition that allows you to match the child compiler name.

webpack.config.js

module.exports = {
  // ...
  name: 'compiler',
  module: {
    rules: [
      {
        test: /a\.js$/,
        compiler: 'compiler', // Matches the "compiler" name, loader will be applied
        use: './loader',
      },
      {
        test: /b\.js$/,
        compiler: 'other-compiler', // Does not match the "compiler" name, loader will NOT be applied
        use: './loader',
      },
    ],
  },
};

Rule.enforce

string

Possible values: 'pre' | 'post'

Specifies the category of the loader. No value means normal loader.

There is also an additional category "inlined loader" which are loaders applied inline of the import/require.

There are two phases that all loaders enter one after the other:

1. Pitching phase: the pitch method on loaders is called in the order post, inline, normal, pre. See Pitching Loader for details.
2. Normal phase: the normal method on loaders is executed in the order pre, normal, inline, post. Transformation on the source code of a module happens in this phase.

All normal loaders can be omitted (overridden) by prefixing ! in the request.

All normal and pre loaders can be omitted (overridden) by prefixing -! in the request.

All normal, post and pre loaders can be omitted (overridden) by prefixing !! in the request.

// Disable normal loaders
import { a } from '!./file1.js';

// Disable preloaders and normal loaders
import { b } from '-!./file2.js';

// Disable all loaders
import { c } from '!!./file3.js';

Inline loaders and ! prefixes should not be used as they are non-standard. They may be used by loader generated code.

Rule.exclude

Exclude all modules matching any of these conditions. If you supply a Rule.exclude option, you cannot also supply a Rule.resource. See Rule.resource and Condition.exclude for details.

Rule.include

Include all modules matching any of these conditions. If you supply a Rule.include option, you cannot also supply a Rule.resource. See Rule.resource and Condition.include for details.

Rule.issuer

A Condition to match against the module that issued the request. In the following example, the issuer for the a.js request would be the path to the index.js file.

index.js

import A from './a.js';

This option can be used to apply loaders to the dependencies of a specific module or set of modules.

Rule.issuerLayer

Allows to filter/match by layer of the issuer.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        issuerLayer: 'other-layer',
      },
    ],
  },
};

Rule.layer

string

Specify the layer in which the module should be placed in. A group of modules could be united in one layer which could then be used in split chunks, stats or entry options.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /module-layer-change/,
        layer: 'layer',
      },
    ],
  },
};

Rule.loader

Rule.loader is a shortcut to Rule.use: [ { loader } ]. See Rule.use and UseEntry.loader for details.

Rule.loaders

Rule.loaders is an alias to Rule.use. See Rule.use for details.

Rule.mimetype

You can match config rules to data uri with mimetype.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        mimetype: 'application/json',
        type: 'json',
      },
    ],
  },
};

application/json, text/javascript, application/javascript, application/node and application/wasm are already included by default as mimetype.

Rule.oneOf

An array of Rules from which only the first matching Rule is used when the Rule matches.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.css$/,
        oneOf: [
          {
            resourceQuery: /inline/, // foo.css?inline
            type: 'asset/inline',
          },
          {
            resourceQuery: /external/, // foo.css?external
            type: 'asset/resource',
          },
        ],
      },
    ],
  },
};

Rule.options / Rule.query

Rule.options and Rule.query are shortcuts to Rule.use: [ { options } ]. See Rule.use and UseEntry.options for details.

Rule.parser

An object with parser options. All applied parser options are merged.

Parsers may inspect these options and disable or reconfigure themselves accordingly. Most of the default plugins interpret the values as follows:

• Setting the option to false disables the parser.
• Setting the option to true or leaving it undefined enables the parser.

However, parser plugins may accept more than only a boolean. For example, the internal NodeStuffPlugin can accept an object instead of true to add additional options for a particular Rule.

Examples (parser options by the default plugins):

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        parser: {
          amd: false, // disable AMD
          commonjs: false, // disable CommonJS
          system: false, // disable SystemJS
          harmony: false, // disable ES2015 Harmony import/export
          requireInclude: false, // disable require.include
          requireEnsure: false, // disable require.ensure
          requireContext: false, // disable require.context
          browserify: false, // disable special handling of Browserify bundles
          requireJs: false, // disable requirejs.*
          node: false, // disable __dirname, __filename, module, require.extensions, require.main, etc.
          commonjsMagicComments: false, // disable magic comments support for CommonJS
          node: {}, // reconfigure node layer on module level
          worker: ['default from web-worker', '...'], // Customize the WebWorker handling for javascript files, "..." refers to the defaults.
        },
      },
    ],
  },
};

If Rule.type is an asset then Rules.parser option may be an object or a function that describes a condition whether to encode file contents to Base64 or emit it as a separate file into the output directory.

If Rule.type is an asset or asset/inline then Rule.generator option may be an object that describes the encoding of the module source or a function that encodes module's source by a custom algorithm.

See Asset Modules guide for additional information and use cases.

Rule.parser.dataUrlCondition

object = { maxSize number = 8096 } function (source, { filename, module }) => boolean

If a module source size is less than maxSize then module will be injected into the bundle as a Base64-encoded string, otherwise module file will be emitted into the output directory.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        parser: {
          dataUrlCondition: {
            maxSize: 4 * 1024,
          },
        },
      },
    ],
  },
};

When a function is given, returning true tells webpack to inject the module into the bundle as Base64-encoded string, otherwise module file will be emitted into the output directory.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        parser: {
          dataUrlCondition: (source, { filename, module }) => {
            const content = source.toString();
            return content.includes('some marker');
          },
        },
      },
    ],
  },
};

Rule.generator

Rule.generator.dataUrl

object = { encoding string = 'base64' | false, mimetype string = undefined | false } function (content, { filename, module }) => string

When Rule.generator.dataUrl is used as an object, you can configure two properties:

• encoding: When set to 'base64', module source will be encoded using Base64 algorithm. Setting encoding to false will disable encoding.
• mimetype: A mimetype for data URI. Resolves from module resource extension by default.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        generator: {
          dataUrl: {
            encoding: 'base64',
            mimetype: 'mimetype/png',
          },
        },
      },
    ],
  },
};

When used a a function, it executes for every module and must return a data URI string.

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        generator: {
          dataUrl: (content) => {
            const svgToMiniDataURI = require('mini-svg-data-uri');
            if (typeof content !== 'string') {
              content = content.toString();
            }
            return svgToMiniDataURI(content);
          },
        },
      },
    ],
  },
};

Rule.generator.emit

Opt out of writing assets from Asset Modules, you might want to use it in Server side rendering cases.

• Type: boolean = true

• Available: 5.25.0+

• Example:

  module.exports = {
    // …
    module: {
      rules: [
        {
          test: /\.png$/i,
          type: 'asset/resource',
          generator: {
            emit: false,
          },
        },
      ],
    },
  };

Rule.generator.filename

The same as output.assetModuleFilename but for specific rule. Overrides output.assetModuleFilename and works only with asset and asset/resource module types.

webpack.config.js

module.exports = {
  //...
  output: {
    assetModuleFilename: 'images/[hash][ext][query]',
  },
  module: {
    rules: [
      {
        test: /\.png/,
        type: 'asset/resource',
      },
      {
        test: /\.html/,
        type: 'asset/resource',
        generator: {
          filename: 'static/[hash][ext]',
        },
      },
    ],
  },
};

Rule.generator.publicPath

Customize publicPath for specific Asset Modules.

• Type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
• Available: 5.28.0+

module.exports = {
  //...
  output: {
    publicPath: 'static/',
  },
  module: {
    rules: [
      {
        test: /\.png$/i,
        type: 'asset/resource',
        generator: {
          publicPath: 'assets/',
        },
      },
    ],
  },
};

Rule.generator.outputPath

Emit the asset in the specified folder relative to 'output.path'. This should only be needed when custom 'publicPath' is specified to match the folder structure there.

• Type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
• Available: 5.67.0+

module.exports = {
  //...
  output: {
    publicPath: 'static/',
  },
  module: {
    rules: [
      {
        test: /\.png$/i,
        type: 'asset/resource',
        generator: {
          publicPath: 'https://cdn/assets/',
          outputPath: 'cdn-assets/',
        },
      },
    ],
  },
};

Rule.resource

A Condition matched with the resource. See details in Rule conditions.

Rule.resourceQuery

A Condition matched with the resource query. This option is used to test against the query section of a request string (i.e. from the question mark onwards). If you were to import Foo from './foo.css?inline', the following condition would match:

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.css$/,
        resourceQuery: /inline/,
        type: 'asset/inline',
      },
    ],
  },
};

Rule.parser.parse

function(input) => string | object

If Rule.type is set to 'json' then Rules.parser.parse option may be a function that implements custom logic to parse module's source and convert it to a JavaScript object. It may be useful to import toml, yaml and other non-JSON files as JSON, without specific loaders:

webpack.config.js

const toml = require('toml');

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.toml/,
        type: 'json',
        parser: {
          parse: toml.parse,
        },
      },
    ],
  },
};

Rule.rules

An array of Rules that is also used when the Rule matches.

Rule.scheme

Match the used schema, e.g., data, http.

• Type: string | RegExp | ((value: string) => boolean) | RuleSetLogicalConditions | RuleSetCondition[]
• Available: 5.38.0+

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        scheme: 'data',
        type: 'asset/resource',
      },
    ],
  },
};

Rule.sideEffects

bool

Indicate what parts of the module contain side effects. See Tree Shaking for details.

Rule.test

Include all modules that pass test assertion. If you supply a Rule.test option, you cannot also supply a Rule.resource. See Rule.resource and Condition for details.

Rule.type

string

Possible values: 'javascript/auto' | 'javascript/dynamic' | 'javascript/esm' | 'json' | 'webassembly/sync' | 'webassembly/async' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' | 'css/auto'

Rule.type sets the type for a matching module. This prevents defaultRules and their default importing behaviors from occurring. For example, if you want to load a .json file through a custom loader, you'd need to set the type to javascript/auto to bypass webpack's built-in json importing.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      //...
      {
        test: /\.json$/,
        type: 'javascript/auto',
        loader: 'custom-json-loader',
      },
    ],
  },
};

See Asset Modules guide for more about asset* type.

css/auto

5.87.0+

See use case of css/auto module type here. Make sure to enable experiments.css to use css/auto.

module.exports = {
  target: 'web',
  mode: 'development',
  experiments: {
    css: true,
  },
  module: {
    rules: [
      {
        test: /\.less$/,
        use: 'less-loader',
        type: 'css/auto',
      },
    ],
  },
};

Rule.use

[UseEntry] function(info)

Starting with webpack 5.87.0 falsy values such as undefined null can be used to conditionally disable specific use entry.

[UseEntry]

Rule.use can be an array of UseEntry which are applied to modules. Each entry specifies a loader to be used.

Passing a string (i.e. use: [ 'style-loader' ]) is a shortcut to the loader property (i.e. use: [ { loader: 'style-loader '} ]).

Loaders can be chained by passing multiple loaders, which will be applied from right to left (last to first configured).

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        //...
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              importLoaders: 1,
            },
          },
          {
            loader: 'less-loader',
            options: {
              noIeCompat: true,
            },
          },
        ],
      },
    ],
  },
};

function(info)

Rule.use can also be a function which receives the object argument describing the module being loaded, and must return an array of UseEntry items.

The info object parameter has the following fields:

• compiler: The current webpack compiler (can be undefined)
• issuer: The path to the module that is importing the module being loaded
• realResource: Always the path to the module being loaded
• resource: The path to the module being loaded, it is usually equal to realResource except when the resource name is overwritten via !=! in request string

The same shortcut as an array can be used for the return value (i.e. use: [ 'style-loader' ]).

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        use: (info) => [
          {
            loader: 'custom-svg-loader',
          },
          {
            loader: 'svgo-loader',
            options: {
              plugins: [
                {
                  cleanupIDs: {
                    prefix: basename(info.resource),
                  },
                },
              ],
            },
          },
        ],
      },
    ],
  },
};

See UseEntry for details.

Rule.resolve

Resolving can be configured on module level. See all available options on resolve configuration page. All applied resolve options get deeply merged with higher level resolve.

For example, let's imagine we have an entry in ./src/index.js, ./src/footer/default.js and a ./src/footer/overridden.js to demonstrate the module level resolve.

./src/index.js

import footer from 'footer';
console.log(footer);

./src/footer/default.js

export default 'default footer';

./src/footer/overridden.js

export default 'overridden footer';

webpack.js.org

module.exports = {
  resolve: {
    alias: {
      footer: './footer/default.js',
    },
  },
};

When creating a bundle with this configuration, console.log(footer) will output 'default footer'. Let's set Rule.resolve for .js files, and alias footer to overridden.js.

webpack.js.org

module.exports = {
  resolve: {
    alias: {
      footer: './footer/default.js',
    },
  },
  module: {
    rules: [
      {
        resolve: {
          alias: {
            footer: './footer/overridden.js',
          },
        },
      },
    ],
  },
};

When creating a bundle with updated configuration, console.log(footer) will output 'overridden footer'.

resolve.fullySpecified

boolean = true

When enabled, you should provide the file extension when importing a module in .mjs files or any other .js files when their nearest parent package.json file contains a "type" field with a value of "module", otherwise webpack would fail the compiling with a Module not found error. And webpack won't resolve directories with filenames defined in the resolve.mainFiles, you have to specify the filename yourself.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.m?js$/,
        resolve: {
          fullySpecified: false, // disable the behaviour
        },
      },
    ],
  },
};

Rule.with

v5.92.0+

A Condition that allows you to match the imports based on specific conditions provided with the with keyword, enabling different rules to be applied based on the content type.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        // Handles imports with the condition "with { type: 'json' }"
        with: { type: 'json' },
        loader: require.resolve('./loader-assert.js'),
      },
    ],
  },
};

index.js

import one from './pkg-1.json' with { type: 'json' };

In this example, Rule.with is used to apply loader-assert.js to any module imported with the condition with { type: "json" }.

Condition

Conditions can be one of these:

• A string: To match the input must start with the provided string. I. e. an absolute directory path, or absolute path to the file.
• A RegExp: It's tested with the input.
• A function: It's called with the input and must return a truthy value to match.
• An array of Conditions: At least one of the Conditions must match.
• An object: All properties must match. Each property has a defined behavior.

{ and: [Condition] }: All Conditions must match.

{ or: [Condition] }: Any Condition must match.

{ not: [Condition] }: All Conditions must NOT match.

Example:

const path = require('path');

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.css$/,
        include: [
          // will include any paths relative to the current directory starting with `app/styles`
          // e.g. `app/styles.css`, `app/styles/styles.css`, `app/stylesheet.css`
          path.resolve(__dirname, 'app/styles'),
          // add an extra slash to only include the content of the directory `vendor/styles/`
          path.join(__dirname, 'vendor/styles/'),
        ],
      },
    ],
  },
};

UseEntry

object function(info)

object

It must have a loader property being a string. It is resolved relative to the configuration context with the loader resolving options (resolveLoader).

It can have an options property being a string or object. This value is passed to the loader, which should interpret it as loader options.

For compatibility a query property is also possible, which is an alias for the options property. Use the options property instead.

Note that webpack needs to generate a unique module identifier from the resource and all loaders including options. It tries to do this with a JSON.stringify of the options object. This is fine in 99.9% of cases, but may be not unique if you apply the same loaders with different options to the resource and the options have same stringified values.

It also breaks if the options object cannot be stringified (i.e. circular JSON). Because of this you can have a ident property in the options object which is used as unique identifier.

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        loader: 'css-loader',
        options: {
          modules: true,
        },
      },
    ],
  },
};

function(info)

A UseEntry can also be a function which receives the object argument describing the module being loaded, and must return a non-function UseEntry object. This can be used to vary the loader options on a per-module basis.

The info object parameter has the following fields:

• compiler: The current webpack compiler (can be undefined)
• issuer: The path to the module that is importing the module being loaded
• realResource: Always the path to the module being loaded
• resource: The path to the module being loaded, it is usually equal to realResource except when the resource name is overwritten via !=! in request string

webpack.config.js

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.svg$/,
        type: 'asset',
        use: (info) => ({
          loader: 'svgo-loader',
          options: {
            plugins: [
              {
                cleanupIDs: { prefix: basename(info.resource) },
              },
            ],
          },
        }),
      },
    ],
  },
};

Module Contexts

These options describe the default settings for the context created when a dynamic dependency is encountered.

Example for an unknown dynamic dependency: require.

Example for an expr dynamic dependency: require(expr).

Example for an wrapped dynamic dependency: require('./templates/' + expr).

Here are the available options with their defaults:

webpack.config.js

module.exports = {
  //...
  module: {
    exprContextCritical: true,
    exprContextRecursive: true,
    exprContextRegExp: false,
    exprContextRequest: '.',
    unknownContextCritical: true,
    unknownContextRecursive: true,
    unknownContextRegExp: false,
    unknownContextRequest: '.',
    wrappedContextCritical: false,
    wrappedContextRecursive: true,
    wrappedContextRegExp: /.*/,
    strictExportPresence: false,
  },
};

A few use cases:

• Warn for dynamic dependencies: wrappedContextCritical: true.
• require(expr) should include the whole directory: exprContextRegExp: /^\.\//
• require('./templates/' + expr) should not include subdirectories by default: wrappedContextRecursive: false
• strictExportPresence makes missing exports an error instead of warning
• Set the inner regular expression for partial dynamic dependencies : wrappedContextRegExp: /\\.\\*/

Resolve

These options change how modules are resolved. Webpack provides reasonable defaults, but it is possible to change the resolving in detail. Have a look at Module Resolution for more explanation of how the resolver works.

resolve

object

Configure how modules are resolved. For example, when calling import 'lodash' in ES2015, the resolve options can change where webpack goes to look for 'lodash' (see modules).

webpack.config.js

module.exports = {
  //...
  resolve: {
    // configuration options
  },
};

resolve.alias

object

Create aliases to import or require certain modules more easily. For example, to alias a bunch of commonly used src/ folders:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  resolve: {
    alias: {
      Utilities: path.resolve(__dirname, 'src/utilities/'),
      Templates: path.resolve(__dirname, 'src/templates/'),
    },
  },
};

Now, instead of using relative paths when importing like so:

import Utility from '../../utilities/utility';

you can use the alias:

import Utility from 'Utilities/utility';

A trailing $ can also be added to the given object's keys to signify an exact match:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  resolve: {
    alias: {
      xyz$: path.resolve(__dirname, 'path/to/file.js'),
    },
  },
};

which would yield these results:

import Test1 from 'xyz'; // Exact match, so path/to/file.js is resolved and imported
import Test2 from 'xyz/file.js'; // Not an exact match, normal resolution takes place

The following table explains other cases:

alias:	import 'xyz'	import 'xyz/file.js'
{}	/abc/node_modules/xyz/index.js	/abc/node_modules/xyz/file.js
{ xyz: '/abc/path/to/file.js' }	/abc/path/to/file.js	error
{ xyz$: '/abc/path/to/file.js' }	/abc/path/to/file.js	/abc/node_modules/xyz/file.js
{ xyz: './dir/file.js' }	/abc/dir/file.js	error
{ xyz$: './dir/file.js' }	/abc/dir/file.js	/abc/node_modules/xyz/file.js
{ xyz: '/some/dir' }	/some/dir/index.js	/some/dir/file.js
{ xyz$: '/some/dir' }	/some/dir/index.js	/abc/node_modules/xyz/file.js
{ xyz: './dir' }	/abc/dir/index.js	/abc/dir/file.js
{ xyz: 'modu' }	/abc/node_modules/modu/index.js	/abc/node_modules/modu/file.js
{ xyz$: 'modu' }	/abc/node_modules/modu/index.js	/abc/node_modules/xyz/file.js
{ xyz: 'modu/some/file.js' }	/abc/node_modules/modu/some/file.js	error
{ xyz: 'modu/dir' }	/abc/node_modules/modu/dir/index.js	/abc/node_modules/modu/dir/file.js
{ xyz$: 'modu/dir' }	/abc/node_modules/modu/dir/index.js	/abc/node_modules/xyz/file.js

index.js may resolve to another file if defined in the package.json.

/abc/node_modules may resolve in /node_modules too.

module.exports = {
  //...
  resolve: {
    alias: {
      _: [
        path.resolve(__dirname, 'src/utilities/'),
        path.resolve(__dirname, 'src/templates/'),
      ],
    },
  },
};

Setting resolve.alias to false will tell webpack to ignore a module.

module.exports = {
  //...
  resolve: {
    alias: {
      'ignored-module': false,
      './ignored-module': false,
    },
  },
};

resolve.aliasFields

[string]: ['browser']

Specify a field, such as browser, to be parsed according to this specification.

webpack.config.js

module.exports = {
  //...
  resolve: {
    aliasFields: ['browser'],
  },
};

resolve.byDependency

Configure resolve options by the type of module request.

• Type: [type: string]: ResolveOptions

• Example:

  module.exports = {
    // ...
    resolve: {
      byDependency: {
        // ...
        esm: {
          mainFields: ['browser', 'module'],
        },
        commonjs: {
          aliasFields: ['browser'],
        },
        url: {
          preferRelative: true,
        },
      },
    },
  };

resolve.cache

boolean

Enables caching of successfully resolved requests, allowing cache entries to be revalidated.

webpack.config.js

module.exports = {
  //...
  resolve: {
    cache: true,
  },
};

resolve.cachePredicate

function(module) => boolean

A function which decides whether a request should be cached or not. An object is passed to the function with path and request properties. It must return a boolean.

webpack.config.js

module.exports = {
  //...
  resolve: {
    cachePredicate: (module) => {
      // additional logic
      return true;
    },
  },
};

resolve.cacheWithContext

boolean

If unsafe cache is enabled, includes request.context in the cache key. This option is taken into account by the enhanced-resolve module. context in resolve caching is ignored when resolve or resolveLoader plugins are provided. This addresses a performance regression.

resolve.conditionNames

string[]

Condition names for exports field which defines entry points of a package.

webpack.config.js

module.exports = {
  //...
  resolve: {
    conditionNames: ['require', 'node'],
  },
};

Webpack will match export conditions that are listed within the resolve.conditionNames array.

The key order in the exports field is significant. During condition matching, earlier entries have higher priority and take precedence over later entries.

For example,

package.json

{
  "name": "foo",
  "exports": {
    ".": {
      "import": "./index-import.js",
      "require": "./index-require.js",
      "node": "./index-node.js"
    },
    "./bar": {
      "node": "./bar-node.js",
      "require": "./bar-require.js"
    },
    "./baz": {
      "import": "./baz-import.js",
      "node": "./baz-node.js"
    }
  }
}

webpack.config.js

module.exports = {
  //...
  resolve: {
    conditionNames: ['require', 'node'],
  },
};

importing

• 'foo' will resolve to 'foo/index-require.js'
• 'foo/bar' will resolve to 'foo/bar-node.js' as the "node" key comes before "require" key in the conditional exports object.
• 'foo/baz' will resolve to 'foo/baz-node.js'

resolve.descriptionFiles

[string] = ['package.json']

The JSON files to use for descriptions.

webpack.config.js

module.exports = {
  //...
  resolve: {
    descriptionFiles: ['package.json'],
  },
};

resolve.enforceExtension

boolean = false

If true, it will not allow extension-less files. So by default require('./foo') works if ./foo has a .js extension, but with this enabled only require('./foo.js') will work.

webpack.config.js

module.exports = {
  //...
  resolve: {
    enforceExtension: false,
  },
};

resolve.exportsFields

[string] = ['exports']

Fields in package.json that are used for resolving module requests. See package-exports guideline for more information.

webpack.config.js

module.exports = {
  //...
  resolve: {
    exportsFields: ['exports', 'myCompanyExports'],
  },
};

resolve.extensionAlias

object

An object which maps extension to extension aliases.

webpack.config.js

module.exports = {
  //...
  resolve: {
    extensionAlias: {
      '.js': ['.ts', '.js'],
      '.mjs': ['.mts', '.mjs'],
    },
  },
};

resolve.extensions

[string] = ['.js', '.json', '.wasm']

Attempt to resolve these extensions in order. If multiple files share the same name but have different extensions, webpack will resolve the one with the extension listed first in the array and skip the rest.

webpack.config.js

module.exports = {
  //...
  resolve: {
    extensions: ['.js', '.json', '.wasm'],
  },
};

which is what enables users to leave off the extension when importing:

import File from '../path/to/file';

Note that using resolve.extensions like above will override the default array, meaning that webpack will no longer try to resolve modules using the default extensions. However you can use '...' to access the default extensions:

module.exports = {
  //...
  resolve: {
    extensions: ['.ts', '...'],
  },
};

resolve.fallback

object

Redirect module requests when normal resolving fails.

webpack.config.js

module.exports = {
  //...
  resolve: {
    fallback: {
      abc: false, // do not include a polyfill for abc
      xyz: path.resolve(__dirname, 'path/to/file.js'), // include a polyfill for xyz
    },
  },
};

Webpack 5 no longer polyfills Node.js core modules automatically which means if you use them in your code running in browsers or alike, you will have to install compatible modules from npm and include them yourself. Here is a list of polyfills webpack has used before webpack 5:

module.exports = {
  //...
  resolve: {
    fallback: {
      assert: require.resolve('assert'),
      buffer: require.resolve('buffer'),
      console: require.resolve('console-browserify'),
      constants: require.resolve('constants-browserify'),
      crypto: require.resolve('crypto-browserify'),
      domain: require.resolve('domain-browser'),
      events: require.resolve('events'),
      http: require.resolve('stream-http'),
      https: require.resolve('https-browserify'),
      os: require.resolve('os-browserify/browser'),
      path: require.resolve('path-browserify'),
      punycode: require.resolve('punycode'),
      process: require.resolve('process/browser'),
      querystring: require.resolve('querystring-es3'),
      stream: require.resolve('stream-browserify'),
      string_decoder: require.resolve('string_decoder'),
      sys: require.resolve('util'),
      timers: require.resolve('timers-browserify'),
      tty: require.resolve('tty-browserify'),
      url: require.resolve('url'),
      util: require.resolve('util'),
      vm: require.resolve('vm-browserify'),
      zlib: require.resolve('browserify-zlib'),
    },
  },
};

resolve.fullySpecified

boolean

When set to true, this option treats user-specified requests as fully specified. This means that no extensions are automatically added, and the mainFiles within directories are not resolved. It's important to note that this behavior does not affect requests made through mainFields, aliasFields, or aliases.

webpack.config.js

module.exports = {
  //...
  resolve: {
    fullySpecified: true,
  },
};

resolve.importsFields

[string]

Fields from package.json which are used to provide the internal requests of a package (requests starting with # are considered internal).

webpack.config.js

module.exports = {
  //...
  resolve: {
    importsFields: ['browser', 'module', 'main'],
  },
};

resolve.mainFields

[string]

When importing from an npm package, e.g. import * as D3 from 'd3', this option will determine which fields in its package.json are checked. The default values will vary based upon the target specified in your webpack configuration.

When the target property is set to webworker, web, or left unspecified:

webpack.config.js

module.exports = {
  //...
  resolve: {
    mainFields: ['browser', 'module', 'main'],
  },
};

For any other target (including node):

webpack.config.js

module.exports = {
  //...
  resolve: {
    mainFields: ['module', 'main'],
  },
};

For example, consider an arbitrary library called upstream with a package.json that contains the following fields:

{
  "browser": "build/upstream.js",
  "module": "index"
}

When we import * as Upstream from 'upstream' this will actually resolve to the file in the browser property. The browser property takes precedence because it's the first item in mainFields. Meanwhile, a Node.js application bundled by webpack will first try to resolve using the file in the module field.

resolve.mainFiles

[string] = ['index']

The filename to be used while resolving directories.

webpack.config.js

module.exports = {
  //...
  resolve: {
    mainFiles: ['index'],
  },
};

resolve.modules

[string] = ['node_modules']

Tell webpack what directories should be searched when resolving modules.

Absolute and relative paths can both be used, but be aware that they will behave a bit differently.

A relative path will be scanned similarly to how Node scans for node_modules, by looking through the current directory as well as its ancestors (i.e. ./node_modules, ../node_modules, and on).

With an absolute path, it will only search in the given directory.

webpack.config.js

module.exports = {
  //...
  resolve: {
    modules: ['node_modules'],
  },
};

If you want to add a directory to search in that takes precedence over node_modules/:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  resolve: {
    modules: [path.resolve(__dirname, 'src'), 'node_modules'],
  },
};

resolve.plugins

[Plugin]

A list of additional resolve plugins which should be applied. It allows plugins such as DirectoryNamedWebpackPlugin.

webpack.config.js

module.exports = {
  //...
  resolve: {
    plugins: [new DirectoryNamedWebpackPlugin()],
  },
};

resolve.preferAbsolute

boolean

5.13.0+

Prefer absolute paths to resolve.roots when resolving.

webpack.config.js

module.exports = {
  //...
  resolve: {
    preferAbsolute: true,
  },
};

resolve.preferRelative

boolean

When enabled, webpack would prefer to resolve module requests as relative requests instead of using modules from node_modules directories.

webpack.config.js

module.exports = {
  //...
  resolve: {
    preferRelative: true,
  },
};

src/index.js

// let's say `src/logo.svg` exists
import logo1 from 'logo.svg'; // this is viable when `preferRelative` enabled
import logo2 from './logo.svg'; // otherwise you can only use relative path to resolve logo.svg

// `preferRelative` is enabled by default for `new URL()` case
const b = new URL('module/path', import.meta.url);
const a = new URL('./module/path', import.meta.url);

resolve.restrictions

[string, RegExp]

A list of resolve restrictions to restrict the paths that a request can be resolved on.

webpack.config.js

module.exports = {
  //...
  resolve: {
    restrictions: [/\.(sass|scss|css)$/],
  },
};

resolve.roots

[string]

A list of directories where requests of server-relative URLs (starting with '/') are resolved, defaults to context configuration option. On non-Windows systems these requests are resolved as an absolute path first.

webpack.config.js

const fixtures = path.resolve(__dirname, 'fixtures');
module.exports = {
  //...
  resolve: {
    roots: [__dirname, fixtures],
  },
};

resolve.symlinks

boolean = true

Whether to resolve symlinks to their symlinked location.

When enabled, symlinked resources are resolved to their real path, not their symlinked location. Note that this may cause module resolution to fail when using tools that symlink packages (like npm link).

webpack.config.js

module.exports = {
  //...
  resolve: {
    symlinks: true,
  },
};

resolve.unsafeCache

object boolean = true

Enable aggressive, but unsafe, caching of modules. Passing true will cache everything.

webpack.config.js

module.exports = {
  //...
  resolve: {
    unsafeCache: true,
  },
};

When an object is provided, webpack will use it as cache.

For example, you can supply a Proxy object instead of a regular one:

webpack.config.js

// copied from discussion here https://github.com/webpack/webpack/discussions/18089
const realUnsafeCache = {};
const unsafeCacheHandler = {
  get(cache, key) {
    const cachedValue = cache[key];

    // make sure the file exists on disk
    if (cachedValue && !fs.existsSync(cachedValue.path)) {
      // and if it doesn't, evict that cache entry.
      delete cache[key];
      return undefined;
    }

    return cachedValue;
  },
};
const theProxiedCache = new Proxy(realUnsafeCache, unsafeCacheHandler);
module.exports = {
  //...
  resolve: {
    unsafeCache: theProxiedCache,
  },
};

resolve.useSyncFileSystemCalls

boolean

Use synchronous filesystem calls for the resolver.

webpack.config.js

module.exports = {
  //...
  resolve: {
    useSyncFileSystemCalls: true,
  },
};

resolveLoader

object { modules [string] = ['node_modules'], extensions [string] = ['.js', '.json'], mainFields [string] = ['loader', 'main']}

This set of options is identical to the resolve property set above, but is used only to resolve webpack's loader packages.

webpack.config.js

module.exports = {
  //...
  resolveLoader: {
    modules: ['node_modules'],
    extensions: ['.js', '.json'],
    mainFields: ['loader', 'main'],
  },
};

Optimization

Webpack runs optimizations for you depending on the chosen mode, still all optimizations are available for manual configuration and overrides.

optimization.checkWasmTypes

boolean

Tells webpack to check the incompatible types of WebAssembly modules when they are imported/exported. By default optimization.checkWasmTypes is enabled in production mode and disabled elsewise.

webpack.config.js

module.exports = {
  //...
  optimization: {
    checkWasmTypes: false,
  },
};

optimization.chunkIds

boolean = false string: 'natural' | 'named' | 'size' | 'total-size' | 'deterministic'

Tells webpack which algorithm to use when choosing chunk ids. Setting optimization.chunkIds to false tells webpack that none of built-in algorithms should be used, as custom one can be provided via plugin. There are a couple of defaults for optimization.chunkIds:

• Also if the environment is development then optimization.chunkIds is set to 'named', while in production it is set to 'deterministic'
• if none of the above, optimization.chunkIds will be defaulted to 'natural'

The following string values are supported:

Option	Description
'natural'	Numeric ids in order of usage.
'named'	Readable ids for better debugging.
'deterministic'	Short numeric ids which will not be changing between compilation. Good for long term caching. Enabled by default for production mode.
'size'	Numeric ids focused on minimal initial download size.
'total-size'	numeric ids focused on minimal total download size.

webpack.config.js

module.exports = {
  //...
  optimization: {
    chunkIds: 'named',
  },
};

By default, a minimum length of 3 digits is used when optimization.chunkIds is set to 'deterministic'. To override the default behaviour, set optimization.chunkIds to false and use the webpack.ids.DeterministicChunkIdsPlugin.

webpack.config.js

module.exports = {
  //...
  optimization: {
    chunkIds: false,
  },
  plugins: [
    new webpack.ids.DeterministicChunkIdsPlugin({
      maxLength: 5,
    }),
  ],
};

optimization.concatenateModules

boolean

Tells webpack to find segments of the module graph which can be safely concatenated into a single module. Depends on optimization.providedExports and optimization.usedExports. By default optimization.concatenateModules is enabled in production mode and disabled elsewise.

webpack.config.js

module.exports = {
  //...
  optimization: {
    concatenateModules: true,
  },
};

optimization.emitOnErrors

boolean = false

Use the optimization.emitOnErrors to emit assets whenever there are errors while compiling. This ensures that erroring assets are emitted. Critical errors are emitted into the generated code and will cause errors at runtime.

webpack.config.js

module.exports = {
  //...
  optimization: {
    emitOnErrors: true,
  },
};

optimization.avoidEntryIife

boolean = false

5.95.0+

Use optimization.avoidEntryIife to avoid wrapping the entry module in an IIFE when it is required (search for "This entry needs to be wrapped in an IIFE because" in JavascriptModulesPlugin). This approach helps optimize performance for JavaScript engines and enables tree shaking when building ESM libraries.

Currently, optimization.avoidEntryIife can only optimize a single entry module along with other modules.

By default, optimization.avoidEntryIife is enabled in production mode and disabled otherwise.

webpack.config.js

module.exports = {
  //...
  optimization: {
    avoidEntryIife: true,
  },
};

optimization.flagIncludedChunks

boolean

Tells webpack to determine and flag chunks which are subsets of other chunks in a way that subsets don’t have to be loaded when the bigger chunk has been already loaded. By default optimization.flagIncludedChunks is enabled in production mode and disabled elsewise.

webpack.config.js

module.exports = {
  //...
  optimization: {
    flagIncludedChunks: true,
  },
};

optimization.innerGraph

boolean = true

optimization.innerGraph tells webpack whether to conduct inner graph analysis for unused exports.

webpack.config.js

module.exports = {
  //...
  optimization: {
    innerGraph: false,
  },
};

optimization.mangleExports

boolean string: 'deterministic' | 'size'

optimization.mangleExports allows to control export mangling.

By default optimization.mangleExports: 'deterministic' is enabled in production mode and disabled elsewise.

The following values are supported:

Option	Description
'size'	Short names - usually a single char - focused on minimal download size.
'deterministic'	Short names - usually two chars - which will not change when adding or removing exports. Good for long term caching.
true	Same as 'deterministic'
false	Keep original name. Good for readability and debugging.

webpack.config.js

module.exports = {
  //...
  optimization: {
    mangleExports: true,
  },
};

optimization.mangleWasmImports

boolean = false

When set to true tells webpack to reduce the size of WASM by changing imports to shorter strings. It mangles module and export names.

webpack.config.js

module.exports = {
  //...
  optimization: {
    mangleWasmImports: true,
  },
};

optimization.mergeDuplicateChunks

boolean = true

Tells webpack to merge chunks which contain the same modules. Setting optimization.mergeDuplicateChunks to false will disable this optimization.

webpack.config.js

module.exports = {
  //...
  optimization: {
    mergeDuplicateChunks: false,
  },
};

optimization.minimize

boolean = true

Tell webpack to minimize the bundle using the TerserPlugin or the plugin(s) specified in optimization.minimizer.

webpack.config.js

module.exports = {
  //...
  optimization: {
    minimize: false,
  },
};

optimization.minimizer

[TerserPlugin] and or [function (compiler)] or undefined | null | 0 | false | ""

Allows you to override the default minimizer by providing a different one or more customized TerserPlugin instances. Starting with webpack 5.87.0 falsy values can be used to conditionally disable specific minimizers.

webpack.config.js

const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new TerserPlugin({
        parallel: true,
        terserOptions: {
          // https://github.com/webpack-contrib/terser-webpack-plugin#terseroptions
        },
      }),
    ],
  },
};

Or, as function:

module.exports = {
  optimization: {
    minimizer: [
      (compiler) => {
        const TerserPlugin = require('terser-webpack-plugin');
        new TerserPlugin({
          /* your config */
        }).apply(compiler);
      },
    ],
  },
};

By default, webpack would set optimization.minimizer to the following value:

[
  {
    apply: (compiler) => {
      // Lazy load the Terser plugin
      const TerserPlugin = require('terser-webpack-plugin');
      new TerserPlugin({
        terserOptions: {
          compress: {
            passes: 2,
          },
        },
      }).apply(compiler);
    },
  },
]; // eslint-disable-line

Which can be accessed with '...' in case you want to keep it when customizing optimization.minimizer:

module.exports = {
  optimization: {
    minimizer: [new CssMinimizer(), '...'],
  },
};

Basically, '...' is a shortcut to access the default configuration value webpack would otherwise set for us.

optimization.moduleIds

boolean: false string: 'natural' | 'named' | 'deterministic' | 'size'

Tells webpack which algorithm to use when choosing module ids. Setting optimization.moduleIds to false tells webpack that none of built-in algorithms should be used, as custom one can be provided via plugin.

The following string values are supported:

Option	Description
natural	Numeric ids in order of usage.
named	Readable ids for better debugging.
deterministic	Module names are hashed into small numeric values.
size	Numeric ids focused on minimal initial download size.

webpack.config.js

module.exports = {
  //...
  optimization: {
    moduleIds: 'deterministic',
  },
};

deterministic option is useful for long term caching, but still results in smaller bundles compared to hashed. Length of the numeric value is chosen to fill a maximum of 80% of the id space. By default a minimum length of 3 digits is used when optimization.moduleIds is set to deterministic. To override the default behaviour set optimization.moduleIds to false and use the webpack.ids.DeterministicModuleIdsPlugin.

webpack.config.js

module.exports = {
  //...
  optimization: {
    moduleIds: false,
  },
  plugins: [
    new webpack.ids.DeterministicModuleIdsPlugin({
      maxLength: 5,
    }),
  ],
};

optimization.nodeEnv

boolean = false string

Tells webpack to set process.env.NODE_ENV to a given string value. optimization.nodeEnv uses DefinePlugin unless set to false. optimization.nodeEnv defaults to mode if set, else falls back to 'production'.

Possible values:

• any string: the value to set process.env.NODE_ENV to.
• false: do not modify/set the value of process.env.NODE_ENV.

webpack.config.js

module.exports = {
  //...
  optimization: {
    nodeEnv: 'production',
  },
};

optimization.portableRecords

boolean

optimization.portableRecords tells webpack to generate records with relative paths to be able to move the context folder.

By default optimization.portableRecords is disabled. Automatically enabled if at least one of the records options provided to webpack config: recordsPath, recordsInputPath, recordsOutputPath.

webpack.config.js

module.exports = {
  //...
  optimization: {
    portableRecords: true,
  },
};

optimization.providedExports

boolean

Tells webpack to figure out which exports are provided by modules to generate more efficient code for export * from .... By default optimization.providedExports is enabled.

webpack.config.js

module.exports = {
  //...
  optimization: {
    providedExports: false,
  },
};

optimization.realContentHash

boolean

Adds an additional hash compilation pass after the assets have been processed to get the correct asset content hashes. If realContentHash is set to false, internal data is used to calculate the hash and it can change when assets are identical. By default optimization.realContentHash is enabled in production mode and disabled otherwise.

webpack.config.js

module.exports = {
  //...
  optimization: {
    realContentHash: false,
  },
};

optimization.removeAvailableModules

boolean = false

Tells webpack to detect and remove modules from chunks when these modules are already included in all parents. Setting optimization.removeAvailableModules to true will enable this optimization.

webpack.config.js

module.exports = {
  //...
  optimization: {
    removeAvailableModules: true,
  },
};

optimization.removeEmptyChunks

boolean = true

Tells webpack to detect and remove chunks which are empty. Setting optimization.removeEmptyChunks to false will disable this optimization.

webpack.config.js

module.exports = {
  //...
  optimization: {
    removeEmptyChunks: false,
  },
};

optimization.runtimeChunk

object string boolean

Setting optimization.runtimeChunk to true or 'multiple' adds an additional chunk containing only the runtime to each entrypoint. This setting is an alias for:

webpack.config.js

module.exports = {
  //...
  optimization: {
    runtimeChunk: {
      name: (entrypoint) => `runtime~${entrypoint.name}`,
    },
  },
};

The value 'single' instead creates a runtime file to be shared for all generated chunks. This setting is an alias for:

webpack.config.js

module.exports = {
  //...
  optimization: {
    runtimeChunk: {
      name: 'runtime',
    },
  },
};

By setting optimization.runtimeChunk to object it is only possible to provide the name property which stands for the name or name factory for the runtime chunks.

Default is false: each entry chunk embeds runtime.

webpack.config.js

module.exports = {
  //...
  optimization: {
    runtimeChunk: {
      name: (entrypoint) => `runtimechunk~${entrypoint.name}`,
    },
  },
};

optimization.sideEffects

boolean = true string: 'flag'

Tells webpack to recognise the sideEffects flag in package.json or rules to skip over modules which are flagged to contain no side effects when exports are not used.

package.json

{
  "name": "awesome npm module",
  "version": "1.0.0",
  "sideEffects": false
}

optimization.sideEffects depends on optimization.providedExports to be enabled. This dependency has a build time cost, but eliminating modules has positive impact on performance because of less code generation. Effect of this optimization depends on your codebase, try it for possible performance wins.

webpack.config.js

module.exports = {
  //...
  optimization: {
    sideEffects: true,
  },
};

To only use the manual flag and do not analyse source code:

module.exports = {
  //...
  optimization: {
    sideEffects: 'flag',
  },
};

The 'flag' value is used by default in non-production builds.

optimization.splitChunks

object

By default webpack v4+ provides new common chunks strategies out of the box for dynamically imported modules. See available options for configuring this behavior in the SplitChunksPlugin page.

optimization.usedExports

boolean = true string: 'global'

Tells webpack to determine used exports for each module. This depends on optimization.providedExports. Information collected by optimization.usedExports is used by other optimizations or code generation i.e. exports are not generated for unused exports, export names are mangled to single char identifiers when all usages are compatible. Dead code elimination in minimizers will benefit from this and can remove unused exports.

webpack.config.js

module.exports = {
  //...
  optimization: {
    usedExports: false,
  },
};

To opt-out from used exports analysis per runtime:

module.exports = {
  //...
  optimization: {
    usedExports: 'global',
  },
};

Plugins

The plugins option is used to customize the webpack build process in a variety of ways. Webpack comes with a variety built-in plugins available under webpack.[plugin-name]. See Plugins page for a list of plugins and documentation but note that there are a lot more out in the community.

plugins

[Plugin]

An array of webpack plugins. For example, DefinePlugin allows you to create global constants which can be configured at compile time. This can be useful for allowing different behavior between development builds and release builds. Starting with webpack 5.87.0 falsy values can be used to disable specific plugins conditionally.

webpack.config.js

module.exports = {
  //...
  plugins: [
    new webpack.DefinePlugin({
      // Definitions...
    }),
    false && new webpack.IgnorePlugin(), // disabled conditionally
  ],
};

A more complex example, using multiple plugins, might look something like this:

webpack.config.js

var webpack = require('webpack');
// importing plugins that do not come by default in webpack
var DashboardPlugin = require('webpack-dashboard/plugin');

// adding plugins to your configuration
module.exports = {
  //...
  plugins: [
    new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/),
    // compile time plugins
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': '"production"',
    }),
    // webpack-dev-server enhancement plugins
    new DashboardPlugin(),
    new webpack.HotModuleReplacementPlugin(),
  ],
};

DevServer

webpack-dev-server can be used to quickly develop an application. See the development guide to get started.

This page describes the options that affect the behavior of webpack-dev-server (short: dev-server) version >= 5.0.0. Migration guide from v4 to v5 can be found here.

devServer

object

This set of options is picked up by webpack-dev-server and can be used to change its behavior in various ways. Here's a rudimentary example that gzips and serves everything from our public/ directory in the project root:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },
    compress: true,
    port: 9000,
  },
};

When the server is started, there will be a message prior to the list of resolved modules:

<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:9000/
<i> [webpack-dev-server] On Your Network (IPv4): http://197.158.164.104:9000/
<i> [webpack-dev-server] On Your Network (IPv6): http://[fe80::1]:9000/
<i> [webpack-dev-server] Content not from webpack is served from '/path/to/public' directory

that will give some background on where the server is located and what it's serving.

If you're using dev-server through the Node.js API, the options in devServer will be ignored. Pass the options as the first parameter instead: new WebpackDevServer({...}, compiler). See here for an example of how to use webpack-dev-server through the Node.js API.

Usage via CLI

You can invoke webpack-dev-server via CLI by:

npx webpack serve

A list of CLI options for serve is available here

Usage via API

While it's recommended to run webpack-dev-server via the CLI, you may also choose to start a server via the API.

See the related API documentation for webpack-dev-server.

devServer.app

function

Allows you to use custom server applications, such as connect, fastify, etc. The default application used is express.

webpack.config.js

const connect = require('connect');

module.exports = {
  //...
  devServer: {
    app: () => connect(),
  },
};

devServer.allowedHosts

'auto' | 'all' [string]

This option allows you to allowlist services that are allowed to access the dev server.

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: [
      'host.com',
      'subdomain.host.com',
      'subdomain2.host.com',
      'host2.com',
    ],
  },
};

Mimicking Django's ALLOWED_HOSTS, a value beginning with . can be used as a subdomain wildcard. .host.com will match host.com, www.host.com, and any other subdomain of host.com.

webpack.config.js

module.exports = {
  //...
  devServer: {
    // this achieves the same effect as the first example
    // with the bonus of not having to update your config
    // if new subdomains need to access the dev server
    allowedHosts: ['.host.com', 'host2.com'],
  },
};

Usage via the CLI:

npx webpack serve --allowed-hosts .host.com --allowed-hosts host2.com

When set to 'all' this option bypasses host checking. THIS IS NOT RECOMMENDED as apps that do not check the host are vulnerable to DNS rebinding attacks.

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'all',
  },
};

Usage via the CLI:

npx webpack serve --allowed-hosts all

When set to 'auto' this option always allows localhost, host, and client.webSocketURL.hostname:

webpack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'auto',
  },
};

Usage via the CLI:

npx webpack serve --allowed-hosts auto

devServer.bonjour

boolean = false object

This option broadcasts the server via ZeroConf networking on start.

webpack.config.js

module.exports = {
  //...
  devServer: {
    bonjour: true,
  },
};

Usage via the CLI:

npx webpack serve --bonjour

To disable:

npx webpack serve --no-bonjour

You can also pass custom options to bonjour, for example:

webpack.config.js

module.exports = {
  //...
  devServer: {
    bonjour: {
      type: 'http',
      protocol: 'udp',
    },
  },
};

devServer.client

logging

'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'

Allows to set log level in the browser, e.g. before reloading, before an error or when Hot Module Replacement is enabled.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      logging: 'info',
    },
  },
};

Usage via the CLI:

npx webpack serve --client-logging info

overlay

boolean = true object

Shows a full-screen overlay in the browser when there are compiler errors or warnings.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: true,
    },
  },
};

Usage via the CLI:

npx webpack serve --client-overlay

To disable:

npx webpack serve --no-client-overlay

You can provide an object with the following properties for more granular control:

Property	Explanation
errors	compilation errors
runtimeErrors	unhandled runtime errors
warnings	compilation warnings

All properties are optional and default to true when not provided.

For example, to disable compilation warnings, you can provide the following configuration:

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false,
        runtimeErrors: true,
      },
    },
  },
};

Usage via the CLI:

npx webpack serve --client-overlay-errors --no-client-overlay-warnings --client-overlay-runtime-errors

To filter based on the thrown error, you can pass a function that accepts an error parameter and returns a boolean.

For example, to ignore errors thrown by AbortController.abort():

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        runtimeErrors: (error) => {
          if (error instanceof DOMException && error.name === 'AbortError') {
            return false;
          }
          return true;
        },
      },
    },
  },
};

progress

boolean

Prints compilation progress in percentage in the browser.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      progress: true,
    },
  },
};

Usage via the CLI:

npx webpack serve --client-progress

To disable:

npx webpack serve --no-client-progress

reconnect

boolean = true number

v4.4.0+

Tells dev-server the number of times it should try to reconnect the client. When true it will try to reconnect unlimited times.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: true,
    },
  },
};

Usage via the CLI:

npx webpack serve --client-reconnect

When set to false it will not try to reconnect.

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: false,
    },
  },
};

Usage via the CLI:

npx webpack serve --no-client-reconnect

You can also specify the exact number of times the client should try to reconnect.

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: 5,
    },
  },
};

Usage via the CLI:

npx webpack serve --client-reconnect 5

webSocketTransport

'ws' | 'sockjs' string

This option allows us either to choose the current devServer transport mode for clients individually or to provide custom client implementation. This allows specifying how the browser or other client communicates with the devServer.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: 'ws',
  },
};

Usage via the CLI:

npx webpack serve --client-web-socket-transport ws --web-socket-server-type ws

To create a custom client implementation, create a class that extends BaseClient.

Using path to CustomClient.js, a custom WebSocket client implementation, along with the compatible 'ws' server:

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: 'ws',
  },
};

Using custom, compatible WebSocket client and server implementations:

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

webSocketURL

string object

This option allows specifying URL to web socket server (useful when you're proxying dev server and client script does not always know where to connect to).

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: 'ws://0.0.0.0:8080/ws',
    },
  },
};

Usage via the CLI:

npx webpack serve --client-web-socket-url ws://0.0.0.0:8080/ws

You can also specify an object with the following properties:

• hostname: Tells clients connected to devServer to use the provided hostname.
• pathname: Tells clients connected to devServer to use the provided path to connect.
• password: Tells clients connected to devServer to use the provided password to authenticate.
• port: Tells clients connected to devServer to use the provided port.
• protocol: Tells clients connected to devServer to use the provided protocol.
• username: Tells clients connected to devServer to use the provided username to authenticate.

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: {
        hostname: '0.0.0.0',
        pathname: '/ws',
        password: 'dev-server',
        port: 8080,
        protocol: 'ws',
        username: 'webpack',
      },
    },
  },
};

devServer.compress

boolean = true

Enable gzip compression for everything served:

webpack.config.js

module.exports = {
  //...
  devServer: {
    compress: true,
  },
};

Usage via the CLI:

npx webpack serve --compress

To disable:

npx webpack serve --no-compress

devServer.devMiddleware

object

Provide options to webpack-dev-middleware which handles webpack assets.

webpack.config.js

module.exports = {
  devServer: {
    devMiddleware: {
      index: true,
      mimeTypes: { phtml: 'text/html' },
      publicPath: '/publicPathForDevServe',
      serverSideRender: true,
      writeToDisk: true,
    },
  },
};

devServer.headers

array function object

Adds headers to all responses:

webpack.config.js

module.exports = {
  //...
  devServer: {
    headers: {
      'X-Custom-Foo': 'bar',
    },
  },
};

You can also pass an array:

webpack.config.js

module.exports = {
  //...
  devServer: {
    headers: [
      {
        key: 'X-Custom',
        value: 'foo',
      },
      {
        key: 'Y-Custom',
        value: 'bar',
      },
    ],
  },
};

You can also pass a function:

module.exports = {
  //...
  devServer: {
    headers: () => {
      return { 'X-Bar': ['key1=value1', 'key2=value2'] };
    },
  },
};

devServer.historyApiFallback

boolean = false object

When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. Enable devServer.historyApiFallback by setting it to true:

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: true,
  },
};

Usage via the CLI:

npx webpack serve --history-api-fallback

To disable:

npx webpack serve --no-history-api-fallback

By providing an object this behavior can be controlled further using options like rewrites:

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/$/, to: '/views/landing.html' },
        { from: /^\/subpage/, to: '/views/subpage.html' },
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

When using dots in your path (common with Angular), you may need to use the disableDotRule:

webpack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};

For more options and information, see the connect-history-api-fallback documentation.

devServer.host

'local-ip' | 'local-ipv4' | 'local-ipv6' string

Specify a host to use. If you want your server to be accessible externally, specify it like this:

webpack.config.js

module.exports = {
  //...
  devServer: {
    host: '0.0.0.0',
  },
};

Usage via the CLI:

npx webpack serve --host 0.0.0.0

This also works with IPv6:

npx webpack serve --host ::

local-ip

Specifying local-ip as host will try to resolve the host option as your local IPv4 address if available, if IPv4 is not available it will try to resolve your local IPv6 address.

npx webpack serve --host local-ip

local-ipv4

Specifying local-ipv4 as host will try to resolve the host option as your local IPv4 address.

npx webpack serve --host local-ipv4

local-ipv6

Specifying local-ipv6 as host will try to resolve the host option as your local IPv6 address.

npx webpack serve --host local-ipv6

devServer.hot

'only' boolean = true

Enable webpack's Hot Module Replacement feature:

webpack.config.js

module.exports = {
  //...
  devServer: {
    hot: true,
  },
};

Usage via the CLI:

npx webpack serve --hot

To disable:

npx webpack serve --no-hot

To enable Hot Module Replacement without page refresh as a fallback in case of build failures, use hot: 'only':

webpack.config.js

module.exports = {
  //...
  devServer: {
    hot: 'only',
  },
};

Usage via the CLI:

npx webpack serve --hot only

devServer.ipc

true string

The Unix socket to listen to (instead of a host).

Setting it to true will listen to a socket at /your-os-temp-dir/webpack-dev-server.sock:

webpack.config.js

module.exports = {
  //...
  devServer: {
    ipc: true,
  },
};

Usage via the CLI:

npx webpack serve --ipc

You can also listen to a different socket with:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    ipc: path.join(__dirname, 'my-socket.sock'),
  },
};

devServer.liveReload

boolean = true

By default, the dev-server will reload/refresh the page when file changes are detected. devServer.hot option must be disabled or devServer.watchFiles option must be enabled in order for liveReload to take effect. Disable devServer.liveReload by setting it to false:

webpack.config.js

module.exports = {
  //...
  devServer: {
    liveReload: false,
  },
};

Usage via the CLI:

npx webpack serve --live-reload

To disable:

npx webpack serve --no-live-reload

devserver.onListening

function (devServer)

Provides the ability to execute a custom function when webpack-dev-server starts listening for connections on a port.

webpack.config.js

module.exports = {
  //...
  devServer: {
    onListening: function (devServer) {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      const port = devServer.server.address().port;
      console.log('Listening on port:', port);
    },
  },
};

devServer.open

boolean string object [string, object]

Tells dev-server to open the browser after server had been started. Set it to true to open your default browser.

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: true,
  },
};

Usage via the CLI:

npx webpack serve --open

To disable:

npx webpack serve --no-open

To open a specified page in a browser:

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page'],
  },
};

Usage via the CLI:

npx webpack serve --open /my-page

To open multiple specified pages in browser:

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page', '/another-page'],
  },
};

Usage via the CLI:

npx webpack serve --open /my-page --open /another-page

Provide browser name to use instead of the default one:

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      app: {
        name: 'google-chrome',
      },
    },
  },
};

Usage via the CLI:

npx webpack serve --open-app-name 'google-chrome'

The object accepts all open options:

webpack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      target: ['first.html', 'http://localhost:8080/second.html'],
      app: {
        name: 'google-chrome',
        arguments: ['--incognito', '--new-window'],
      },
    },
  },
};

devServer.port

'auto' string number

Specify a port number to listen for requests on:

webpack.config.js

module.exports = {
  //...
  devServer: {
    port: 8080,
  },
};

Usage via the CLI:

npx webpack serve --port 8080

port option can't be null or an empty string, to automatically use a free port please use port: 'auto':

webpack.config.js

module.exports = {
  //...
  devServer: {
    port: 'auto',
  },
};

Usage via the CLI:

npx webpack serve --port auto

devServer.proxy

[object, function]

Proxying some URLs can be useful when you have a separate API backend development server and you want to send API requests on the same domain.

The dev-server makes use of the powerful http-proxy-middleware package. Check out its documentation for more advanced usages. Note that some of http-proxy-middleware's features do not require a target key, e.g. its router feature, but you will still need to include a target key in your configuration here, otherwise webpack-dev-server won't pass it along to http-proxy-middleware.

With a backend on localhost:3000, you can use this to enable proxying:

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};

A request to /api/users will now proxy the request to http://localhost:3000/api/users.

If you don't want /api to be passed along, we need to rewrite the path:

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    ],
  },
};

A backend server running on HTTPS with an invalid certificate will not be accepted by default. If you want to, modify your configuration like this:

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        secure: false,
      },
    ],
  },
};

Sometimes you don't want to proxy everything. It is possible to bypass the proxy based on the return value of a function.

In the function, you get access to the request, response, and proxy options.

• Return null or undefined to continue processing the request with proxy.
• Return false to produce a 404 error for the request.
• Return a path to serve from, instead of continuing to proxy the request.

E.g. for a browser request, you want to serve an HTML page, but for an API request, you want to proxy it. You could do something like this:

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        bypass: function (req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    ],
  },
};

If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a context property:

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/auth', '/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};

Note that requests to root won't be proxied by default. To enable root proxying, the devMiddleware.index option should be specified as a falsy value:

webpack.config.js

module.exports = {
  //...
  devServer: {
    devMiddleware: {
      index: false, // specify to enable root proxying
    },
    proxy: [
      {
        context: () => true,
        target: 'http://localhost:1234',
      },
    ],
  },
};

The origin of the host header is kept when proxying by default, you can set changeOrigin to true to override this behaviour. It is useful in some cases like using name-based virtual hosted sites.

webpack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    ],
  },
};

devServer.server

'http' | 'https' | 'spdy' string object

v4.4.0+

Allows to set server and options (by default 'http').

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'http',
  },
};

Usage via the CLI:

npx webpack serve --server-type http

To serve over HTTPS with a self-signed certificate:

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'https',
  },
};

Usage via the CLI:

npx webpack serve --server-type https

To serve over HTTP/2 using spdy with a self-signed certificate:

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: 'spdy',
  },
};

Usage via the CLI:

npx webpack serve --server-type spdy

Use the object syntax to provide your own certificate:

webpack.config.js

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        ca: './path/to/server.pem',
        pfx: './path/to/server.pfx',
        key: './path/to/server.key',
        cert: './path/to/server.crt',
        passphrase: 'webpack-dev-server',
        requestCert: true,
      },
    },
  },
};

Usage via the CLI:

npx webpack serve --server-type https --server-options-key ./path/to/server.key --server-options-cert ./path/to/server.crt --server-options-ca ./path/to/ca.pem --server-options-passphrase webpack-dev-server

It also allows you to set additional TLS options like minVersion and you can directly pass the contents of respective files:

webpack.config.js

const fs = require('fs');
const path = require('path');

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        minVersion: 'TLSv1.1',
        key: fs.readFileSync(path.join(__dirname, './server.key')),
        pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
        cert: fs.readFileSync(path.join(__dirname, './server.crt')),
        ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
        passphrase: 'webpack-dev-server',
        requestCert: true,
      },
    },
  },
};

devServer.setupExitSignals

boolean = true

Allows to close dev server and exit the process on SIGINT and SIGTERM signals.

webpack.config.js

module.exports = {
  //...
  devServer: {
    setupExitSignals: true,
  },
};

devServer.setupMiddlewares

function (middlewares, devServer)

v4.7.0+

Provides the ability to execute a custom function and apply custom middleware(s).

webpack.config.js

module.exports = {
  // ...
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('webpack-dev-server is not defined');
      }

      devServer.app.get('/setup-middleware/some/path', (_, response) => {
        response.send('setup-middlewares option GET');
      });

      // Use the `unshift` method if you want to run a middleware before all other middlewares
      // or when you are migrating from the `onBeforeSetupMiddleware` option
      middlewares.unshift({
        name: 'first-in-array',
        // `path` is optional
        path: '/foo/path',
        middleware: (req, res) => {
          res.send('Foo!');
        },
      });

      // Use the `push` method if you want to run a middleware after all other middlewares
      // or when you are migrating from the `onAfterSetupMiddleware` option
      middlewares.push({
        name: 'hello-world-test-one',
        // `path` is optional
        path: '/foo/bar',
        middleware: (req, res) => {
          res.send('Foo Bar!');
        },
      });

      middlewares.push((req, res) => {
        res.send('Hello World!');
      });

      return middlewares;
    },
  },
};

devServer.static

boolean string object [string, object]

This option allows configuring options for serving static files from the directory (by default 'public' directory). To disable set it to false:

webpack.config.js

module.exports = {
  //...
  devServer: {
    static: false,
  },
};

Usage via CLI:

npx webpack serve --static

To disable:

npx webpack serve --no-static

To watch a single directory:

webpack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets'],
  },
};

Usage via CLI:

npx webpack serve --static assets

To watch multiple static directories:

webpack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets', 'css'],
  },
};

Usage via CLI:

npx webpack serve --static assets --static css

directory

string = path.join(process.cwd(), 'public')

Tell the server where to serve the content from. This is only necessary if you want to serve static files. static.publicPath will be used to determine where the bundles should be served from and takes precedence.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
    },
  },
};

Provide an array of objects in case you have multiple static folders:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: [
      {
        directory: path.join(__dirname, 'assets'),
      },
      {
        directory: path.join(__dirname, 'css'),
      },
    ],
  },
};

staticOptions

object

It is possible to configure advanced options for serving static files from static.directory. See the Express documentation for the possible options.

webpack.config.js

module.exports = {
  //...
  devServer: {
    static: {
      staticOptions: {
        redirect: true,
      },
    },
  },
};

publicPath

string = '/' [string]

Tell the server at which URL to serve static.directory content. For example to serve a file assets/manifest.json at /serve-public-path-url/manifest.json, your configurations should be as following:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'assets'),
      publicPath: '/serve-public-path-url',
    },
  },
};

Provide an array of objects in case you have multiple static folders:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: [
      {
        directory: path.join(__dirname, 'assets'),
        publicPath: '/serve-public-path-url',
      },
      {
        directory: path.join(__dirname, 'css'),
        publicPath: '/other-serve-public-path-url',
      },
    ],
  },
};

serveIndex

boolean object = { icons: true }

Tell dev-server to use serveIndex middleware when enabled.

serveIndex middleware generates directory listings on viewing directories that don't have an index.html file.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      serveIndex: true,
    },
  },
};

Usage via CLI:

npx webpack serve --static-serve-index

To disable:

npx webpack serve --no-static-serve-index

watch

boolean object

Tell dev-server to watch the files served by the static.directory option. It is enabled by default, and file changes will trigger a full page reload. This can be disabled by setting the watch option to false.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      watch: false,
    },
  },
};

Usage via CLI:

npx webpack serve --static-watch

To disable:

npx webpack serve --no-static-watch

It is possible to configure advanced options for watching static files from static.directory. See the chokidar documentation for the possible options.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'),
      watch: {
        ignored: '*.txt',
        usePolling: false,
      },
    },
  },
};

devServer.watchFiles

string object [string, object]

This option allows you to configure a list of globs/directories/files to watch for file changes. For example:

webpack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: ['src/**/*.php', 'public/**/*'],
  },
};

It is possible to configure advanced options for watching files. See the chokidar documentation for the possible options.

webpack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: {
      paths: ['src/**/*.php', 'public/**/*'],
      options: {
        usePolling: false,
      },
    },
  },
};

devServer.webSocketServer

false | 'sockjs' | 'ws' string function object

This option allows us either to choose the current web-socket server or to provide custom web-socket server implementation.

The current default mode is 'ws'. This mode uses ws as a server, and native WebSockets on the client.

webpack.config.js

module.exports = {
  //...
  devServer: {
    webSocketServer: 'ws',
  },
};

To create a custom server implementation, create a class that extends BaseServer.

Using path to CustomServer.js, a custom WebSocket server implementation, along with the compatible 'ws' client:

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

Using custom, compatible WebSocket client and server implementations:

webpack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

Cache

cache

boolean object

Cache the generated webpack modules and chunks to improve build speed. cache is set to type: 'memory' in development mode and disabled in production mode. cache: true is an alias to cache: { type: 'memory' }. To disable caching pass false:

webpack.config.js

module.exports = {
  //...
  cache: false,
};

While setting cache.type to 'filesystem' opens up more options for configuration.

cache.allowCollectingMemory

Collect unused memory allocated during deserialization, only available when cache.type is set to 'filesystem'. This requires copying data into smaller buffers and has a performance cost.

• Type: boolean
  • It defaults to false in production mode and true in development mode.
• 5.35.0+

webpack.config.js

module.exports = {
  cache: {
    type: 'filesystem',
    allowCollectingMemory: true,
  },
};

cache.buildDependencies

object

cache.buildDependencies is an object of arrays of additional code dependencies for the build. Webpack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.

Defaults to webpack/lib to get all dependencies of webpack.

webpack.config.js

module.exports = {
  cache: {
    buildDependencies: {
      // This makes all dependencies of this file - build dependencies
      config: [__filename],
      // By default webpack and loaders are build dependencies
    },
  },
};

cache.cacheDirectory

string

Base directory for the cache. Defaults to node_modules/.cache/webpack.

cache.cacheDirectory option is only available when cache.type is set to 'filesystem'.

webpack.config.js

const path = require('path');

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    cacheDirectory: path.resolve(__dirname, '.temp_cache'),
  },
};

cache.cacheLocation

string

Locations for the cache. Defaults to path.resolve(cache.cacheDirectory, cache.name).

webpack.config.js

const path = require('path');

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    cacheLocation: path.resolve(__dirname, '.test_cache'),
  },
};

cache.cacheUnaffected

Cache computation of modules which are unchanged and reference only unchanged modules. It can only be used along with cache.type of 'memory', besides, experiments.cacheUnaffected must be enabled to use it.

• Type: boolean
• v5.54.0+

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'memory',
    cacheUnaffected: true,
  },
};

cache.compression

false | 'gzip' | 'brotli'

5.42.0+

Compression type used for the cache files. By default it is false.

cache.compression option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    compression: 'gzip',
  },
};

cache.hashAlgorithm

string

Algorithm used the hash generation. See Node.js crypto for more details. Defaults to md4.

cache.hashAlgorithm option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    hashAlgorithm: 'md4',
  },
};

cache.idleTimeout

number = 60000

Time in milliseconds. cache.idleTimeout denotes the time period after which the cache storing should happen.

cache.idleTimeout option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //..
  cache: {
    type: 'filesystem',
    idleTimeout: 60000,
  },
};

cache.idleTimeoutAfterLargeChanges

number = 1000

5.41.0+

Time in milliseconds. cache.idleTimeoutAfterLargeChanges is the time period after which the cache storing should happen when larger changes have been detected.

cache.idleTimeoutAfterLargeChanges option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //..
  cache: {
    type: 'filesystem',
    idleTimeoutAfterLargeChanges: 1000,
  },
};

cache.idleTimeoutForInitialStore

number = 5000

Time in milliseconds. cache.idleTimeoutForInitialStore is the time period after which the initial cache storing should happen.

cache.idleTimeoutForInitialStore option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //..
  cache: {
    type: 'filesystem',
    idleTimeoutForInitialStore: 0,
  },
};

cache.managedPaths

[string] = ['./node_modules']

cache.managedPaths is an array of package-manager only managed paths. Webpack will avoid hashing and timestamping them, assume the version is unique and will use it as a snapshot (for both memory and filesystem cache).

cache.maxAge

number = 5184000000

5.30.0+

The amount of time in milliseconds that unused cache entries are allowed to stay in the filesystem cache; defaults to one month.

cache.maxAge option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  // ...
  cache: {
    type: 'filesystem',
    maxAge: 5184000000,
  },
};

cache.maxGenerations

number

5.30.0+

Define the lifespan of unused cache entries in the memory cache.

• cache.maxGenerations: 1: Cache entries are removed after being unused for a single compilation.

• cache.maxGenerations: Infinity: Cache entries are kept forever.

cache.maxGenerations option is only available when cache.type is set to 'memory'.

webpack.config.js

module.exports = {
  // ...
  cache: {
    type: 'memory',
    maxGenerations: Infinity,
  },
};

cache.maxMemoryGenerations

number

5.30.0+

Define the lifespan of unused cache entries in the memory cache.

• cache.maxMemoryGenerations: 0: Persistent cache will not use an additional memory cache. It will only cache items in memory until they are serialized to disk. Once serialized the next read will deserialize them from the disk again. This mode will minimize memory usage but introduce a performance cost.

• cache.maxMemoryGenerations: 1: This will purge items from the memory cache once they are serialized and unused for at least one compilation. When they are used again they will be deserialized from the disk. This mode will minimize memory usage while still keeping active items in the memory cache.

• cache.maxMemoryGenerations: small numbers > 0 will have a performance cost for the GC operation. It gets lower as the number increases.

• cache.maxMemoryGenerations: defaults to 10 in development mode and to Infinity in production mode.

cache.maxMemoryGenerations option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  // ...
  cache: {
    type: 'filesystem',
    maxMemoryGenerations: Infinity,
  },
};

cache.memoryCacheUnaffected

Cache computation of modules which are unchanged and reference only unchanged modules in memory. It can only be used along with cache.type of 'filesystem', besides, experiments.cacheUnaffected must be enabled to use it.

• Type: boolean
• v5.54.0+

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    memoryCacheUnaffected: true,
  },
};

cache.name

string

Name for the cache. Different names will lead to different coexisting caches. Defaults to ${config.name}-${config.mode}. Using cache.name makes sense when you have multiple configurations which should have independent caches.

cache.name option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    name: 'AppBuildCache',
  },
};

cache.profile

boolean = false

Track and log detailed timing information for individual cache items of type 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    profile: true,
  },
};

cache.readonly

boolean 5.85.0

Prevent webpack from storing cache into file system. Only available when cache.type === "filesystem" and cache.store === 'pack'.

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    store: 'pack',
    readonly: true,
  },
};

cache.store

string = 'pack': 'pack'

cache.store tells webpack when to store data on the file system.

• 'pack': Store data when compiler is idle in a single file for all cached items

cache.store option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    store: 'pack',
  },
};

cache.type

string: 'memory' | 'filesystem'

Sets the cache type to either in memory or on the file system. The memory option is straightforward, it tells webpack to store cache in memory and doesn't allow additional configuration:

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'memory',
  },
};

cache.version

string = ''

Version of the cache data. Different versions won't allow to reuse the cache and override existing content. Update the version when configuration changed in a way which doesn't allow to reuse cache. This will invalidate the cache.

cache.version option is only available when cache.type is set to 'filesystem'.

webpack.config.js

module.exports = {
  //...
  cache: {
    type: 'filesystem',
    version: 'your_version',
  },
};

Setup cache in CI/CD system

Filesystem cache allows to share cache between builds in CI. To setup cache:

• CI should have an option to share cache between builds.
• CI should run job in the same absolute path. This is important since webpack cache files store absolute paths.

GitLab CI/CD

Common config could looks like

variables:
  # fallback to use "main" branch cache, requires GitLab Runner 13.4
  CACHE_FALLBACK_KEY: main

# this is webpack build job
build-job:
  cache:
    key: '$CI_COMMIT_REF_SLUG' # branch/tag name
    paths:
      # cache directory
      # make sure that you don't run "npm ci" in this job or change default cache directory
      # otherwise "npm ci" will prune cache files
      - node_modules/.cache/webpack/

Github actions

- uses: actions/cache@v3
  with:
    # cache directory
    path: node_modules/.cache/webpack/
    key: ${{ GITHUB_REF_NAME }}-webpack-build
    # fallback to use "main" branch cache
    restore-keys: |
      main-webpack-build

Devtool

This option controls if and how source maps are generated.

Use the SourceMapDevToolPlugin for a more fine grained configuration. See the source-map-loader to deal with existing source maps.

devtool

string = 'eval' false

Choose a style of source mapping to enhance the debugging process. These values can affect build and rebuild speed dramatically.

devtool	performance	production	quality	comment
(none)	build: fastest rebuild: fastest	yes	bundle	Recommended choice for production builds with maximum performance.
eval	build: fast rebuild: fastest	no	generated	Recommended choice for development builds with maximum performance.
eval-cheap-source-map	build: ok rebuild: fast	no	transformed	Tradeoff choice for development builds.
eval-cheap-module-source-map	build: slow rebuild: fast	no	original lines	Tradeoff choice for development builds.
eval-source-map	build: slowest rebuild: ok	no	original	Recommended choice for development builds with high quality SourceMaps.
cheap-source-map	build: ok rebuild: slow	no	transformed
cheap-module-source-map	build: slow rebuild: slow	no	original lines
source-map	build: slowest rebuild: slowest	yes	original	Recommended choice for production builds with high quality SourceMaps.
inline-cheap-source-map	build: ok rebuild: slow	no	transformed
inline-cheap-module-source-map	build: slow rebuild: slow	no	original lines
inline-source-map	build: slowest rebuild: slowest	no	original	Possible choice when publishing a single file
eval-nosources-cheap-source-map	build: ok rebuild: fast	no	transformed	source code not included
eval-nosources-cheap-module-source-map	build: slow rebuild: fast	no	original lines	source code not included
eval-nosources-source-map	build: slowest rebuild: ok	no	original	source code not included
inline-nosources-cheap-source-map	build: ok rebuild: slow	no	transformed	source code not included
inline-nosources-cheap-module-source-map	build: slow rebuild: slow	no	original lines	source code not included
inline-nosources-source-map	build: slowest rebuild: slowest	no	original	source code not included
nosources-cheap-source-map	build: ok rebuild: slow	no	transformed	source code not included
nosources-cheap-module-source-map	build: slow rebuild: slow	no	original lines	source code not included
nosources-source-map	build: slowest rebuild: slowest	yes	original	source code not included
hidden-nosources-cheap-source-map	build: ok rebuild: slow	no	transformed	no reference, source code not included
hidden-nosources-cheap-module-source-map	build: slow rebuild: slow	no	original lines	no reference, source code not included
hidden-nosources-source-map	build: slowest rebuild: slowest	yes	original	no reference, source code not included
hidden-cheap-source-map	build: ok rebuild: slow	no	transformed	no reference
hidden-cheap-module-source-map	build: slow rebuild: slow	no	original lines	no reference
hidden-source-map	build: slowest rebuild: slowest	yes	original	no reference. Possible choice when using SourceMap only for error reporting purposes.

shortcut	explanation
performance: build	How is the performance of the initial build affected by the devtool setting?
performance: rebuild	How is the performance of the incremental build affected by the devtool setting? Slow devtools might reduce development feedback loop in watch mode. The scale is different compared to the build performance, as one would expect rebuilds to be faster than builds.
production	Does it make sense to use this devtool for production builds? It's usually no when the devtool has a negative effect on user experience.
quality: bundled	You will see all generated code of a chunk in a single blob of code. This is the raw output file without any devtooling support
quality: generated	You will see the generated code, but each module is shown as separate code file in browser devtools.
quality: transformed	You will see generated code after the preprocessing by loaders but before additional webpack transformations. Only source lines will be mapped and column information will be discarded resp. not generated. This prevents setting breakpoints in the middle of lines which doesn't work together with minimizer.
quality: original lines	You will see the original code that you wrote, assuming all loaders support SourceMapping. Only source lines will be mapped and column information will be discarded resp. not generated. This prevents setting breakpoints in the middle of lines which doesn't work together with minimizer.
quality: original	You will see the original code that you wrote, assuming all loaders support SourceMapping.
eval-* addition	generate SourceMap per module and attach it via eval. Recommended for development, because of improved rebuild performance. Note that there is a windows defender issue, which causes huge slowdown due to virus scanning.
inline-* addition	inline the SourceMap to the original file instead of creating a separate file.
hidden-* addition	no reference to the SourceMap added. When SourceMap is not deployed, but should still be generated, e. g. for error reporting purposes.
nosources-* addition	source code is not included in SourceMap. This can be useful when the original files should be referenced (further config options needed).

Some of these values are suited for development and some for production. For development you typically want fast Source Maps at the cost of bundle size, but for production you want separate Source Maps that are accurate and support minimizing.

Qualities

bundled code - You see all generated code as a big blob of code. You don't see modules separated from each other.

generated code - You see each module separated from each other, annotated with module names. You see the code generated by webpack. Example: Instead of import {test} from "module"; test(); you see something like var module__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(42); module__WEBPACK_IMPORTED_MODULE_1__.a();.

transformed code - You see each module separated from each other, annotated with module names. You see the code before webpack transforms it, but after Loaders transpile it. Example: Instead of import {test} from "module"; class A extends test {} you see something like import {test} from "module"; var A = function(_test) { ... }(test);

original source - You see each module separated from each other, annotated with module names. You see the code before transpilation, as you authored it. This depends on Loader support.

without source content - Contents for the sources are not included in the Source Maps. Browsers usually try to load the source from the webserver or filesystem. You have to make sure to set output.devtoolModuleFilenameTemplate correctly to match source urls.

(lines only) - Source Maps are simplified to a single mapping per line. This usually means a single mapping per statement (assuming you author it this way). This prevents you from debugging execution on statement level and from settings breakpoints on columns of a line. Combining with minimizing is not possible as minimizers usually only emit a single line.

Development

The following options are ideal for development:

eval - Each module is executed with eval() and //# sourceURL. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code (No Source Maps from Loaders).

eval-source-map - Each module is executed with eval() and a SourceMap is added as a DataUrl to the eval(). Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code. It yields the best quality SourceMaps for development.

eval-cheap-source-map - Similar to eval-source-map, each module is executed with eval(). It is "cheap" because it doesn't have column mappings, it only maps line numbers. It ignores SourceMaps from Loaders and only display transpiled code similar to the eval devtool.

eval-cheap-module-source-map - Similar to eval-cheap-source-map, however, in this case Source Maps from Loaders are processed for better results. However Loader Source Maps are simplified to a single mapping per line.

Special cases

The following options are not ideal for development nor production. They are needed for some special cases, i. e. for some 3rd party tools.

inline-source-map - A SourceMap is added as a DataUrl to the bundle.

cheap-source-map - A SourceMap without column-mappings ignoring loader Source Maps.

inline-cheap-source-map - Similar to cheap-source-map but SourceMap is added as a DataUrl to the bundle.

cheap-module-source-map - A SourceMap without column-mappings that simplifies loader Source Maps to a single mapping per line.

inline-cheap-module-source-map - Similar to cheap-module-source-map but SourceMap is added as a DataUrl to the bundle.

Production

These options are typically used in production:

(none) (Omit the devtool option or set devtool: false) - No SourceMap is emitted. This is a good option to start with.

source-map - A full SourceMap is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.

hidden-source-map - Same as source-map, but doesn't add a reference comment to the bundle. Useful if you only want SourceMaps to map error stack traces from error reports, but don't want to expose your SourceMap for the browser development tools.

nosources-source-map - A SourceMap is created without the sourcesContent in it. It can be used to map stack traces on the client without exposing all of the source code. You can deploy the Source Map file to the webserver.

Extends

extends

string | string[]

webpack v5.82.0+ webpack-cli v5.1.0+

The extends property allows you to extend an existing configuration to use as the base. It internally uses the webpack-merge package to merge the configurations and helps you to avoid duplicating configurations between multiple configurations.

base.webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: 'babel-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
    }),
  ],
};

webpack.config.js

module.exports = {
  extends: path.resolve(__dirname, './base.webpack.config.js'),
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

Extending multiple configurations

You can extend multiple configurations at once by passing an array of configuration paths to the extends property.

Configurations from the extends property are merged from right to left, meaning that the configuration on the right will be merged into the configuration on the left. Configuration can be overridden by passing the same property in the configuration on the right.

js.webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: 'babel-loader',
        exclude: /node_modules/,
      },
    ],
  },
};

css.webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};

webpack.config.js

module.exports = {
  extends: [
    path.resolve(__dirname, './js.webpack.config.js'),
    path.resolve(__dirname, './css.webpack.config.js'),
  ],
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

Overridding Configurations

You can override configurations from the extended configuration by passing the same property in the configuration that extends it.

base.webpack.config.js

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

webpack.config.js

module.exports = {
  extends: path.resolve(__dirname, './base.webpack.config.js'),
  entry: './src/index.js',
  // overriding the output path and filename
  output: {
    path: path.resolve(__dirname, 'build'),
    filename: '[name].bundle.js',
  },
};

Loading configuration from external packages

You can also load configuration from third-party packages by passing the package name to the extends property. The package must export the webpack configuration in package.json.

webpack.config.js

module.exports = {
  extends: require.resolve('webpack-config-foo'),
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
};

Target

Webpack can compile for multiple environments or targets. To understand what a target is in detail, read through the targets concept page.

target

string [string] false

Instructs webpack to generate runtime code for a specific environment. Note that webpack runtime code is not the same as the user code you write, you should transpile those code with transpilers like Babel if you want to target specific environments, e.g, you have arrow functions in source code and want to run the bundled code in ES5 environments. Webpack won't transpile them automatically with a target configured.

Defaults to 'browserslist' or to 'web' when no browserslist configuration was found.

string

The following string values are supported via WebpackOptionsApply:

Option	Description
async-node[[X].Y]	Compile for usage in a Node.js-like environment (uses fs and vm to load chunks asynchronously)
electron[[X].Y]-main	Compile for Electron for main process.
electron[[X].Y]-renderer	Compile for Electron for renderer process, providing a target using JsonpTemplatePlugin, FunctionModulePlugin for browser environments and NodeTargetPlugin and ExternalsPlugin for CommonJS and Electron built-in modules.
electron[[X].Y]-preload	Compile for Electron for renderer process, providing a target using NodeTemplatePlugin with asyncChunkLoading set to true, FunctionModulePlugin for browser environments and NodeTargetPlugin and ExternalsPlugin for CommonJS and Electron built-in modules.
node[[X].Y]	Compile for usage in a Node.js-like environment (uses Node.js require to load chunks)
node-webkit[[X].Y]	Compile for usage in WebKit and uses JSONP for chunk loading. Allows importing of built-in Node.js modules and nw.gui (experimental)
nwjs[[X].Y]	The same as node-webkit
web	Compile for usage in a browser-like environment (default)
webworker	Compile as WebWorker
esX	Compile for specified ECMAScript version. Examples: es5, es2020.
browserslist	Infer a platform and the ES-features from a browserslist-config (default if browserslist config is available)

For example, when the target is set to "electron-main", webpack includes multiple electron specific variables.

A version of node or electron may be optionally specified. This is denoted by the [[X].Y] in the table above.

webpack.config.js

module.exports = {
  // ...
  target: 'node12.18',
};

It helps determinate ES-features that may be used to generate a runtime-code (all the chunks and modules are wrapped by runtime code).

browserslist

If a project has a browserslist config, then webpack will use it for:

• Determinate ES-features that may be used to generate a runtime-code.
• Infer an environment (e.g: last 2 node versions the same as target: "node" with some output.environment settings).

Supported browserslist values:

• browserslist - use automatically resolved browserslist config and environment (from the nearest package.json or BROWSERSLIST environment variable, see browserslist documentation for details)
• browserslist:modern - use modern environment from automatically resolved browserslist config
• browserslist:last 2 versions - use an explicit browserslist query (config will be ignored)
• browserslist:/path/to/config - explicitly specify browserslist config
• browserslist:/path/to/config:modern - explicitly specify browserslist config and an environment

[string]

When multiple targets are passed, then common subset of features will be used:

webpack.config.js

module.exports = {
  // ...
  target: ['web', 'es5'],
};

Webpack will generate a runtime code for web platform and will use only ES5 features.

Not all targets may be mixed for now.

webpack.config.js

module.exports = {
  // ...
  target: ['web', 'node'],
};

Will cause an error. Webpack does not support universal target for now.

false

Set target to false if none of the predefined targets from the list above meet your needs, no plugins will be applied.

webpack.config.js

module.exports = {
  // ...
  target: false,
};

Or you can apply specific plugins you want:

webpack.config.js

const webpack = require('webpack');

module.exports = {
  // ...
  target: false,
  plugins: [
    new webpack.web.JsonpTemplatePlugin(options.output),
    new webpack.LoaderTargetPlugin('web'),
  ],
};

When no information about the target or the environment features is provided, then ES2015 will be used.

Watch and WatchOptions

Webpack can watch files and recompile whenever they change. This page explains how to enable this and a couple of tweaks you can make if watching does not work properly for you.

watch

boolean = false

Turn on watch mode. This means that after the initial build, webpack will continue to watch for changes in any of the resolved files.

webpack.config.js

module.exports = {
  //...
  watch: true,
};

watchOptions

object

A set of options used to customize watch mode:

webpack.config.js

module.exports = {
  //...
  watchOptions: {
    aggregateTimeout: 200,
    poll: 1000,
  },
};

watchOptions.aggregateTimeout

number = 20

Add a delay before rebuilding once the first file changed. This allows webpack to aggregate any other changes made during this time period into one rebuild. Pass a value in milliseconds:

module.exports = {
  //...
  watchOptions: {
    aggregateTimeout: 600,
  },
};

watchOptions.ignored

RegExp string [string]

For some systems, watching many files can result in a lot of CPU or memory usage. It is possible to exclude a huge folder like node_modules using a regular expression:

webpack.config.js

module.exports = {
  //...
  watchOptions: {
    ignored: /node_modules/,
  },
};

Alternatively, a glob pattern may be used:

webpack.config.js

module.exports = {
  //...
  watchOptions: {
    ignored: '**/node_modules',
  },
};

It is also possible to use multiple glob patterns:

webpack.config.js

module.exports = {
  //...
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/node_modules'],
  },
};

In addition, you can specify an absolute path:

const path = require('path');
module.exports = {
  //...
  watchOptions: {
    ignored: [path.posix.resolve(__dirname, './ignored-dir')],
  },
};

When using glob patterns, we convert them to regular expressions with glob-to-regexp, so make sure to get yourself familiar with it before you use glob patterns for watchOptions.ignored.

watchOptions.poll

boolean = false number

Turn on polling by passing true which would set the default poll interval to 5007, or specifying a poll interval in milliseconds:

webpack.config.js

module.exports = {
  //...
  watchOptions: {
    poll: 1000, // Check for changes every second
  },
};

watchOptions.followSymlinks

Follow symbolic links while looking for a file. This is usually not needed as webpack already resolves symlinks with resolve.symlinks.

• Type: boolean

• Example:

  module.exports = {
    //...
    watchOptions: {
      followSymlinks: true,
    },
  };

watchOptions.stdin

Stop watching when stdin stream has ended.

• Type: boolean

• Example:

  module.exports = {
    //...
    watchOptions: {
      stdin: true,
    },
  };

Troubleshooting

If you are experiencing any issues, please see the following notes. There are a variety of reasons why webpack might miss a file change.

Changes Seen But Not Processed

Verify that webpack is not being notified of changes by running webpack with the --progress flag. If progress shows on save but no files are outputted, it is likely a configuration issue, not a file watching issue.

webpack --watch --progress

Not Enough Watchers

Verify that you have enough available watchers in your system. If this value is too low, the file watcher in Webpack won't recognize the changes:

cat /proc/sys/fs/inotify/max_user_watches

Arch users, add fs.inotify.max_user_watches=524288 to /etc/sysctl.d/99-sysctl.conf and then execute sysctl --system. Ubuntu users (and possibly others), execute: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p.

macOS fsevents Bug

On macOS, folders can get corrupted in certain scenarios. See this article.

Windows Paths

Because webpack expects absolute paths for many configuration options such as __dirname + '/app/folder' the Windows \ path separator can break some functionality.

Use the correct separators. I.e. path.resolve(__dirname, 'app/folder') or path.join(__dirname, 'app', 'folder').

Vim

On some machines Vim is preconfigured with the backupcopy option set to auto. This could potentially cause problems with the system's file watching mechanism. Switching this option to yes will make sure a copy of the file is made and the original one overwritten on save.

:set backupcopy=yes

Saving in WebStorm

When using the JetBrains WebStorm IDE, you may find that saving changed files does not trigger the watcher as you might expect. Try disabling the Back up files before saving option in the settings, which determines whether files are saved to a temporary location first before the originals are overwritten: uncheck File > {Settings|Preferences} > Appearance & Behavior > System Settings > Back up files before saving. On some versions of Webstorm, this option may be called Use "safe write" (save changes to a temporary file first).

Externals

The externals configuration option provides a way of excluding dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer's (any end-user application) environment. This feature is typically most useful to library developers, however there are a variety of applications for it.

externals

string object function RegExp [string, object, function, RegExp]

Prevent bundling of certain imported packages and instead retrieve these external dependencies at runtime.

For example, to include jQuery from a CDN instead of bundling it:

index.html

<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>

webpack.config.js

module.exports = {
  //...
  externals: {
    jquery: 'jQuery',
  },
};

This leaves any dependent modules unchanged, i.e. the code shown below will still work:

import $ from 'jquery';

$('.my-element').animate(/* ... */);

The property name jquery specified under externals in the above webpack.config.js indicates that the module jquery in import $ from 'jquery' should be excluded from bundling. In order to replace this module, the value jQuery will be used to retrieve a global jQuery variable, as the default external library type is var, see externalsType.

While we showed an example consuming external global variable above, the external can actually be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in externalsType.

string

Depending on the externalsType, this could be the name of the global variable (see 'global', 'this', 'var', 'window') or the name of the module (see amd, commonjs, module, umd).

You can also use the shortcut syntax if you're defining only 1 external:

module.exports = {
  //...
  externals: 'jquery',
};

equals to

module.exports = {
  //...
  externals: {
    jquery: 'jquery',
  },
};

You can specify the external library type to the external with the ${externalsType} ${libraryName} syntax. It will override the default external library type specified in the externalsType option.

For example, if the external library is a CommonJS module, you can specify

module.exports = {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};

[string]

module.exports = {
  //...
  externals: {
    subtract: ['./math', 'subtract'],
  },
};

subtract: ['./math', 'subtract'] allows you select part of a module, where ./math is the module and your bundle only requires the subset under the subtract variable.

When the externalsType is commonjs, this example would translate to require('./math').subtract; while when the externalsType is window, this example would translate to window["./math"]["subtract"];

Similar to the string syntax, you can specify the external library type with the ${externalsType} ${libraryName} syntax, in the first item of the array, for example:

module.exports = {
  //...
  externals: {
    subtract: ['commonjs ./math', 'subtract'],
  },
};

object

module.exports = {
  //...
  externals: {
    react: 'react',
  },

  // or

  externals: {
    lodash: {
      commonjs: 'lodash',
      amd: 'lodash',
      root: '_', // indicates global variable
    },
  },

  // or

  externals: {
    subtract: {
      root: ['math', 'subtract'],
    },
  },
};

This syntax is used to describe all the possible ways that an external library can be made available. lodash here is available as lodash under AMD and CommonJS module systems but available as _ in a global variable form. subtract here is available via the property subtract under the global math object (e.g. window['math']['subtract']).

function

• function ({ context, request, contextInfo, getResolve }, callback)
• function ({ context, request, contextInfo, getResolve }) => promise 5.15.0+

It might be useful to define your own function to control the behavior of what you want to externalize from webpack. webpack-node-externals, for example, excludes all modules from the node_modules directory and provides options to allowlist packages.

Here're arguments the function can receive:

• ctx (object): Object containing details of the file.
  • ctx.context (string): The directory of the file which contains the import.
  • ctx.request (string): The import path being requested.
  • ctx.contextInfo (object): Contains information about the issuer (e.g. the layer and compiler)
  • ctx.getResolve 5.15.0+: Get a resolve function with the current resolver options.
• callback (function (err, result, type)): Callback function used to indicate how the module should be externalized.

The callback function takes three arguments:

• err (Error): Used to indicate if there has been an error while externalizing the import. If there is an error, this should be the only parameter used.
• result (string [string] object): Describes the external module with the other external formats (string, [string], or object)
• type (string): Optional parameter that indicates the module external type (if it has not already been indicated in the result parameter).

As an example, to externalize all imports where the import path matches a regular expression you could do the following:

webpack.config.js

module.exports = {
  //...
  externals: [
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        // Externalize to a commonjs module using the request path
        return callback(null, 'commonjs ' + request);
      }

      // Continue without externalizing the import
      callback();
    },
  ],
};

Other examples using different module formats:

webpack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a `commonjs2` module located in `@scope/library`
      callback(null, '@scope/library', 'commonjs2');
    },
  ],
};

webpack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a global variable called `nameOfGlobal`.
      callback(null, 'nameOfGlobal');
    },
  ],
};

webpack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a named export in the `@scope/library` module.
      callback(null, ['@scope/library', 'namedexport'], 'commonjs');
    },
  ],
};

webpack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a UMD module
      callback(null, {
        root: 'componentsGlobal',
        commonjs: '@scope/components',
        commonjs2: '@scope/components',
        amd: 'components',
      });
    },
  ],
};

RegExp

Every dependency that matches the given regular expression will be excluded from the output bundles.

webpack.config.js

module.exports = {
  //...
  externals: /^(jquery|\$)$/i,
};

In this case, any dependency named jQuery, capitalized or not, or $ would be externalized.

Combining syntaxes

Sometimes you may want to use a combination of the above syntaxes. This can be done in the following manner:

webpack.config.js

module.exports = {
  //...
  externals: [
    {
      // String
      react: 'react',
      // Object
      lodash: {
        commonjs: 'lodash',
        amd: 'lodash',
        root: '_', // indicates global variable
      },
      // [string]
      subtract: ['./math', 'subtract'],
    },
    // Function
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        return callback(null, 'commonjs ' + request);
      }
      callback();
    },
    // Regex
    /^(jquery|\$)$/i,
  ],
};

For more information on how to use this configuration, please refer to the article on how to author a library.

byLayer

function object

Specify externals by layer.

webpack.config.js

module.exports = {
  externals: {
    byLayer: {
      layer: {
        external1: 'var 43',
      },
    },
  },
};

externalsType

string = 'var'

Specify the default type of externals. amd, umd, system and jsonp externals depend on the output.libraryTarget being set to the same value e.g. you can only consume amd externals within an amd library.

Supported types:

• 'amd'
• 'amd-require'
• 'assign' - same as 'var'
• 'commonjs'
• 'commonjs-module'
• 'global'
• 'import' - uses import() to load a native EcmaScript module (async module)
• 'jsonp'
• 'module'
• 'import'
• 'module-import'
• 'node-commonjs'
• 'promise' - same as 'var' but awaits the result (async module)
• 'self'
• 'system'
• 'script'
• 'this'
• 'umd'
• 'umd2'
• 'var'
• 'window'

webpack.config.js

module.exports = {
  //...
  externalsType: 'promise',
};

externalsType.commonjs

Specify the default type of externals as 'commonjs'. Webpack will generate code like const X = require('...') for externals used in a module.

Example

import fs from 'fs-extra';

webpack.config.js

module.exports = {
  // ...
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};

Will generate into something like:

const fs = require('fs-extra');

Note that there will be a require() in the output bundle.

externalsType.global

Specify the default type of externals as 'global'. Webpack will read the external as a global variable on the globalObject.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};

Will generate into something like

const jq = global['$'];
jq('.my-element').animate(/* ... */);

externalsType.module

Specify the default type of externals as 'module'. Webpack will generate code like import * as X from '...' for externals used in a module.

Make sure to enable experiments.outputModule first, otherwise webpack will throw errors.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'module',
  externals: {
    jquery: 'jquery',
  },
};

Will generate into something like

import * as __WEBPACK_EXTERNAL_MODULE_jquery__ from 'jquery';

const jq = __WEBPACK_EXTERNAL_MODULE_jquery__['default'];
jq('.my-element').animate(/* ... */);

Note that there will be an import statement in the output bundle.

externalsType.import

5.94.0+

Specify the default type of externals as 'import'. Webpack will generate code like import('...') for externals used in a module.

Example

async function foo() {
  const jq = await import('jQuery');
  jq('.my-element').animate(/* ... */);
}

webpack.config.js

module.exports = {
  externalsType: 'import',
  externals: {
    jquery: 'jquery',
  },
};

Will generate something like below:

var __webpack_modules__ = {
  jQuery: (module) => {
    module.exports = import('jQuery');
  },
};

// webpack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jQuery')
  );
  jq('.my-element').animate(/* ... */);
}

Note that the output bundle will have an import() statement.

externalsType.module-import

5.94.0+

Specify the default type of externals as 'module-import'. This combines 'module' and 'import'. Webpack will automatically detect the type of import syntax, setting it to 'module' for static imports and 'import' for dynamic imports.

Ensure to enable experiments.outputModule first if static imports exist, otherwise, webpack will throw errors.

Example

import { attempt } from 'lodash';

async function foo() {
  const jq = await import('jQuery');
  attempt(() => jq('.my-element').animate(/* ... */));
}

webpack.config.js

module.exports = {
  externalsType: 'import',
  externals: {
    jquery: 'jquery',
  },
};

Will generate something like below:

import * as __WEBPACK_EXTERNAL_MODULE_lodash__ from 'lodash';
const lodash = __WEBPACK_EXTERNAL_MODULE_jquery__;

var __webpack_modules__ = {
  jQuery: (module) => {
    module.exports = import('jQuery');
  },
};

// webpack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jQuery')
  );
  (0, lodash.attempt)(() => jq('.my-element').animate(/* ... */));
}

Note that the output bundle will have an import or import() statement.

When a module is not imported via import or import(), webpack will use the "module" externals type as a fallback. If you want to use a different kind of externals as a fallback, you can specify it with a function in the externals option. For example:

module.exports = {
  externalsType: "module-import",
  externals: [
    function (
      { request, dependencyType },
      callback
    ) {
      if (dependencyType === "commonjs") {
        return callback(null, `node-commonjs ${request}`);
      }
      callback();
    },
  ]

externalsType.node-commonjs

Specify the default type of externals as 'node-commonjs'. Webpack will import createRequire from 'module' to construct a require function for loading externals used in a module.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.export = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};

Will generate into something like

import { createRequire } from 'module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);

Note that there will be an import statement in the output bundle.

externalsType.promise

Specify the default type of externals as 'promise'. Webpack will read the external as a global variable (similar to 'var') and await for it.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'promise',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = await $;
jq('.my-element').animate(/* ... */);

externalsType.self

Specify the default type of externals as 'self'. Webpack will read the external as a global variable on the self object.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = self['$'];
jq('.my-element').animate(/* ... */);

externalsType.script

Specify the default type of externals as 'script'. Webpack will load the external as a script exposing predefined global variables with HTML <script> element. The <script> tag would be removed after the script has been loaded.

Syntax

module.exports = {
  externalsType: 'script',
  externals: {
    packageName: [
      'http://example.com/script.js',
      'global',
      'property',
      'property',
    ], // properties are optional
  },
};

You can also use the shortcut syntax if you're not going to specify any properties:

module.exports = {
  externalsType: 'script',
  externals: {
    packageName: 'global@http://example.com/script.js', // no properties here
  },
};

Note that output.publicPath won't be added to the provided URL.

Example

Let's load a lodash from CDN:

webpack.config.js

module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_'],
  },
};

Then use it in code:

import _ from 'lodash';
console.log(_.head([1, 2, 3]));

Here's how we specify properties for the above example:

module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: [
      'https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js',
      '_',
      'head',
    ],
  },
};

Both local variable head and global window._ will be exposed when you import lodash:

import head from 'lodash';
console.log(head([1, 2, 3])); // logs 1 here
console.log(window._.head(['a', 'b'])); // logs a here

externalsType.this

Specify the default type of externals as 'this'. Webpack will read the external as a global variable on the this object.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = this['$'];
jq('.my-element').animate(/* ... */);

externalsType.var

Specify the default type of externals as 'var'. Webpack will read the external as a global variable.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = $;
jq('.my-element').animate(/* ... */);

externalsType.window

Specify the default type of externals as 'window'. Webpack will read the external as a global variable on the window object.

Example

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

webpack.config.js

module.exports = {
  // ...
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = window['$'];
jq('.my-element').animate(/* ... */);

externalsPresets

object

Enable presets of externals for specific targets.

Option	Description	Input Type
electron	Treat common electron built-in modules in main and preload context like electron, ipc or shell as external and load them via require() when used.	boolean
electronMain	Treat electron built-in modules in the main context like app, ipc-main or shell as external and load them via require() when used.	boolean
electronPreload	Treat electron built-in modules in the preload context like web-frame, ipc-renderer or shell as external and load them via require() when used.	boolean
electronRenderer	Treat electron built-in modules in the renderer context like web-frame, ipc-renderer or shell as external and load them via require() when used.	boolean
node	Treat node.js built-in modules like fs, path or vm as external and load them via require() when used.	boolean
nwjs	Treat NW.js legacy nw.gui module as external and load it via require() when used.	boolean
web	Treat references to http(s)://... and std:... as external and load them via import when used. (Note that this changes execution order as externals are executed before any other code in the chunk).	boolean
webAsync	Treat references to http(s)://... and std:... as external and load them via async import() when used (Note that this external type is an async module, which has various effects on the execution).	boolean

Note that if you're going to output ES Modules with those node.js-related presets, webpack will set the default externalsType to node-commonjs which would use createRequire to construct a require function instead of using require().

Example

Using node preset will not bundle built-in modules and treats them as external and loads them via require() when used.

webpack.config.js

module.exports = {
  // ...
  externalsPresets: {
    node: true,
  },
};

Performance

These options allows you to control how webpack notifies you of assets and entry points that exceed a specific file limit. This feature was inspired by the idea of webpack Performance Budgets.

performance

object

Configure how performance hints are shown. For example if you have an asset that is over 250kb, webpack will emit a warning notifying you of this.

performance.assetFilter

function(assetFilename) => boolean

This property allows webpack to control what files are used to calculate performance hints. The default function is:

function assetFilter(assetFilename) {
  return !/\.map$/.test(assetFilename);
}

You can override this property by passing your own function in:

module.exports = {
  //...
  performance: {
    assetFilter: function (assetFilename) {
      return assetFilename.endsWith('.js');
    },
  },
};

The example above will only give you performance hints based on .js files.

performance.hints

string = 'warning': 'error' | 'warning' boolean: false

Turns hints on/off. In addition, tells webpack to throw either an error or a warning when hints are found.

Given an asset is created that is over 250kb:

module.exports = {
  //...
  performance: {
    hints: false,
  },
};

No hint warnings or errors are shown.

module.exports = {
  //...
  performance: {
    hints: 'warning',
  },
};

A warning will be displayed notifying you of a large asset. We recommend something like this for development environments.

module.exports = {
  //...
  performance: {
    hints: 'error',
  },
};

An error will be displayed notifying you of a large asset. We recommend using hints: "error" during production builds to help prevent deploying production bundles that are too large, impacting webpage performance.

performance.maxAssetSize

number = 250000

An asset is any emitted file from webpack. This option controls when webpack emits a performance hint based on individual asset size in bytes.

module.exports = {
  //...
  performance: {
    maxAssetSize: 100000,
  },
};

performance.maxEntrypointSize

number = 250000

An entry point represents all assets that would be utilized during initial load time for a specific entry. This option controls when webpack should emit performance hints based on the maximum entry point size in bytes.

module.exports = {
  //...
  performance: {
    maxEntrypointSize: 400000,
  },
};

Node

The following Node.js options configure whether to polyfill or mock certain Node.js globals.

This feature is provided by webpack's internal NodeStuffPlugin plugin.

node

false object

webpack.config.js

module.exports = {
  //...
  node: {
    global: false,
    __filename: false,
    __dirname: false,
  },
};

The node option may be set to false to completely turn off the NodeStuffPlugin plugin.

node.global

boolean 'warn'

See the Node.js documentation for the exact behavior of this object.

Options:

• true: Provide a polyfill.
• false: Provide nothing. Code that expects this object may crash with a ReferenceError.
• 'warn': Show a warning when using global.

node.__filename

boolean 'mock' | 'warn-mock' | 'node-module' | 'eval-only'

Options:

• true: The filename of the input file relative to the context option.
• false: Webpack won't touch your __filename code, which means you have the regular Node.js __filename behavior. The filename of the output file when run in a Node.js environment.
• 'mock': The fixed value '/index.js'.
• 'warn-mock': Use the fixed value of '/index.js' but show a warning.
• 'node-module': Replace __filename in CommonJS modules to fileURLToPath(import.meta.url) when output.module is enabled.
• 'eval-only'

node.__dirname

boolean 'mock' | 'warn-mock' | 'node-module' | 'eval-only'

Options:

• true: The dirname of the input file relative to the context option.
• false: Webpack won't touch your __dirname code, which means you have the regular Node.js __dirname behavior. The dirname of the output file when run in a Node.js environment.
• 'mock': The fixed value '/'.
• 'warn-mock': Use the fixed value of '/' but show a warning.
• 'node-module': Replace __dirname in CommonJS modules to fileURLToPath(import.meta.url + "/..") when output.module is enabled.
• 'eval-only'

Stats

object string

The stats option lets you precisely control what bundle information gets displayed. This can be a nice middle ground if you don't want to use quiet or noInfo because you want some bundle information, but not all of it.

module.exports = {
  //...
  stats: 'errors-only',
};

Stats Presets

Webpack comes with certain presets available for the stats output:

Preset	Alternative	Description
'errors-only'	none	Only output when errors happen
'errors-warnings'	none	Only output errors and warnings happen
'minimal'	none	Only output when errors or new compilation happen
'none'	false	Output nothing
'normal'	true	Standard output
'verbose'	none	Output everything
'detailed'	none	Output everything except chunkModules and chunkRootModules
'summary'	none	Output webpack version, warnings count and errors count

Stats Options

It is possible to specify which information you want to see in the stats output.

stats.all

A fallback value for stats options when an option is not defined. It has precedence over local webpack defaults.

module.exports = {
  //...
  stats: {
    all: undefined,
  },
};

stats.assets

boolean = true

Tells stats whether to show the asset information. Set stats.assets to false to hide it.

module.exports = {
  //...
  stats: {
    assets: false,
  },
};

stats.assetsSort

string = 'id'

Tells stats to sort the assets by a given field. All of the sorting fields are allowed to be used as values for stats.assetsSort. Use ! prefix in the value to reverse the sort order by a given field.

module.exports = {
  //...
  stats: {
    assetsSort: '!size',
  },
};

stats.assetsSpace

number = 15

Tells stats how many items of assets should be displayed (groups will be collapsed to fit this space).

module.exports = {
  //...
  stats: {
    assetsSpace: 15,
  },
};

stats.builtAt

boolean = true

Tells stats whether to add the build date and the build time information. Set stats.builtAt to false to hide it.

module.exports = {
  //...
  stats: {
    builtAt: false,
  },
};

stats.cached

Old version of stats.cachedModules.

stats.cachedAssets

boolean = true

Tells stats whether to add information about the cached assets. Setting stats.cachedAssets to false will tell stats to only show the emitted files (not the ones that were built).

module.exports = {
  //...
  stats: {
    cachedAssets: false,
  },
};

stats.cachedModules

boolean = true

Tells stats whether to add information about cached (not built) modules.

module.exports = {
  //...
  stats: {
    cachedModules: false,
  },
};

stats.children

boolean = true

Tells stats whether to add information about the children.

module.exports = {
  //...
  stats: {
    children: false,
  },
};

stats.chunkGroupAuxiliary

boolean = true

Display auxiliary assets in chunk groups.

module.exports = {
  //...
  stats: {
    chunkGroupAuxiliary: false,
  },
};

stats.chunkGroupChildren

boolean = true

Display children of the chunk groups (e.g. prefetched, preloaded chunks and assets).

module.exports = {
  //...
  stats: {
    chunkGroupChildren: false,
  },
};

stats.chunkGroupMaxAssets

number

Limit of assets displayed in chunk groups.

module.exports = {
  //...
  stats: {
    chunkGroupMaxAssets: 5,
  },
};

stats.chunkGroups

boolean = true

Tells stats whether to add information about the namedChunkGroups.

module.exports = {
  //...
  stats: {
    chunkGroups: false,
  },
};

stats.chunkModules

boolean = true

Tells stats whether to add information about the built modules to information about the chunk.

module.exports = {
  //...
  stats: {
    chunkModules: false,
  },
};

stats.chunkModulesSpace

number = 10

Tells stats how many items of chunk modules should be displayed (groups will be collapsed to fit this space).

module.exports = {
  //...
  stats: {
    chunkModulesSpace: 15,
  },
};

stats.chunkOrigins

boolean = true

Tells stats whether to add information about the origins of chunks and chunk merging.

module.exports = {
  //...
  stats: {
    chunkOrigins: false,
  },
};

stats.chunkRelations

boolean = false

Tells stats to display chunk parents, children and siblings.

module.exports = {
  //...
  stats: {
    chunkRelations: false,
  },
};

stats.chunks

boolean = true

Tells stats whether to add information about the chunk. Setting stats.chunks to false results in a less verbose output.

module.exports = {
  //...
  stats: {
    chunks: false,
  },
};

stats.chunksSort

string = 'id'

Tells stats to sort the chunks by a given field. All of the sorting fields are allowed to be used as values for stats.chunksSort. Use ! prefix in the value to reverse the sort order by a given field.

module.exports = {
  //...
  stats: {
    chunksSort: 'name',
  },
};

stats.colors

boolean = false { bold?: string, cyan?: string, green?: string, magenta?: string, red?: string, yellow?: string }

Tells stats whether to output in the different colors.

module.exports = {
  //...
  stats: {
    colors: true,
  },
};

It is also available as a CLI flag:

npx webpack --stats-colors

To disable:

npx webpack --no-stats-colors

You can specify your own terminal output colors using ANSI escape sequences

module.exports = {
  //...
  colors: {
    green: '\u001b[32m',
  },
};

stats.context

string

The stats base directory, an absolute path for shortening the request information.

const path = require('path');

module.exports = {
  //...
  stats: {
    context: path.resolve(__dirname, 'src/components'),
  },
};

By default, the value of context or the Node.js current working directory is used.

stats.dependentModules

boolean

Tells stats whether to show chunk modules that are dependencies of other modules of the chunk.

module.exports = {
  //...
  stats: {
    dependentModules: false,
  },
};

stats.depth

boolean = false

Tells stats whether to display the distance from the entry point for each module.

module.exports = {
  //...
  stats: {
    depth: true,
  },
};

stats.entrypoints

boolean = true "auto"

Tells stats whether to display the entry points with the corresponding bundles.

module.exports = {
  //...
  stats: {
    entrypoints: false,
  },
};

When stats.entrypoints is set to 'auto', webpack will decide automatically whether to display the entry points in the stats output.

stats.env

boolean = false

Tells stats whether to display the --env information.

module.exports = {
  //...
  stats: {
    env: true,
  },
};

stats.errorDetails

boolean "auto"

Tells stats whether to add the details to the errors. It defaults to 'auto' which will show error details when there're only 2 or less errors.

module.exports = {
  //...
  stats: {
    errorDetails: false,
  },
};

stats.errorStack

boolean = true

Tells stats whether to show stack trace of errors.

module.exports = {
  //...
  stats: {
    errorStack: false,
  },
};

stats.errors

boolean = true

Tells stats whether to display the errors.

module.exports = {
  //...
  stats: {
    errors: false,
  },
};

stats.errorsCount

boolean = true

Add errors count.

module.exports = {
  //...
  stats: {
    errorsCount: false,
  },
};

stats.errorsSpace

5.80.0+

number

Tells stats to limit the number of lines to allocate for displaying an error.

module.exports = {
  //...
  stats: {
    errorsSpace: 5,
  },
};

stats.exclude

See stats.excludeModules.

stats.excludeAssets

array = []: string | RegExp | function (assetName) => boolean string RegExp function (assetName) => boolean

Tells stats to exclude the matching assets information. This can be done with a string, a RegExp, a function that is getting the assets name as an argument and returns a boolean. stats.excludeAssets can be an array of any of the above.

module.exports = {
  //...
  stats: {
    excludeAssets: [
      'filter',
      /filter/,
      (assetName) => assetName.contains('moduleA'),
    ],
  },
};

stats.excludeModules

array = []: string | RegExp | function (assetName) => boolean string RegExp function (assetName) => boolean boolean: false

Tells stats to exclude the matching modules information. This can be done with a string, a RegExp, a function that is getting the module's source as an argument and returns a boolean. stats.excludeModules can be an array of any of the above. stats.excludeModules's configuration is merged with the stats.exclude's configuration value.

module.exports = {
  //...
  stats: {
    excludeModules: ['filter', /filter/, (moduleSource) => true],
  },
};

Setting stats.excludeModules to false will disable the exclude behaviour.

module.exports = {
  //...
  stats: {
    excludeModules: false,
  },
};

stats.groupAssetsByChunk

boolean

Tells stats whether to group assets by how their are related to chunks.

module.exports = {
  //...
  stats: {
    groupAssetsByChunk: false,
  },
};

stats.groupAssetsByEmitStatus

boolean

Tells stats whether to group assets by their status (emitted, compared for emit or cached).

module.exports = {
  //...
  stats: {
    groupAssetsByEmitStatus: false,
  },
};

stats.groupAssetsByExtension

boolean

Tells stats whether to group assets by their extension.

module.exports = {
  //...
  stats: {
    groupAssetsByExtension: false,
  },
};

stats.groupAssetsByInfo

boolean

Tells stats whether to group assets by their asset info (immutable, development, hotModuleReplacement, etc).

module.exports = {
  //...
  stats: {
    groupAssetsByInfo: false,
  },
};

stats.groupAssetsByPath

boolean

Tells stats whether to group assets by their asset path.

module.exports = {
  //...
  stats: {
    groupAssetsByPath: false,
  },
};

stats.groupModulesByAttributes

boolean

Tells stats whether to group modules by their attributes (errors, warnings, assets, optional, orphan, or dependent).

module.exports = {
  //...
  stats: {
    groupModulesByAttributes: false,
  },
};

stats.groupModulesByCacheStatus

boolean

Tells stats whether to group modules by their cache status (cached or built and cacheable).

module.exports = {
  //...
  stats: {
    groupModulesByCacheStatus: true,
  },
};

stats.groupModulesByExtension

boolean

Tells stats whether to group modules by their extension.

module.exports = {
  //...
  stats: {
    groupModulesByExtension: true,
  },
};

stats.groupModulesByLayer

boolean

Tells stats whether to group modules by their layer.

module.exports = {
  //...
  stats: {
    groupModulesByLayer: true,
  },
};

stats.groupModulesByPath

boolean

Tells stats whether to group modules by their path.

module.exports = {
  //...
  stats: {
    groupModulesByPath: true,
  },
};

stats.groupModulesByType

boolean

Tells stats whether to group modules by their type.

module.exports = {
  //...
  stats: {
    groupModulesByType: true,
  },
};

stats.groupReasonsByOrigin

boolean

5.46.0+

Group reasons by their origin module to avoid large set of reasons.

module.exports = {
  //...
  stats: {
    groupReasonsByOrigin: true,
  },
};

stats.hash

boolean = true

Tells stats whether to add information about the hash of the compilation.

module.exports = {
  //...
  stats: {
    hash: false,
  },
};

stats.ids

boolean = false

Tells stats to add IDs of modules and chunks.

module.exports = {
  //...
  stats: {
    ids: true,
  },
};

stats.logging

string = 'info': 'none' | 'error' | 'warn' | 'info' | 'log' | 'verbose' boolean

Tells stats whether to add logging output.

• 'none', false - disable logging
• 'error' - errors only
• 'warn' - errors and warnings only
• 'info' - errors, warnings, and info messages
• 'log', true - errors, warnings, info messages, log messages, groups, clears. Collapsed groups are displayed in a collapsed state.
• 'verbose' - log everything except debug and trace. Collapsed groups are displayed in expanded state.

module.exports = {
  //...
  stats: {
    logging: 'verbose',
  },
};

stats.loggingDebug

array = []: string | RegExp | function (name) => boolean string RegExp function (name) => boolean

Tells stats to include the debug information of the specified loggers such as Plugins or Loaders. When stats.logging is set to false, stats.loggingDebug option is ignored.

module.exports = {
  //...
  stats: {
    loggingDebug: [
      'MyPlugin',
      /MyPlugin/,
      /webpack/, // To get core logging
      (name) => name.contains('MyPlugin'),
    ],
  },
};

stats.loggingTrace

boolean = true

Enable stack traces in the logging output for errors, warnings and traces. Set stats.loggingTrace to hide the trace.

module.exports = {
  //...
  stats: {
    loggingTrace: false,
  },
};

stats.moduleAssets

boolean = true

Tells stats whether to add information about assets inside modules. Set stats.moduleAssets to false to hide it.

module.exports = {
  //...
  stats: {
    moduleAssets: false,
  },
};

stats.moduleTrace

boolean = true

Tells stats to show dependencies and the origin of warnings/errors. stats.moduleTrace is available since webpack 2.5.0.

module.exports = {
  //...
  stats: {
    moduleTrace: false,
  },
};

stats.modules

boolean = true

Tells stats whether to add information about the built modules.

module.exports = {
  //...
  stats: {
    modules: false,
  },
};

stats.modulesSort

string = 'id'

Tells stats to sort the modules by a given field. All of the sorting fields are allowed to be used as values for stats.modulesSort. Use ! prefix in the value to reverse the sort order by a given field.

module.exports = {
  //...
  stats: {
    modulesSort: 'size',
  },
};

stats.modulesSpace

number = 15

Tells stats how many items of modules should be displayed (groups will be collapsed to fit this space).

module.exports = {
  //...
  stats: {
    modulesSpace: 15,
  },
};

stats.nestedModules

boolean

Tells stats whether to add information about modules nested in other modules (like with module concatenation).

module.exports = {
  //...
  stats: {
    nestedModules: true,
  },
};

stats.nestedModulesSpace

number = 10

Tells stats how many items of nested modules should be displayed (groups will be collapsed to fit this space).

module.exports = {
  //...
  stats: {
    nestedModulesSpace: 15,
  },
};

stats.optimizationBailout

boolean

Tells stats to show the reasons why optimization bailed out for modules.

module.exports = {
  //...
  stats: {
    optimizationBailout: false,
  },
};

stats.orphanModules

boolean = false

Tells stats whether to hide orphan modules. A module is an orphan if it is not included in any chunk. Orphan modules are hidden by default in stats.

module.exports = {
  //...
  stats: {
    orphanModules: true,
  },
};

stats.outputPath

boolean = true

Tells stats to show the outputPath.

module.exports = {
  //...
  stats: {
    outputPath: false,
  },
};

stats.performance

boolean = true

Tells stats to show performance hint when the file size exceeds performance.maxAssetSize.

module.exports = {
  //...
  stats: {
    performance: false,
  },
};

stats.preset

string boolean: false

Sets the preset for the type of information that gets displayed. It is useful for extending stats behaviours.

module.exports = {
  //...
  stats: {
    preset: 'minimal',
  },
};

Setting value of stats.preset to false tells webpack to use 'none' stats preset.

stats.providedExports

boolean = false

Tells stats to show the exports of the modules.

module.exports = {
  //...
  stats: {
    providedExports: true,
  },
};

stats.publicPath

boolean = true

Tells stats to show the publicPath.

module.exports = {
  //...
  stats: {
    publicPath: false,
  },
};

stats.reasons

boolean = true

Tells stats to add information about the reasons of why modules are included.

module.exports = {
  //...
  stats: {
    reasons: false,
  },
};

stats.reasonsSpace

number

5.46.0+

Space to display reasons (groups will be collapsed to fit this space).

module.exports = {
  //...
  stats: {
    reasonsSpace: 1000,
  },
};

stats.relatedAssets

boolean = false

Tells stats whether to add information about assets that are related to other assets (like SourceMaps for assets).

module.exports = {
  //...
  stats: {
    relatedAssets: true,
  },
};

stats.runtimeModules

boolean = true

Tells stats whether to add information about runtime modules.

module.exports = {
  //...
  stats: {
    runtimeModules: false,
  },
};

stats.source

boolean = false

Tells stats to add the source code of modules.

module.exports = {
  //...
  stats: {
    source: true,
  },
};

stats.timings

boolean = true

Tells stats to add the timing information.

module.exports = {
  //...
  stats: {
    timings: false,
  },
};

stats.usedExports

boolean = false

Tells stats whether to show which exports of a module are used.

module.exports = {
  //...
  stats: {
    usedExports: true,
  },
};

stats.version

boolean = true

Tells stats to add information about the webpack version used.

module.exports = {
  //...
  stats: {
    version: false,
  },
};

stats.warnings

boolean = true

Tells stats to add warnings.

module.exports = {
  //...
  stats: {
    warnings: false,
  },
};

stats.warningsCount

boolean = true

Add warnings count.

module.exports = {
  //...
  stats: {
    warningsCount: false,
  },
};

stats.warningsFilter

array = []: string | RegExp | function (warning) => boolean string RegExp function (warning) => boolean

Tells stats to exclude the warnings that are matching given filters. This can be done with a string, a RegExp, a function that is getting a warning as an argument and returns a boolean. stats.warningsFilter can be an array of any of the above.

module.exports = {
  //...
  stats: {
    warningsFilter: ['filter', /filter/, (warning) => true],
  },
};

stats.warningsSpace

5.80.0+

number

Tells stats to limit the number of lines to allocate for displaying a warning.

module.exports = {
  //...
  stats: {
    warningsSpace: 5,
  },
};

Sorting fields

For assetsSort, chunksSort, and modulesSort there are several possible fields that you can sort items by:

• 'id' - the item's id,
• 'name' - the item's name that was assigned to it upon importing,
• 'size' - the size of item in bytes,
• 'chunks' - what chunks the item originates from (for example, if there are multiple subchunks for one chunk: the subchunks will be grouped according to their main chunk),
• 'errors' - number of errors in items,
• 'warnings' - number of warnings in items,
• 'failed' - whether the item has failed compilation,
• 'cacheable' - whether the item is cacheable,
• 'built' - whether the asset has been built,
• 'prefetched' - whether the asset will be prefetched,
• 'optional' - whether the asset is optional.
• 'identifier' - identifier of the item.
• 'index' - item's processing index.
• 'index2'
• 'profile'
• 'issuer' - an identifier of the issuer.
• 'issuerId' - an id of the issuer.
• 'issuerName' - a name of the issuer.
• 'issuerPath' - a full issuer object. There's no real need to sort by this field.

Extending stats behaviours

If you want to use one of the presets e.g. 'minimal' but still override some of the rules: specify the desired stats.preset and add the customized or additional rules afterwards.

webpack.config.js

module.exports = {
  //..
  stats: {
    preset: 'minimal',
    moduleTrace: true,
    errorDetails: true,
  },
};

Experiments

experiments

boolean: false

experiments option was introduced in webpack 5 to empower users with the ability to activate and try out experimental features.

Available options:

• asyncWebAssembly: Support the new WebAssembly according to the updated specification, it makes a WebAssembly module an async module. And it is enabled by default when experiments.futureDefaults is set to true.
• backCompat
• buildHttp
• cacheUnaffected
• css
• futureDefaults
• layers: Enable module and chunk layers.
• lazyCompilation
• outputModule
• syncWebAssembly: Support the old WebAssembly like in webpack 4.
• topLevelAwait

webpack.config.js

module.exports = {
  //...
  experiments: {
    asyncWebAssembly: true,
    buildHttp: true,
    layers: true,
    lazyCompilation: true,
    outputModule: true,
    syncWebAssembly: true,
    topLevelAwait: true,
  },
};

experiments.backCompat

Enable backward-compat layer with deprecation warnings for many webpack 4 APIs.

• Type: boolean

module.exports = {
  //...
  experiments: {
    backCompat: true,
  },
};

experiments.buildHttp

When enabled, webpack can build remote resources that begin with the http(s): protocol.

• Type:

  • (string | RegExp | ((uri: string) => boolean))[]

    A shortcut for experiments.buildHttp.allowedUris.

  • HttpUriOptions

    {
      allowedUris: (string|RegExp|(uri: string) => boolean)[],
      cacheLocation?: false | string,
      frozen?: boolean,
      lockfileLocation?: string,
      upgrade?: boolean
    }

• Available: 5.49.0+

• Example

  // webpack.config.js
  module.exports = {
    //...
    experiments: {
      buildHttp: true,
    },
  };

  // src/index.js
  import pMap1 from 'https://cdn.skypack.dev/p-map';
  // with `buildHttp` enabled, webpack will build pMap1 like a regular local module
  console.log(pMap1);

experiments.buildHttp.allowedUris

A list of allowed URIs.

• Type: (string|RegExp|(uri: string) => boolean)[]

• Example

  // webpack.config.js
  module.exports = {
    //...
    experiments: {
      buildHttp: {
        allowedUris: [
          'http://localhost:9990/',
          'https://raw.githubusercontent.com/',
        ],
      },
    },
  };

experiments.buildHttp.cacheLocation

Define the location for caching remote resources.

• Type

  • string
  • false

• Example

  // webpack.config.js
  module.exports = {
    //...
    experiments: {
      buildHttp: {
        cacheLocation: false,
      },
    },
  };

By default webpack would use <compiler-name.>webpack.lock.data/ for caching, but you can disable it by setting its value to false.

Note that you should commit files under experiments.buildHttp.cacheLocation into a version control system as no network requests will be made during the production build.

experiments.buildHttp.frozen

Freeze the remote resources and lockfile. Any modification to the lockfile or resource contents will result in an error.

• Type: boolean

experiments.buildHttp.lockfileLocation

Define the location to store the lockfile.

• Type: string

By default webpack would generate a <compiler-name.>webpack.lock file>. Make sure to commit it into a version control system. During the production build, webpack will build those modules beginning with http(s): protocol from the lockfile and caches under experiments.buildHttp.cacheLocation.

experiments.buildHttp.proxy

Specify the proxy server to use for fetching remote resources.

• Type: string

By default, Webpack would imply the proxy server to use for fetching remote resources from the http_proxy (case insensitive) environment variable. However, you can also specify one through the proxy option.

experiments.buildHttp.upgrade

Detect changes to remote resources and upgrade them automatically.

• Type: boolean

experiments.css

Enable native CSS support. Note that it's an experimental feature still under development and will be enabled by default in webpack v6, however you can track the progress on GitHub.

• Type: boolean

Experimental features:

• CSS Modules support: webpack will generate a unique name for each CSS class. Use the .module.css extension for CSS Modules.

• 5.87.0+ Style-specific fields resolution in package.json files: webpack will look for style field in package.json files and use that if it exists for imports inside CSS files.

  For example, if you add @import 'bootstrap'; to your CSS file, webpack will look for bootstrap in node_modules and use the style field in package.json from there. If style field is not found, webpack will use the main field instead to preserve backward compatibility.

• Content hash for CSS files: webpack will generate a content hash for CSS files and use it in the filename. This is useful for long-term caching.

• CSS extraction: webpack will extract CSS into a separate file. This functionality replaces the need for mini-css-extract-plugin and css-loader, as it provides native support.

• CSS imports: webpack will inline CSS imports into the generated CSS file.

• Hot Module Reload (HMR): webpack supports HMR for CSS files. This means that changes made to CSS files will be reflected in the browser without a full page reload.

experiments.cacheUnaffected

Enable additional in-memory caching of modules which are unchanged and reference only unchanged modules.

• Type: boolean

Defaults to the value of futureDefaults.

experiments.futureDefaults

Use defaults of the next major webpack and show warnings in any problematic places.

webpack.config.js

module.exports = {
  //...
  experiments: {
    futureDefaults: true,
  },
};

experiments.lazyCompilation

Compile entrypoints and dynamic imports only when they are in use. It can be used for either Web or Node.js.

• Type

  • boolean

  • object

    {
      // define a custom backend
      backend?: ((
        compiler: Compiler,
        callback: (err?: Error, api?: BackendApi) => void
      ) => void)
        | ((compiler: Compiler) => Promise<BackendApi>)
        | {
          /**
           * A custom client.
           */
          client?: string;
    
          /**
           * Specify where to listen to from the server.
           */
          listen?: number | ListenOptions | ((server: Server) => void);
    
          /**
           * Specify the protocol the client should use to connect to the server.
           */
          protocol?: "http" | "https";
    
          /**
           * Specify how to create the server handling the EventSource requests.
           */
          server?: ServerOptionsImport | ServerOptionsHttps | (() => Server);
        },
      entries?: boolean,
      imports?: boolean,
      test?: string | RegExp | ((module: Module) => boolean)
    }

    • backend: Customize the backend.
    • entries: Enable lazy compilation for entries.
    • imports 5.20.0+: Enable lazy compilation for dynamic imports.
    • test 5.20.0+: Specify which imported modules should be lazily compiled.

• Available: 5.17.0+

• Example 1:

  module.exports = {
    // …
    experiments: {
      lazyCompilation: true,
    },
  };

• Example 2:

  module.exports = {
    // …
    experiments: {
      lazyCompilation: {
        // disable lazy compilation for dynamic imports
        imports: false,
  
        // disable lazy compilation for entries
        entries: false,
  
        // do not lazily compile moduleB
        test: (module) => !/moduleB/.test(module.nameForCondition()),
      },
    },
  };

experiments.outputModule

boolean

Once enabled, webpack will output ECMAScript module syntax whenever possible. For instance, import() to load chunks, ESM exports to expose chunk data, among others.

module.exports = {
  experiments: {
    outputModule: true,
  },
};

experiments.topLevelAwait

boolean = true

The topLevelAwait option transforms a module into an async module when an await is used at the top level. Starting from webpack version 5.83.0, this feature is enabled by default. However, in versions prior to that, you can enable it by setting experiments.topLevelAwait to true.

module.exports = {
  experiments: {
    topLevelAwait: true,
  },
};

InfrastructureLogging

Options for infrastructure level logging.

infrastructureLogging.appendOnly

5.31.0+

boolean

Append lines to the output instead of updating existing output, useful for status messages. This option is used only when no custom console is provided.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    appendOnly: true,
    level: 'verbose',
  },
  plugins: [
    (compiler) => {
      const logger = compiler.getInfrastructureLogger('MyPlugin');
      logger.status('first output'); // this line won't be overridden with `appendOnly` enabled
      logger.status('second output');
    },
  ],
};

infrastructureLogging.colors

5.31.0+

boolean

Enable colorful output for infrastructure level logging. This option is used only when no custom console is provided.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    colors: true,
    level: 'verbose',
  },
  plugins: [
    (compiler) => {
      const logger = compiler.getInfrastructureLogger('MyPlugin');
      logger.log('this output will be colorful');
    },
  ],
};

infrastructureLogging.console

5.31.0+

Console

Customize the console used for infrastructure level logging.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    console: yourCustomConsole(),
  },
};

infrastructureLogging.debug

string boolean = false RegExp function(name) => boolean [string, RegExp, function(name) => boolean]

Enable debug information of specified loggers such as plugins or loaders. Similar to stats.loggingDebug option but for infrastructure. Defaults to false.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    level: 'info',
    debug: ['MyPlugin', /MyPlugin/, (name) => name.contains('MyPlugin')],
  },
};

infrastructureLogging.level

string = 'info' : 'none' | 'error' | 'warn' | 'info' | 'log' | 'verbose'

Enable infrastructure logging output. Similar to stats.logging option but for infrastructure. Defaults to 'info'.

Possible values:

• 'none' - disable logging
• 'error' - errors only
• 'warn' - errors and warnings only
• 'info' - errors, warnings, and info messages
• 'log' - errors, warnings, info messages, log messages, groups, clears. Collapsed groups are displayed in a collapsed state.
• 'verbose' - log everything except debug and trace. Collapsed groups are displayed in expanded state.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    level: 'info',
  },
};

infrastructureLogging.stream

5.31.0+

NodeJS.WritableStream = process.stderr

Stream used for logging output. Defaults to process.stderr. This option is used only when no custom console is provided.

webpack.config.js

module.exports = {
  //...
  infrastructureLogging: {
    stream: process.stderr,
  },
};

Other Options

These are the remaining configuration options supported by webpack.

amd

object boolean: false

Set the value of require.amd or define.amd. Setting amd to false will disable webpack's AMD support.

webpack.config.js

module.exports = {
  //...
  amd: {
    jQuery: true,
  },
};

Certain popular modules written for AMD, most notably jQuery versions 1.7.0 to 1.9.1, will only register as an AMD module if the loader indicates it has taken special allowances for multiple versions being included on a page.

The allowances were the ability to restrict registrations to a specific version or to support different sandboxes with different defined modules.

This option allows you to set the key your module looks for to a truthy value. As it happens, the AMD support in webpack ignores the defined name anyways.

bail

boolean = false

Fail out on the first error instead of tolerating it. By default webpack will log these errors in red in the terminal, as well as the browser console when using HMR, but continue bundling. To enable it:

webpack.config.js

module.exports = {
  //...
  bail: true,
};

This will force webpack to exit its bundling process.

dependencies

[string]

A list of name defining all sibling configurations it depends on. Dependent configurations need to be compiled first.

In watch mode dependencies will invalidate the compiler when:

1. the dependency has changed
2. a dependency is currently compiling or invalid

Remember that current configuration will not compile until its dependencies are done.

webpack.config.js

module.exports = [
  {
    name: 'client',
    target: 'web',
    // …
  },
  {
    name: 'server',
    target: 'node',
    dependencies: ['client'],
  },
];

ignoreWarnings

[RegExp, function (WebpackError, Compilation) => boolean, {module?: RegExp, file?: RegExp, message?: RegExp}]

Tells webpack to ignore specific warnings. This can be done with a RegExp, a custom function to select warnings based on the raw warning instance which is getting WebpackError and Compilation as arguments and returns a boolean, an object with the following properties:

• file : A RegExp to select the origin file for the warning.
• message : A RegExp to select the warning message.
• module : A RegExp to select the origin module for the warning.

ignoreWarnings must be an array of any or all of the above.

module.exports = {
  //...
  ignoreWarnings: [
    {
      module: /module2\.js\?[34]/, // A RegExp
    },
    {
      module: /[13]/,
      message: /homepage/,
    },
    /warning from compiler/,
    (warning) => true,
  ],
};

loader

object

Expose custom values into the loader context.

For example, you can define a new variable in the loader context:

webpack.config.js

module.exports = {
  // ...
  loader: {
    answer: 42,
  },
};

Then use this.answer to get its value in the loader:

custom-loader.js

module.exports = function (source) {
  // ...
  console.log(this.answer); // will log `42` here
  return source;
};

name

string

Name of the configuration. Used when loading multiple configurations.

webpack.config.js

module.exports = {
  //...
  name: 'admin-app',
};

parallelism

number = 100

Limit the number of parallel processed modules. Can be used to fine tune performance or to get more reliable profiling results.

profile

boolean

Capture a "profile" of the application, including statistics and hints, which can then be dissected using the Analyze tool. It will also log out a summary of module timings.

recordsInputPath

string

Specify the file from which to read the last set of records. This can be used to rename a records file. See the example below.

recordsOutputPath

string

Specify where the records should be written. The following example shows how you might use this option in combination with recordsInputPath to rename a records file:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  recordsInputPath: path.join(__dirname, 'records.json'),
  recordsOutputPath: path.join(__dirname, 'newRecords.json'),
};

recordsPath

string

Use this option to generate a JSON file containing webpack "records" – pieces of data used to store module identifiers across multiple builds. You can use this file to track how modules change between builds. To generate one, specify a location:

webpack.config.js

const path = require('path');

module.exports = {
  //...
  recordsPath: path.join(__dirname, 'records.json'),
};

Records are particularly useful if you have a complex setup that leverages Code Splitting. The data can be used to ensure the split bundles are achieving the caching behavior you need.

snapshot

object

snapshot options decide how the file system snapshots are created and invalidated.

webpack.config.js

const path = require('path');
module.exports = {
  // ...
  snapshot: {
    managedPaths: [path.resolve(__dirname, '../node_modules')],
    immutablePaths: [],
    unmanagedPaths: [],
    buildDependencies: {
      hash: true,
      timestamp: true,
    },
    module: {
      timestamp: true,
    },
    resolve: {
      timestamp: true,
    },
    resolveBuildDependencies: {
      hash: true,
      timestamp: true,
    },
  },
};

buildDependencies

object = { hash boolean = true, timestamp boolean = true }

Snapshots for build dependencies when using the persistent cache.

• hash: Compare content hashes to determine invalidation (more expensive than timestamp, but changes less often).
• timestamp: Compare timestamps to determine invalidation.

Both hash and timestamp are optional.

• { hash: true }: Good for CI caching with a fresh checkout which doesn't keep timestamps and uses hashes.
• { timestamp: true }: Good for local development caching.
• { timestamp: true, hash: true }: Good for both cases mentioned above. Timestamps are compared first, which is cheap because webpack doesn't need to read files to compute their hashes. Content hashes will be compared only when timestamps are the same, which leads to a small performance hit for the initial build.

immutablePaths

(RegExp | string)[]

An array of paths that are managed by a package manager and contain a version or a hash in their paths so that all files are immutable.

Make sure to wrap the path in a capture group if you use regular expressions.

managedPaths

(RegExp | string)[]

An array of paths that are managed by a package manager and can be trusted to not be modified otherwise.

Make sure you wrap the path in a capture group if you are using regular expressions so webpack can extract the path, for example, here's a RegExp webpack internally uses to match the node_modules directory:

/^(.+?[\\/]node_modules)[\\/]/

A common use case for managedPaths would be to exclude some folders from node_modules, e.g. you want webpack to know that files in the node_modules/@azure/msal-browser folder are expected to change, which can be done with a regular expression like the one below:

module.exports = {
  snapshot: {
    managedPaths: [
      /^(.+?[\\/]node_modules[\\/](?!(@azure[\\/]msal-browser))(@.+?[\\/])?.+?)[\\/]/,
    ],
  },
};

unmanagedPaths

5.90.0+

(RegExp | string)[]

An array of paths that are not managed by a package manager and the contents are subject to change.

Make sure to wrap the path in a capture group if you use regular expressions.

module

object = {hash boolean = true, timestamp boolean = true}

Snapshots for building modules.

• hash: Compare content hashes to determine invalidation (more expensive than timestamp, but changes less often).
• timestamp: Compare timestamps to determine invalidation.

resolve

object = {hash boolean = true, timestamp boolean = true}

Snapshots for resolving of requests.

• hash: Compare content hashes to determine invalidation (more expensive than timestamp, but changes less often).
• timestamp: Compare timestamps to determine invalidation.

resolveBuildDependencies

object = {hash boolean = true, timestamp boolean = true}

Snapshots for resolving of build dependencies when using the persistent cache.

• hash: Compare content hashes to determine invalidation (more expensive than timestamp, but changes less often).
• timestamp: Compare timestamps to determine invalidation.