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.
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"
}
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!
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.
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:
tsconfig.json
.tsconfig.json
and add settings for ts-node
.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"
}
}
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
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>
);
Besides exporting a single configuration object, there are a few more ways that cover other needs as well.
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:
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
}
})
]
+ };
};
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);
});
};
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',
},
];
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'],
},
];
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.
number
webpack.config.js
module.exports = [
{
//config-1
},
{
//config-2
},
];
module.exports.parallelism = 1;
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.
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).
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',
},
};
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.
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.
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.
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'],
},
};
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.
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,
},
},
};
Providing the mode
configuration option tells webpack to use its built-in optimizations accordingly.
string = 'production': 'none' | 'development' | 'production'
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
.
// webpack.development.config.js
module.exports = {
mode: 'development',
};
// webpack.production.config.js
module.exports = {
mode: 'production',
};
// 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;
};
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.
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.
boolean = true
Create async chunks that are loaded on demand.
webpack.config.js
module.exports = {
//...
output: {
//...
asyncChunks: true,
},
};
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',
},
},
};
boolean = true
Tells webpack to add charset="utf-8"
to the HTML <script>
tag.
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';
},
},
};
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',
},
};
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,
},
};
string = 'webpackChunkwebpack'
The global variable is used by webpack for loading chunks.
webpack.config.js
module.exports = {
//...
output: {
//...
chunkLoadingGlobal: 'myCustomFunc',
},
};
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',
},
};
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;
}
);
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,
},
};
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 credentialsstring
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.
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.
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.
string
function (info)
A fallback is used when the template string or function above yields duplicates.
See 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.
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
},
};
[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'],
},
};
[string]
List of library types enabled for use by entry points.
module.exports = {
//...
output: {
enabledLibraryTypes: ['module'],
},
};
[string]
List of wasm loading types enabled for use by entry points.
module.exports = {
//...
output: {
enabledWasmLoadingTypes: ['fetch'],
},
};
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,
},
},
};
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.
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;
};
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',
},
};
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.
number = 20
The prefix length of the hash digest to use.
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.
An optional salt to update the hash via Node.JS' hash.update
.
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',
},
};
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
.
string = '[runtime].[fullhash].hot-update.json'
function
Customize the main hot update filename. [fullhash]
and [runtime]
are available as placeholder.
boolean = true
Tells webpack to add IIFE wrapper around emitted code.
module.exports = {
//...
output: {
iife: true,
},
};
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,
},
};
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__',
},
};
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 a library exposing the exports of your entry point.
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
.
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',
},
};
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',
},
},
},
};
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*/);
module.exports = {
// …
output: {
library: {
name: 'MyLibrary',
},
},
};
Specify a name for the library.
Type:
string | string[] | {amd?: string, commonjs?: string, root?: string | string[]}
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.
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.
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();
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.
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');
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
.
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
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();
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();
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();
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.
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.
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.
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]
.
commonjs-module
is equivalent to commonjs2
. We may remove commonjs-module
in future versions.
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]
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.
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.
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',
},
},
};
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 () {
// ...
},
};
}
);
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.
Specify which export should be exposed as a library.
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;
Add a comment in the UMD wrapper.
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',
},
},
},
};
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);
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();
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
.
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.
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();
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.
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');
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_);
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
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();
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();
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();
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.
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.
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.
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.
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.
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',
},
};
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);
});
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.
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,
},
};
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.
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,
},
};
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__
.
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',
},
};
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.
string = ''
Change the prefix for each line in the output bundles.
webpack.config.js
module.exports = {
//...
output: {
sourcePrefix: '\t',
},
};
Handle error in module loading as per EcmaScript Modules spec at a performance cost.
boolean
module.exports = {
//...
output: {
strictModuleErrorHandling: true,
},
};
boolean = false
Tell webpack to remove a module from the module instance cache (require.cache
) if it throws an exception when it is require
d.
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 require
s of this module throw an exception:
// with strictModuleExceptionHandling = true
require('module'); // <- throws
require('module'); // <- also throws
true
string
object
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).
true
, webpack will use output.uniqueName
as the Trusted Types policy name.policyName
property.webpack.config.js
module.exports = {
//...
output: {
//...
trustedTypes: {
policyName: 'my-application#webpack',
},
},
};
string = 'stop': 'continue' | 'stop'
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',
},
},
};
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,
},
};
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:
webpack.config.js
module.exports = {
// ...
output: {
uniqueName: 'my-package-xyz',
},
};
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
:
'fetch'
if target
is set to 'web'
, 'webworker'
, 'electron-renderer'
or 'node-webkit'
.'async-node'
if target
is set to 'node'
, 'async-node'
, 'electron-main'
or 'electron-preload'
.module.exports = {
//...
output: {
wasmLoading: 'fetch',
},
};
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',
},
};
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,
},
};
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/',
},
};
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',
},
};
These options determine how the different types of modules within a project will be treated.
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
},
],
},
};
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…
},
},
};
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…
},
},
};
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.
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.
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');
Specify the global fetchPriority for dynamic import.
Type: 'low' | 'high' | 'auto' | false
Available: 5.87.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
dynamicImportFetchPriority: 'high',
},
},
},
};
Specifies global mode for dynamic import.
Type: 'eager' | 'weak' | 'lazy' | 'lazy-once'
Available: 5.73.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
dynamicImportMode: 'lazy',
},
},
},
};
Specifies global prefetch for dynamic import.
Type: number | boolean
Available: 5.73.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
dynamicImportPrefetch: false,
},
},
},
};
Specifies global preload for dynamic import.
Type: number | boolean
Available: 5.73.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
dynamicImportPreload: false,
},
},
},
};
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',
},
},
},
};
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',
},
},
},
};
Enable or disable evaluating import.meta
.
Type: boolean = true
Available: 5.68.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
importMeta: false,
},
},
},
};
Enable/disable evaluating import.meta.webpackContext
.
Type: boolean
Available: 5.70.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
importMetaContext: 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.
Type: 'strict' | 'non-strict'
Available: 5.93.0+
Example:
module.exports = {
module: {
parser: {
javascript: {
overrideStrict: 'non-strict',
},
},
},
};
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',
},
},
},
};
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" />
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),
},
};
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,
},
};
(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.
object
A Rule can be separated into three parts — Conditions, Results and nested Rules.
There are two input values for the conditions:
The resource: An absolute path to the file requested. It's already resolved according to the resolve
rules.
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 are used only when the Rule condition matches.
There are two output values of a Rule:
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 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:
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.
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',
},
],
},
};
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:
post, inline, normal, pre
. See Pitching Loader for details.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.
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.
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.
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.
Allows to filter/match by layer of the issuer.
webpack.config.js
module.exports = {
// ...
module: {
rules: [
{
issuerLayer: 'other-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
is a shortcut to Rule.use: [ { loader } ]
. See Rule.use
and UseEntry.loader
for details.
Rule.loaders
is an alias to Rule.use
. See Rule.use
for details.
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.
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
and Rule.query
are shortcuts to Rule.use: [ { options } ]
. See Rule.use
and UseEntry.options
for details.
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:
false
disables the parser.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.
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');
},
},
},
],
},
};
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:
'base64'
, module source will be encoded using Base64 algorithm. Setting encoding
to false will disable encoding.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);
},
},
},
],
},
};
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,
},
},
],
},
};
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]',
},
},
],
},
};
Customize publicPath
for specific Asset Modules.
string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
module.exports = {
//...
output: {
publicPath: 'static/',
},
module: {
rules: [
{
test: /\.png$/i,
type: 'asset/resource',
generator: {
publicPath: 'assets/',
},
},
],
},
};
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.
string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
module.exports = {
//...
output: {
publicPath: 'static/',
},
module: {
rules: [
{
test: /\.png$/i,
type: 'asset/resource',
generator: {
publicPath: 'https://cdn/assets/',
outputPath: 'cdn-assets/',
},
},
],
},
};
A Condition
matched with the resource. See details in Rule
conditions.
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',
},
],
},
};
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,
},
},
],
},
};
An array of Rules
that is also used when the Rule matches.
Match the used schema, e.g., data
, http
.
string | RegExp | ((value: string) => boolean) | RuleSetLogicalConditions | RuleSetCondition[]
webpack.config.js
module.exports = {
module: {
rules: [
{
scheme: 'data',
type: 'asset/resource',
},
],
},
};
bool
Indicate what parts of the module contain side effects. See Tree Shaking for details.
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.
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.
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',
},
],
},
};
[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 loadedrealResource
: Always the path to the module being loadedresource
: The path to the module being loaded, it is usually equal to realResource
except when the resource name is overwritten via !=!
in request stringThe 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.
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'.
boolean = true
When enabled, you should provide the file extension when import
ing 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
},
},
],
},
};
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" }
.
Conditions can be one of these:
{ 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/'),
],
},
],
},
};
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 loadedrealResource
: Always the path to the module being loadedresource
: The path to the module being loaded, it is usually equal to realResource
except when the resource name is overwritten via !=!
in request stringwebpack.config.js
module.exports = {
//...
module: {
rules: [
{
test: /\.svg$/,
type: 'asset',
use: (info) => ({
loader: 'svgo-loader',
options: {
plugins: [
{
cleanupIDs: { prefix: basename(info.resource) },
},
],
},
}),
},
],
},
};
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:
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 warningwrappedContextRegExp: /\\.\\*/
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.
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
},
};
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,
},
},
};
[string]: ['browser']
Specify a field, such as browser
, to be parsed according to this specification.
webpack.config.js
module.exports = {
//...
resolve: {
aliasFields: ['browser'],
},
};
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,
},
},
},
};
boolean
Enables caching of successfully resolved requests, allowing cache entries to be revalidated.
webpack.config.js
module.exports = {
//...
resolve: {
cache: true,
},
};
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;
},
},
};
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.
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'
[string] = ['package.json']
The JSON files to use for descriptions.
webpack.config.js
module.exports = {
//...
resolve: {
descriptionFiles: ['package.json'],
},
};
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,
},
};
[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'],
},
};
object
An object which maps extension to extension aliases.
webpack.config.js
module.exports = {
//...
resolve: {
extensionAlias: {
'.js': ['.ts', '.js'],
'.mjs': ['.mts', '.mjs'],
},
},
};
[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', '...'],
},
};
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'),
},
},
};
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,
},
};
[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'],
},
};
[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.
[string] = ['index']
The filename to be used while resolving directories.
webpack.config.js
module.exports = {
//...
resolve: {
mainFiles: ['index'],
},
};
[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'],
},
};
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()],
},
};
boolean
Prefer absolute paths to resolve.roots
when resolving.
webpack.config.js
module.exports = {
//...
resolve: {
preferAbsolute: true,
},
};
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);
[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)$/],
},
};
[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],
},
};
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,
},
};
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,
},
};
boolean
Use synchronous filesystem calls for the resolver.
webpack.config.js
module.exports = {
//...
resolve: {
useSyncFileSystemCalls: true,
},
};
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'],
},
};
Webpack runs optimizations for you depending on the chosen mode
, still all optimizations are available for manual configuration and overrides.
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,
},
};
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
:
optimization.chunkIds
is set to 'named'
, while in production it is set to 'deterministic'
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,
}),
],
};
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,
},
};
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,
},
};
boolean = false
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,
},
};
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,
},
};
boolean = true
optimization.innerGraph
tells webpack whether to conduct inner graph analysis for unused exports.
webpack.config.js
module.exports = {
//...
optimization: {
innerGraph: false,
},
};
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,
},
};
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,
},
};
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,
},
};
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,
},
};
[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.
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,
}),
],
};
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:
process.env.NODE_ENV
to.process.env.NODE_ENV
.webpack.config.js
module.exports = {
//...
optimization: {
nodeEnv: 'production',
},
};
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,
},
};
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,
},
};
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,
},
};
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,
},
};
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,
},
};
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}`,
},
},
};
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.
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.
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',
},
};
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.
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(),
],
};
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.
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.
You can invoke webpack-dev-server via CLI by:
npx webpack serve
A list of CLI options for serve
is available here
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
.
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(),
},
};
'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
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',
},
},
};
'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
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;
},
},
},
},
};
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
boolean = true
number
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
'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'),
},
};
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',
},
},
},
};
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
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,
},
},
};
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'] };
},
},
};
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.
'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 ::
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
Specifying local-ipv4
as host will try to resolve the host option as your local IPv4
address.
npx webpack serve --host local-ipv4
Specifying local-ipv6 as host will try to resolve the host option as your local IPv6 address.
npx webpack serve --host local-ipv6
'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
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'),
},
};
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
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);
},
},
};
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'],
},
},
},
};
'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
[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.
null
or undefined
to continue processing the request with proxy.false
to produce a 404 error for 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,
},
],
},
};
'http' | 'https' | 'spdy'
string
object
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,
},
},
},
};
boolean = true
Allows to close dev server and exit the process on SIGINT
and SIGTERM
signals.
webpack.config.js
module.exports = {
//...
devServer: {
setupExitSignals: true,
},
};
function (middlewares, devServer)
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;
},
},
};
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
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'),
},
],
},
};
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,
},
},
},
};
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',
},
],
},
};
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
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,
},
},
},
};
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,
},
},
},
};
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'),
},
};
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.
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.
boolean
false
in production mode and true
in development mode.webpack.config.js
module.exports = {
cache: {
type: 'filesystem',
allowCollectingMemory: true,
},
};
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
},
},
};
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'),
},
};
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 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.
boolean
webpack.config.js
module.exports = {
//...
cache: {
type: 'memory',
cacheUnaffected: true,
},
};
false | 'gzip' | 'brotli'
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',
},
};
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',
},
};
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,
},
};
number = 1000
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,
},
};
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,
},
};
[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).
number = 5184000000
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,
},
};
number
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,
},
};
number
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 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.
boolean
webpack.config.js
module.exports = {
//...
cache: {
type: 'filesystem',
memoryCacheUnaffected: true,
},
};
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',
},
};
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,
},
};
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,
},
};
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 itemscache.store
option is only available when cache.type
is set to 'filesystem'
.
webpack.config.js
module.exports = {
//...
cache: {
type: 'filesystem',
store: 'pack',
},
};
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',
},
};
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',
},
};
Filesystem cache allows to share cache between builds in CI. To setup cache:
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/
- 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
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.
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.
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.
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.
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.
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.
string | string[]
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',
},
};
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',
},
};
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',
},
};
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',
},
};
Webpack can compile for multiple environments or targets. To understand what a target
is in detail, read through the targets concept page.
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.
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).
If a project has a browserslist config, then webpack will use it for:
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 configbrowserslist:last 2 versions
- use an explicit browserslist query (config will be ignored)browserslist:/path/to/config
- explicitly specify browserslist configbrowserslist:/path/to/config:modern
- explicitly specify browserslist config and an environmentWhen 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.
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.
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.
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,
};
object
A set of options used to customize watch mode:
webpack.config.js
module.exports = {
//...
watchOptions: {
aggregateTimeout: 200,
poll: 1000,
},
};
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,
},
};
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
.
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
},
};
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,
},
};
Stop watching when stdin stream has ended.
Type: boolean
Example:
module.exports = {
//...
watchOptions: {
stdin: true,
},
};
If you are experiencing any issues, please see the following notes. There are a variety of reasons why webpack might miss a file change.
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
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
.
On macOS, folders can get corrupted in certain scenarios. See this article.
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')
.
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
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)
.
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.
string
object
function
RegExp
[string, object, function, RegExp]
Prevent bundling of certain import
ed 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.
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',
},
};
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'],
},
};
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 ({ 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',
});
},
],
};
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.
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.
function
object
Specify externals by layer.
webpack.config.js
module.exports = {
externals: {
byLayer: {
layer: {
external1: 'var 43',
},
},
},
};
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',
};
Specify the default type of externals as 'commonjs'
. Webpack will generate code like const X = require('...')
for externals used in a module.
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.
Specify the default type of externals as 'global'
. Webpack will read the external as a global variable on the globalObject
.
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(/* ... */);
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.
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.
Specify the default type of externals as 'import'
. Webpack will generate code like import('...')
for externals used in a module.
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.
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.
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();
},
]
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.
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.
This is useful when dependencies rely on Node.js built-in modules or require a CommonJS-style require
function to preserve prototypes, which is necessary for functions like util.inherits
. Refer to this issue for more details.
For code that relies on prototype structures, like:
function ChunkStream() {
Stream.call(this);
}
util.inherits(ChunkStream, Stream);
You can use node-commonjs
to ensure that the prototype chain is preserved:
const { builtinModules } = require('module');
module.exports = {
experiments: { outputModule: true },
externalsType: 'node-commonjs',
externals: ({ request }, callback) => {
if (/^node:/.test(request) || builtinModules.includes(request)) {
return callback(null, 'node-commonjs ' + request);
}
callback();
},
};
This produces something like:
import { createRequire as __WEBPACK_EXTERNAL_createRequire } from "node:module";
// ...
/***/ 2613:
/***/ ((module) => {
module.exports = __WEBPACK_EXTERNAL_createRequire(import.meta.url)("stream");
/***/ }),
This setup keeps the prototype structure intact, resolving issues with Node.js built-ins.
Specify the default type of externals as 'promise'
. Webpack will read the external as a global variable (similar to 'var'
) and await
for it.
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(/* ... */);
Specify the default type of externals as 'self'
. Webpack will read the external as a global variable on the self
object.
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(/* ... */);
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.
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.
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
Specify the default type of externals as 'this'
. Webpack will read the external as a global variable on the this
object.
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(/* ... */);
Specify the default type of externals as 'var'
. Webpack will read the external as a global variable.
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(/* ... */);
Specify the default type of externals as 'window'
. Webpack will read the external as a global variable on the window
object.
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(/* ... */);
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,
},
};
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.
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.
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.
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,
},
};
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,
},
};
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.
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.
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
.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'
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'
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',
};
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 |
It is possible to specify which information you want to see in the stats output.
A fallback value for stats options when an option is not defined. It has precedence over local webpack defaults.
module.exports = {
//...
stats: {
all: undefined,
},
};
boolean = true
Tells stats
whether to show the asset information. Set stats.assets
to false
to hide it.
module.exports = {
//...
stats: {
assets: false,
},
};
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',
},
};
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,
},
};
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,
},
};
Old version of stats.cachedModules
.
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,
},
};
boolean = true
Tells stats
whether to add information about cached (not built) modules.
module.exports = {
//...
stats: {
cachedModules: false,
},
};
boolean = true
Tells stats
whether to add information about the children.
module.exports = {
//...
stats: {
children: false,
},
};
boolean = true
Display auxiliary assets in chunk groups.
module.exports = {
//...
stats: {
chunkGroupAuxiliary: false,
},
};
boolean = true
Display children of the chunk groups (e.g. prefetched, preloaded chunks and assets).
module.exports = {
//...
stats: {
chunkGroupChildren: false,
},
};
number
Limit of assets displayed in chunk groups.
module.exports = {
//...
stats: {
chunkGroupMaxAssets: 5,
},
};
boolean = true
Tells stats
whether to add information about the namedChunkGroups
.
module.exports = {
//...
stats: {
chunkGroups: false,
},
};
boolean = true
Tells stats
whether to add information about the built modules to information about the chunk.
module.exports = {
//...
stats: {
chunkModules: false,
},
};
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,
},
};
boolean = true
Tells stats
whether to add information about the origins of chunks and chunk merging.
module.exports = {
//...
stats: {
chunkOrigins: false,
},
};
boolean = false
Tells stats
to display chunk parents, children and siblings.
module.exports = {
//...
stats: {
chunkRelations: false,
},
};
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,
},
};
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',
},
};
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',
},
};
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.
boolean
Tells stats
whether to show chunk modules that are dependencies of other modules of the chunk.
module.exports = {
//...
stats: {
dependentModules: false,
},
};
boolean = false
Tells stats
whether to display the distance from the entry point for each module.
module.exports = {
//...
stats: {
depth: true,
},
};
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.
boolean = false
Tells stats
whether to display the --env
information.
module.exports = {
//...
stats: {
env: true,
},
};
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,
},
};
boolean = true
Tells stats
whether to show stack trace of errors.
module.exports = {
//...
stats: {
errorStack: false,
},
};
boolean = true
Tells stats
whether to display the errors.
module.exports = {
//...
stats: {
errors: false,
},
};
boolean = true
Add errors count.
module.exports = {
//...
stats: {
errorsCount: false,
},
};
number
Tells stats
to limit the number of lines to allocate for displaying an error.
module.exports = {
//...
stats: {
errorsSpace: 5,
},
};
See stats.excludeModules
.
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'),
],
},
};
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,
},
};
boolean
Tells stats
whether to group assets by how their are related to chunks.
module.exports = {
//...
stats: {
groupAssetsByChunk: false,
},
};
boolean
Tells stats
whether to group assets by their status (emitted, compared for emit or cached).
module.exports = {
//...
stats: {
groupAssetsByEmitStatus: false,
},
};
boolean
Tells stats
whether to group assets by their extension.
module.exports = {
//...
stats: {
groupAssetsByExtension: false,
},
};
boolean
Tells stats
whether to group assets by their asset info (immutable, development, hotModuleReplacement, etc).
module.exports = {
//...
stats: {
groupAssetsByInfo: false,
},
};
boolean
Tells stats
whether to group assets by their asset path.
module.exports = {
//...
stats: {
groupAssetsByPath: false,
},
};
boolean
Tells stats
whether to group modules by their attributes (errors, warnings, assets, optional, orphan, or dependent).
module.exports = {
//...
stats: {
groupModulesByAttributes: false,
},
};
boolean
Tells stats
whether to group modules by their cache status (cached or built and cacheable).
module.exports = {
//...
stats: {
groupModulesByCacheStatus: true,
},
};
boolean
Tells stats
whether to group modules by their extension.
module.exports = {
//...
stats: {
groupModulesByExtension: true,
},
};
boolean
Tells stats
whether to group modules by their layer.
module.exports = {
//...
stats: {
groupModulesByLayer: true,
},
};
boolean
Tells stats
whether to group modules by their path.
module.exports = {
//...
stats: {
groupModulesByPath: true,
},
};
boolean
Tells stats
whether to group modules by their type.
module.exports = {
//...
stats: {
groupModulesByType: true,
},
};
boolean
Group reasons
by their origin module to avoid large set of reasons.
module.exports = {
//...
stats: {
groupReasonsByOrigin: true,
},
};
boolean = true
Tells stats
whether to add information about the hash of the compilation.
module.exports = {
//...
stats: {
hash: false,
},
};
boolean = false
Tells stats
to add IDs of modules and chunks.
module.exports = {
//...
stats: {
ids: true,
},
};
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',
},
};
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'),
],
},
};
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,
},
};
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,
},
};
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,
},
};
boolean = true
Tells stats
whether to add information about the built modules.
module.exports = {
//...
stats: {
modules: false,
},
};
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',
},
};
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,
},
};
boolean
Tells stats
whether to add information about modules nested in other modules (like with module concatenation).
module.exports = {
//...
stats: {
nestedModules: true,
},
};
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,
},
};
boolean
Tells stats
to show the reasons why optimization bailed out for modules.
module.exports = {
//...
stats: {
optimizationBailout: false,
},
};
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,
},
};
boolean = true
Tells stats
to show the outputPath
.
module.exports = {
//...
stats: {
outputPath: false,
},
};
boolean = true
Tells stats
to show performance hint when the file size exceeds performance.maxAssetSize
.
module.exports = {
//...
stats: {
performance: false,
},
};
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.
boolean = false
Tells stats
to show the exports of the modules.
module.exports = {
//...
stats: {
providedExports: true,
},
};
boolean = true
Tells stats
to show the publicPath
.
module.exports = {
//...
stats: {
publicPath: false,
},
};
boolean = true
Tells stats
to add information about the reasons of why modules are included.
module.exports = {
//...
stats: {
reasons: false,
},
};
number
Space to display reasons
(groups will be collapsed to fit this space).
module.exports = {
//...
stats: {
reasonsSpace: 1000,
},
};
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,
},
};
boolean = true
Tells stats
whether to add information about runtime modules.
module.exports = {
//...
stats: {
runtimeModules: false,
},
};
boolean = false
Tells stats
to add the source code of modules.
module.exports = {
//...
stats: {
source: true,
},
};
boolean = true
Tells stats
to add the timing information.
module.exports = {
//...
stats: {
timings: false,
},
};
boolean = false
Tells stats
whether to show which exports of a module are used.
module.exports = {
//...
stats: {
usedExports: true,
},
};
boolean = true
Tells stats
to add information about the webpack version used.
module.exports = {
//...
stats: {
version: false,
},
};
boolean = true
Tells stats
to add warnings.
module.exports = {
//...
stats: {
warnings: false,
},
};
boolean = true
Add warnings count.
module.exports = {
//...
stats: {
warningsCount: false,
},
};
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],
},
};
number
Tells stats
to limit the number of lines to allocate for displaying a warning.
module.exports = {
//...
stats: {
warningsSpace: 5,
},
};
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.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,
},
};
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,
},
};
Enable backward-compat layer with deprecation warnings for many webpack 4 APIs.
boolean
module.exports = {
//...
experiments: {
backCompat: true,
},
};
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);
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/',
],
},
},
};
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.
Freeze the remote resources and lockfile. Any modification to the lockfile or resource contents will result in an error.
boolean
Define the location to store the lockfile.
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
.
Specify the proxy server to use for fetching remote resources.
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.
Detect changes to remote resources and upgrade them automatically.
boolean
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.
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.
Enable additional in-memory caching of modules which are unchanged and reference only unchanged modules.
boolean
Defaults to the value of futureDefaults
.
Use defaults of the next major webpack and show warnings in any problematic places.
webpack.config.js
module.exports = {
//...
experiments: {
futureDefaults: true,
},
};
Compile entrypoints and dynamic import
s 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()),
},
},
};
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,
},
};
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,
},
};
Options for infrastructure level logging.
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');
},
],
};
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');
},
],
};
Console
Customize the console used for infrastructure level logging.
webpack.config.js
module.exports = {
//...
infrastructureLogging: {
console: yourCustomConsole(),
},
};
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')],
},
};
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',
},
};
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,
},
};
These are the remaining configuration options supported by webpack.
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.
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.
[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:
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'],
},
];
[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,
],
};
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;
};
string
Name of the configuration. Used when loading multiple configurations.
webpack.config.js
module.exports = {
//...
name: 'admin-app',
};
number = 100
Limit the number of parallel processed modules. Can be used to fine tune performance or to get more reliable profiling results.
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.
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.
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'),
};
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.
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,
},
},
};
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.(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.
(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))(@.+?[\\/])?.+?)[\\/]/,
],
},
};
(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.
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.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.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.