webpack is fed a configuration object. Depending on your usage of webpack there are two ways to pass this configuration object:
If you use the CLI it will read a file webpack.config.js (or the file passed by the --config option). This file should export the configuration object:
module.exports = {
// configuration
};
If you use the node.js API you need to pass the configuration object as parameter:
webpack({
// configuration
}, callback);
In both cases you can also use an array of configurations, which are processed in parallel. They share filesystem cache and watchers so this is more efficient than calling webpack multiple times.
Hint: Keep in mind that you don’t need to write pure JSON into the configuration. Use any JavaScript you want. It’s just a node.js module…
Very simple configuration object example:
{
context: __dirname + "/app",
entry: "./entry",
output: {
path: __dirname + "/dist",
filename: "bundle.js"
}
}
contextThe base directory (absolute path!) for resolving the entry option. If output.pathinfo is set, the included pathinfo is shortened to this directory.
Default:
process.cwd()
entryThe entry point for the bundle.
If you pass a string: The string is resolved to a module which is loaded upon startup.
If you pass an array: All modules are loaded upon startup. The last one is exported.
entry: ["./entry1", "./entry2"]
If you pass an object: Multiple entry bundles are created. The key is the chunk name. The value can be a string or an array.
{
entry: {
page1: "./page1",
page2: ["./entry1", "./entry2"]
},
output: {
// Make sure to use [name] or [id] in output.filename
// when using multiple entry points
filename: "[name].bundle.js",
chunkFilename: "[id].bundle.js"
}
}
NOTE: It is not possible to configure other options specific to entry points. If you need entry point specific configuration you need to use multiple configurations.
outputOptions affecting the output of the compilation. output options tell Webpack how to write the compiled files to disk. Note, that while there can be multiple entry points, only one output configuration is specified.
If you use any hashing ([hash] or [chunkhash]), make sure to have a consistent ordering of modules. Use the OccurrenceOrderPlugin or recordsPath.
output.filenameSpecifies the name of each output file on disk. You must not specify an absolute path here! The output.path option determines the location on disk the files are written. filename is used solely for naming the individual files.
single entry
{
entry: './src/app.js',
output: {
filename: 'bundle.js',
path: __dirname + '/build'
}
}
// writes to disk: ./build/bundle.js
multiple entries
If your configuration creates more than a single “chunk” (as with multiple entry points or when using plugins like CommonsChunkPlugin), you should use substitutions to ensure that each file has a unique name.
[name] is replaced by the name of the chunk.
[hash] is replaced by the hash of the compilation.
[chunkhash] is replaced by the hash of the chunk.
{
entry: {
app: './src/app.js',
search: './src/search.js'
},
output: {
filename: '[name].js',
path: __dirname + '/build'
}
}
// writes to disk: ./build/app.js, ./build/search.js
output.pathThe output directory as an absolute path (required).
[hash] is replaced by the hash of the compilation.
output.publicPathThe publicPath specifies the public URL address of the output files when referenced in a browser. For loaders that embed <script> or <link> tags or reference assets like images, publicPath is used as the href or url() to the file when it’s different than their location on disk (as specified by path). This can be helpful when you want to host some or all output files on a different domain or on a CDN. The Webpack Dev Server also uses this to determine the path where the output files are expected to be served from. As with path you can use the [hash] substitution for a better caching profile.
config.js
output: {
path: "/home/proj/public/assets",
publicPath: "/assets/"
}
index.html
<head> <link href="/assets/spinner.gif"/> </head>
And a more complicated example of using a CDN and hashes for assets.
config.js
output: {
path: "/home/proj/cdn/assets/[hash]",
publicPath: "http://cdn.example.com/assets/[hash]/"
}
Note: In cases when the eventual publicPath of output files isn’t known at compile time, it can be left blank and set dynamically at runtime in the entry point file. If you don’t know the publicPath while compiling, you can omit it and set __webpack_public_path__ on your entry point.
__webpack_public_path__ = myRuntimePublicPath // rest of your application entry
output.chunkFilenameThe filename of non-entry chunks as a relative path inside the output.path directory.
[id] is replaced by the id of the chunk.
[name] is replaced by the name of the chunk (or with the id when the chunk has no name).
[hash] is replaced by the hash of the compilation.
[chunkhash] is replaced by the hash of the chunk.
output.sourceMapFilenameThe filename of the SourceMaps for the JavaScript files. They are inside the output.path directory.
[file] is replaced by the filename of the JavaScript file.
[id] is replaced by the id of the chunk.
[hash] is replaced by the hash of the compilation.
Default:
"[file].map"
output.devtoolModuleFilenameTemplateFilename template string of function for the sources array in a generated SourceMap.
[resource] is replaced by the path used by Webpack to resolve the file, including the query params to the rightmost loader (if any).
[resource-path] is the same as [resource] but without the loader query params.
[loaders] is the list of loaders and params up to the name of the rightmost loader (only explicit loaders).
[all-loaders] is the list of loaders and params up to the name of the rightmost loader (including automatic loaders).
[id] is replaced by the id of the module.
[hash] is replaced by the hash of the module identifier.
[absolute-resource-path] is replaced with the absolute filename.
Default (devtool=
[inline-]source-map):"webpack:///[resource-path]"
Default (devtool=eval):"webpack:///[resource-path]?[loaders]"
Default (devtool=eval-source-map):"webpack:///[resource-path]?[hash]"
Can also be defined as a function instead of a string template. The function will accept an info object parameter which exposes the following properties:
output.devtoolFallbackModuleFilenameTemplateSimilar to output.devtoolModuleFilenameTemplate but used in the case of duplicate module identifiers.
Default:
"webpack:///[resourcePath]?[hash]"
output.devtoolLineToLineEnable line-to-line mapped mode for all/specified modules. Line-to-line mapped mode uses a simple SourceMap where each line of the generated source is mapped to the same line of the original source. It’s a performance optimization. Only use it if your performance needs to be better and you are sure that input lines match which generated lines.
true enables it for all modules (not recommended)
An object {test, include, exclude} similar to module.loaders enables it for specific files.
Default: disabled
output.hotUpdateChunkFilenameThe filename of the Hot Update Chunks. They are inside the output.path directory.
[id] is replaced by the id of the chunk.
[hash] is replaced by the hash of the compilation. (The last hash stored in the records)
Default:
"[id].[hash].hot-update.js"
output.hotUpdateMainFilenameThe filename of the Hot Update Main File. It is inside the output.path directory.
[hash] is replaced by the hash of the compilation. (The last hash stored in the records)
Default:
"[hash].hot-update.json"
output.jsonpFunctionThe JSONP function used by webpack for async loading of chunks.
A shorter function may reduce the filesize a bit. Use a different identifier when having multiple webpack instances on a single page.
Default:
"webpackJsonp"
output.hotUpdateFunctionThe JSONP function used by webpack for async loading of hot update chunks.
Default:
"webpackHotUpdate"
output.pathinfoInclude comments with information about the modules.
require(/* ./test */23)
Do not use this in production.
Default:
false
output.libraryIf set, export the bundle as library. output.library is the name.
Use this if you are writing a library and want to publish it as single file.
output.libraryTargetWhich format to export the library:
"var" - Export by setting a variable: var Library = xxx (default)
"this" - Export by setting a property of this: this["Library"] = xxx
"commonjs" - Export by setting a property of exports: exports["Library"] = xxx
"commonjs2" - Export by setting module.exports: module.exports = xxx
"amd" - Export to AMD (optionally named - set the name via the library option)
"umd" - Export to AMD, CommonJS2 or as property in root
Default:
"var"
If output.library is not set, but output.libraryTarget is set to a value other than var, every property of the exported object is copied (Except amd, commonjs2 and umd).
output.umdNamedDefineIf output.libraryTarget is set to umd and output.library is set, setting this to true will name the AMD module.
output.sourcePrefixPrefixes every line of the source in the bundle with this string.
Default:
"\t"
output.crossOriginLoadingThis option enables cross-origin loading of chunks.
Possible values are:
false - Disable cross-origin loading.
"anonymous" - Cross-origin loading is enabled. When using anonymous no credentials will be sent with the request.
"use-credentials" - Cross-origin loading is enabled and credentials will be send with the request.
For more information on cross-origin loading see MDN
Default:
false
moduleOptions affecting the normal modules (NormalModuleFactory)
module.loadersAn array of automatically applied loaders.
Each item can have these properties:
test: A condition that must be metexclude: A condition that must not be metinclude: An array of paths or files where the imported files will be transformed by the loaderloader: A string of “!” separated loadersloaders: An array of loaders as stringA condition may be a RegExp (tested against absolute path), a string containing the absolute path, a function(absPath): bool, or an array of one of these combined with “and”.
See more: loaders
IMPORTANT: The loaders here are resolved relative to the resource which they are applied to. This means they are not resolved relative to the configuration file. If you have loaders installed from npm and your node_modules folder is not in a parent folder of all source files, webpack cannot find the loader. You need to add the node_modules folder as an absolute path to the resolveLoader.root option. (resolveLoader: { root: path.join(__dirname, "node_modules") })
Example:
module: {
loaders: [
{
// "test" is commonly used to match the file extension
test: /\.jsx$/,
// "include" is commonly used to match the directories
include: [
path.resolve(__dirname, "app/src"),
path.resolve(__dirname, "app/test")
],
// "exclude" should be used to exclude exceptions
// try to prefer "include" when possible
// the "loader"
loader: "babel-loader" // or "babel" because webpack adds the '-loader' automatically
}
]
}
module.preLoaders, module.postLoaders
Syntax like module.loaders.
An array of applied pre and post loaders.
module.noParseDon’t parse files matching a RegExp or an array of RegExps.
It’s matched against the full resolved request.
This can boost the performance when ignoring big libraries.
The files are expected to have no call to require, define, or similar. They are allowed to use exports and module.exports.
module.xxxContextXxx
There are multiple options to configure the defaults for an automatically created context. We differentiate three types of automatically created contexts:
exprContext: An expression as a dependency (i. e. require(expr))wrappedContext: An expression plus pre- and/or suffixed string (i. e. require("./templates/" + expr))unknownContext: Any other unparsable usage of require (i. e. require)Four options are possible for automatically created contexts:
request: The request for context.recursive: Subdirectories should be traversed.regExp: The RegExp for the expression.critical: This type of dependency should be consider as critical (emits a warning).All options and defaults:
unknownContextRequest = ".", unknownContextRecursive = true, unknownContextRegExp = /^\.\/.*$/, unknownContextCritical = true
exprContextRequest = ".", exprContextRegExp = /^\.\/.*$/, exprContextRecursive = true, exprContextCritical = true
wrappedContextRegExp = /.*/, wrappedContextRecursive = true, wrappedContextCritical = false
Note:
module.wrappedContextRegExponly refers to the middle part of the full RegExp. The remaining is generated from prefix and suffix.
Example:
{
module: {
// Disable handling of unknown requires
unknownContextRegExp: /$^/,
unknownContextCritical: false,
// Disable handling of requires with a single expression
exprContextRegExp: /$^/,
exprContextCritical: false,
// Warn for every expression in require
wrappedContextCritical: true
}
}
resolveOptions affecting the resolving of modules.
resolve.aliasReplace modules with other modules or paths.
Expects an object with keys being module names. The value is the new path. It’s similar to a replace but a bit more clever. If the key ends with $ only the exact match (without the $) will be replaced.
If the value is a relative path it will be relative to the file containing the require.
Examples: Calling a require from /abc/entry.js with different alias settings.
alias: |
require("xyz") |
require("xyz/file.js") |
|---|---|---|
{} |
/abc/node_modules/xyz/index.js |
/abc/node_modules/xyz/file.js |
{ xyz: "/absolute/path/to/file.js" } |
/absolute/path/to/file.js |
error |
{ xyz$: "/absolute/path/to/file.js" } |
/absolute/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/dir/file.js |
{ xyz: "xyz/dir" } |
/abc/node_modules/xyz/dir/index.js |
/abc/node_modules/xyz/dir/file.js |
{ xyz$: "xyz/dir" } |
/abc/node_modules/xyz/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.
resolve.rootThe directory (absolute path) that contains your modules. May also be an array of directories. This setting should be used to add individual directories to the search path.
It must be an absolute path! Don’t pass something like
./app/modules.
Example:
var path = require('path');
// ...
resolve: {
root: [
path.resolve('./app/modules'),
path.resolve('./vendor/modules')
]
}
resolve.modulesDirectoriesAn array of directory names to be resolved to the current directory as well as its ancestors, and searched for modules. This functions similarly to how node finds “node_modules” directories. For example, if the value is ["mydir"], webpack will look in “./mydir”, “../mydir”, “../../mydir”, etc.
Default:
["web_modules", "node_modules"]Note: Passing
"../someDir","app","."or an absolute path isn’t necessary here. Just use a directory name, not a path. Use only if you expect to have a hierarchy within these folders. Otherwise you may want to use theresolve.rootoption instead.
resolve.fallbackA directory (or array of directories absolute paths), in which webpack should look for modules that weren’t found in resolve.root or resolve.modulesDirectories.
resolve.extensionsAn array of extensions that should be used to resolve modules. For example, in order to discover CoffeeScript files, your array should contain the string ".coffee".
Default:
[".webpack.js", ".web.js", ".js"]
IMPORTANT: Setting this option will override the default, meaning that webpack will no longer try to resolve modules using the default extensions. If you want modules that were required with their extension (e.g. require('./somefile.ext')) to be properly resolved, you must include an empty string in your array. Similarly, if you want modules that were required without extensions (e.g. require('underscore')) to be resolved to files with “.js” extensions, you must include ".js" in your array.
resolve.packageMainsCheck these fields in the package.json for suitable files.
Default:
["webpack", "browser", "web", "browserify", ["jam", "main"], "main"]
Note: This option has been changed to resolve.mainFields in webpack 2.
resolve.packageAliasCheck this field in the package.json for an object. Key-value-pairs are treated as aliasing according to this spec
Not set by default
Example: "browser" to check the browser field.
resolve.unsafeCacheEnable aggressive but unsafe caching for the resolving of a part of your files. Changes to cached paths may cause failure (in rare cases). An array of RegExps, only a RegExp or true (all files) is expected. If the resolved path matches, it’ll be cached.
Default:
[]
resolveLoaderLike resolve but for loaders.
// Default:
{
modulesDirectories: ["web_loaders", "web_modules", "node_loaders", "node_modules"],
extensions: ["", ".webpack-loader.js", ".web-loader.js", ".loader.js", ".js"],
packageMains: ["webpackLoader", "webLoader", "loader", "main"]
}
Note that you can use alias here and other features familiar from resolve. For example { txt: 'raw-loader' } would shim txt!templates/demo.txt to use raw-loader.
resolveLoader.moduleTemplatesThat’s a resolveLoader only property.
It describes alternatives for the module name that are tried.
Default:
["*-webpack-loader", "*-web-loader", "*-loader", "*"]
externalsIndicates dependencies that should not be bundled by webPack but instead remain requested by the resulting bundle. The requesting technique is modified to what is specified by output.libraryTarget or on a per dependency basis using a property-value pair object definition. Consequently, the value of externals may be a string, object, function, RegExp, or array as follows:
output.libraryTarget.false to ignore the externalization request and bundle the dependency anyway; true to bundle the dependency using the technique prescribed by output.libraryTarget; or a string containing two space separated names referring to a request technique per output.libraryTarget and a dependency reference, which may be different than the associated key.function(context, request, callback(err, result)) The function is called on each dependency. If a result is passed to the callback function this value is handled like a property value of an object (above bullet point).request for the external dependency. Because the request is the exact code used to generate the external code hook, if you are matching a commonjs package (e.g. ‘../some/package.js’), use the function external strategy instead. You can then import the package via callback(null, "require('" + request + "')", which generates a module.exports = require('../some/package.js');, using require outside of webpack context.Example:
{
output: { libraryTarget: "commonjs" },
externals: [
{
a: false, // a is not external
b: true, // b is external `module.exports = b`
"./c": "c", // "./c" is external `module.exports = c`
"./d": "var d" // "./d" is external `module.exports = ./d` <-- would be syntax error
"./f": "commonjs2 ./a/b" // "./f" is external `module.exports = require("./a/b")`
"./f": "commonjs ./a/b" // ...same as commonjs2
"./f": "this ./a/b" // "./f" is external `(function() { module.exports = this["./a/b"]; }())`
},
// Every non-relative module is external
// abc -> require("abc")
/^[a-z\-0-9]+$/,
function(context, request, callback) {
// Every module prefixed with "global-" becomes external
// "global-abc" -> abc
if(/^global-/.test(request))
return callback(null, "var " + request.substr(7));
callback();
},
"./e" // "./e" is external (require("./e"))
]
}
| type | value | resulting import code |
|---|---|---|
| “var” | "abc" |
module.exports = abc; |
| “var” | "abc.def" |
module.exports = abc.def; |
| “this” | "abc" |
(function() { module.exports = this["abc"]; }()); |
| “this” | ["abc", "def"] |
(function() { module.exports = this["abc"]["def"]; }()); |
| “commonjs” | "abc" |
module.exports = require("abc"); |
| “commonjs” | ["abc", "def"] |
module.exports = require("abc").def; |
| “amd” | "abc" |
define(["abc"], function(X) { module.exports = X; }) |
| “umd” | "abc" |
everything above |
Enforcing amd or umd in a external value will break if not compiling as amd/umd target.
Note: If using
umdyou can specify an object as external value with propertycommonjs,commonjs2,amdandrootto set different values for each import kind.
target"web" Compile for usage in a browser-like environment (default)"webworker" Compile as WebWorker"node" Compile for usage in a node.js-like environment (use require to load chunks)"async-node" Compile for usage in a node.js-like environment (use fs and vm to load chunks async)"node-webkit" Compile for usage in webkit, uses jsonp chunk loading but also supports build in node.js modules plus require(“nw.gui”) (experimental)"electron" Compile for usage in Electron – supports require-ing Electron-specific modules."electron-renderer" Compile for electron renderer process, provide a target using JsonpTemplatePlugin, FunctionModulePlugin for browser environment and NodeTargetPlugin and ExternalsPlugin for commonjs and electron bulit-in modules. Note: need webpack >= 1.12.15.
bailReport the first error as a hard error instead of tolerating it.
profileCapture timing information for each module.
Hint: Use the analyze tool to visualize it.
--jsonorstats.toJson()will give you the stats as JSON.
cacheCache generated modules and chunks to improve performance for multiple incremental builds.
This is enabled by default in watch mode.
You can pass false to disable it.
You can pass an object to enable it and let webpack use the passed object as cache. This way you can share the cache object between multiple compiler calls. Note: Don’t share the cache between calls with different options.
debugSwitch loaders to debug mode.
devtoolChoose a developer tool to enhance debugging.
eval - Each module is executed with eval and //@ sourceURL.
source-map - A SourceMap is emitted. See also output.sourceMapFilename.
hidden-source-map - Same as source-map, but doesn’t add a reference comment to the bundle.
inline-source-map - A SourceMap is added as DataUrl to the JavaScript file.
eval-source-map - Each module is executed with eval and a SourceMap is added as DataUrl to the eval.
cheap-source-map - A SourceMap without column-mappings. SourceMaps from loaders are not used.
cheap-module-source-map - A SourceMap without column-mappings. SourceMaps from loaders are simplified to a single mapping per line.
Prefixing @, # or #@ will enforce a pragma style. (Defaults to @ in webpack@1 and # in webpack@2; using # is recommended)
Combinations are possible. hidden, inline, eval and pragma style are exclusive.
i. e. cheap-module-inline-source-map, cheap-eval-source-map, #@source-map
Hint: If your modules already contain SourceMaps you’ll need to use the source-map-loader to merge it with the emitted SourceMap.
| devtool | build speed | rebuild speed | production supported | quality |
|---|---|---|---|---|
| eval | +++ | +++ | no | generated code |
| cheap-eval-source-map | + | ++ | no | transformed code (lines only) |
| cheap-source-map | + | o | yes | transformed code (lines only) |
| cheap-module-eval-source-map | o | ++ | no | original source (lines only) |
| cheap-module-source-map | o | - | yes | original source (lines only) |
| eval-source-map | – | + | no | original source |
| source-map | – | – | yes | original source |
Example:
{
devtool: "#inline-source-map"
}
// =>
//# sourceMappingURL=...
Note: With the next major version the default for
-dwill change tocheap-module-eval-source-map
devServerCan be used to configure the behaviour of webpack-dev-server when the webpack config is passed to webpack-dev-server CLI.
Example:
{
devServer: {
contentBase: "./build",
}
}
nodeInclude polyfills or mocks for various node stuff:
console: true or false
global: true or false
process: true, "mock" or false
Buffer: true or false
__filename: true (real filename relative to the context option), "mock" ("/index.js") or false (normal node __dirname)__dirname: true (real dirname relative to the context option), "mock" ("/") or false (normal node __dirname)<node buildin>: true, "mock", "empty" or false
// Default:
{
console: false,
global: true,
process: true,
Buffer: true,
__filename: "mock",
__dirname: "mock",
setImmediate: true
}
amdSet the value of require.amd and define.amd.
Example: amd: { jQuery: true } (for old 1.x AMD versions of jquery)
loaderCustom values available in the loader context.
recordsPath, recordsInputPath, recordsOutputPath
Store/Load compiler state from/to a json file. This will result in persistent IDs of modules and chunks.
An absolute path is expected. recordsPath is used for recordsInputPath and recordsOutputPath if they left undefined.
This is required when using Hot Code Replacement between multiple calls to the compiler.
pluginsAdd additional plugins to the compiler.
© 2012–2015 Tobias Koppers
Licensed under the MIT License.
https://webpack.github.io/docs/configuration.html