diff --git a/src/content/configuration/index.md b/src/content/configuration/index.md index 31f945f414cc..ec872f7dbbdb 100644 --- a/src/content/configuration/index.md +++ b/src/content/configuration/index.md @@ -11,21 +11,40 @@ contributors: - mattce - kbariotis - sterlingvix + - jeremenichelli --- -webpack is fed via a configuration object. It is passed in one of two ways depending on how you are using webpack: through the terminal or via Node.js. All the available configuration options are specified below. +Out of the box webpack won't require you a configuration file, it will assume the entry point of your project is `src/index` 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. T> New to webpack? Check out our guide to some of webpack's [core concepts](/concepts) to get started! -T> Notice that throughout the configuration we use Node's built-in [path module](https://nodejs.org/api/path.html) and prefix it with the [__dirname](https://nodejs.org/docs/latest/api/globals.html#globals_dirname) global. This prevents file path issues between operating systems and allows relative paths to work as expected. See [this section](https://nodejs.org/api/path.html#path_windows_vs_posix) for more info on POSIX vs. Windows paths. + +## Use different config file + +If for some reason you want to use different config file depending on certain situations you can change this via command line by using the `--config` flag. + +**package.json** + +```json +"scripts": { + "build": "webpack --config prod.config.js" +} +``` + ## Options Click on the name of each option in the configuration code below to jump to the detailed documentation. Also note that the items with arrows can be expanded to show more examples and, in some cases, more advanced configuration. +W> Notice that throughout the configuration we use Node's built-in [path module](https://nodejs.org/api/path.html) and prefix it with the [__dirname](https://nodejs.org/docs/latest/api/globals.html#globals_dirname) global. This prevents file path issues between operating systems and allows relative paths to work as expected. See [this section](https://nodejs.org/api/path.html#path_windows_vs_posix) for more info on POSIX vs. Windows paths. + __webpack.config.js__ -``` js-with-links-with-details +```js-with-links-with-details const path = require('path'); module.exports = { @@ -35,7 +54,6 @@ module.exports = { [mode](/concepts/mode): "none", // no defaults // Chosen mode tells webpack to use its built-in optimizations accordingly. -
[entry](/configuration/entry-context#entry): "./app/entry", // string | object | array [entry](/configuration/entry-context#entry): ["./app/entry1", "./app/entry2"], [entry](/configuration/entry-context#entry): { @@ -45,29 +63,23 @@ module.exports = {
// Here the application starts executing // and webpack starts bundling - [output](/configuration/output): { // options related to how webpack emits results - [path](/configuration/output#output-path): path.resolve(__dirname, "dist"), // string // the target directory for all output files // must be an absolute path (use the Node.js path module) -
[filename](/configuration/output#output-filename): "bundle.js", // string [filename](/configuration/output#output-filename): "[name].js", // for multiple entry points [filename](/configuration/output#output-filename): "[chunkhash].js", // for [long term caching](/guides/caching)
// the filename template for entry chunks -
[publicPath](/configuration/output#output-publicpath): "/assets/", // string [publicPath](/configuration/output#output-publicpath): "", [publicPath](/configuration/output#output-publicpath): "https://cdn.example.com/",
// the url to the output directory resolved relative to the HTML page - [library](/configuration/output#output-library): "MyLibrary", // string, // the name of the exported library -
[libraryTarget](/configuration/output#output-librarytarget): "umd", // universal module definition [libraryTarget](/configuration/output#output-librarytarget): "umd2", // universal module definition [libraryTarget](/configuration/output#output-librarytarget): "commonjs2", // exported with module.exports @@ -81,62 +93,45 @@ module.exports = { [libraryTarget](/configuration/output#output-librarytarget): "jsonp", // jsonp wrapper
// the type of the exported library -
/* Advanced output configuration (click to show) */ - [pathinfo](/configuration/output#output-pathinfo): true, // boolean - // include useful path info about modules, exports, requests, etc. into the generated code - + // include useful path info about modules, exports, requests, etc. into the generated cod [chunkFilename](/configuration/output#output-chunkfilename): "[id].js", [chunkFilename](/configuration/output#output-chunkfilename): "[chunkhash].js", // for [long term caching](/guides/caching) // the filename template for additional chunks - [jsonpFunction](/configuration/output#output-jsonpfunction): "myWebpackJsonp", // string // name of the JSONP function used to load chunks - [sourceMapFilename](/configuration/output#output-sourcemapfilename): "[file].map", // string [sourceMapFilename](/configuration/output#output-sourcemapfilename): "sourcemaps/[file].map", // string // the filename template of the source map location - [devtoolModuleFilenameTemplate](/configuration/output#output-devtoolmodulefilenametemplate): "webpack:///[resource-path]", // string // the name template for modules in a devtool - [devtoolFallbackModuleFilenameTemplate](/configuration/output#output-devtoolfallbackmodulefilenametemplate): "webpack:///[resource-path]?[hash]", // string // the name template for modules in a devtool (used for conflicts) - [umdNamedDefine](/configuration/output#output-umdnameddefine): true, // boolean // use a named AMD module in UMD library - [crossOriginLoading](/configuration/output#output-crossoriginloading): "use-credentials", // enum [crossOriginLoading](/configuration/output#output-crossoriginloading): "anonymous", [crossOriginLoading](/configuration/output#output-crossoriginloading): false, // specifies how cross origin request are issued by the runtime -
/* Expert output configuration (on own risk) */ - [devtoolLineToLine](/configuration/output#output-devtoollinetoline): { test: /\.jsx$/ }, // use a simple 1:1 mapped SourceMaps for these modules (faster) - [hotUpdateMainFilename](/configuration/output#output-hotupdatemainfilename): "[hash].hot-update.json", // string // filename template for HMR manifest - [hotUpdateChunkFilename](/configuration/output#output-hotupdatechunkfilename): "[id].[hash].hot-update.js", // string // filename template for HMR chunks - [sourcePrefix](/configuration/output#output-sourceprefix): "\t", // string // prefix module sources in bundle for better readablitity
}, - [module](/configuration/module): { // configuration regarding modules - [rules](/configuration/module#module-rules): [ // rules for modules (configure loaders, parser options, etc.) - { [test](/configuration/module#rule-test): /\.jsx?$/, [include](/configuration/module#rule-include): [ @@ -152,28 +147,22 @@ module.exports = { // - Use RegExp only in test and for filename matching // - Use arrays of absolute paths in include and exclude // - Try to avoid exclude and prefer include - [issuer](/configuration/module#rule-issuer): { test, include, exclude }, // conditions for the issuer (the origin of the import) - [enforce](/configuration/module#rule-enforce): "pre", [enforce](/configuration/module#rule-enforce): "post", // flags to apply these rules, even if they are overridden (advanced option) - [loader](/configuration/module#rule-loader): "babel-loader", // the loader which should be applied, it'll be resolved relative to the context // -loader suffix is no longer optional in webpack2 for clarity reasons // see [webpack 1 upgrade guide](/guides/migrating) - [options](/configuration/module#rule-options-rule-query): { presets: ["es2015"] }, // options for the loader }, - { [test](/configuration/module#rule-test): /\.html$/, - [use](/configuration/module#rule-use): [ // apply multiple loaders and options "htmllint-loader", @@ -185,31 +174,23 @@ module.exports = { } ] }, - { [oneOf](/configuration/module#rule-oneof): [ /* rules */ ] }, // only use one of these nested rules - { [rules](/configuration/module#rule-rules): [ /* rules */ ] }, // use all of these nested rules (combine with conditions to be useful) - { [resource](/configuration/module#rule-resource): { [and](/configuration/module#condition): [ /* conditions */ ] } }, // matches only if all conditions are matched - { [resource](/configuration/module#rule-resource): { [or](/configuration/module#condition): [ /* conditions */ ] } }, { [resource](/configuration/module#rule-resource): [ /* conditions */ ] }, // matches if any condition is matched (default for arrays) - { [resource](/configuration/module#rule-resource): { [not](/configuration/module#condition): /* condition */ } } // matches if the condition is not matched ], -
/* Advanced module configuration (click to show) */ - [noParse](/configuration/module#module-noparse): [ /special-library\.js$/ ], // do not parse this module - unknownContextRequest: ".", unknownContextRecursive: true, unknownContextRegExp: /^\.\/.*$/, @@ -224,29 +205,22 @@ module.exports = { // specifies default behavior for dynamic requests
}, - [resolve](/configuration/resolve): { // options for resolving module requests // (does not apply to resolving to loaders) - [modules](/configuration/resolve#resolve-modules): [ "node_modules", path.resolve(__dirname, "app") ], // directories where to look for modules - [extensions](/configuration/resolve#resolve-extensions): [".js", ".json", ".jsx", ".css"], // extensions that are used - [alias](/configuration/resolve#resolve-alias): { // a list of module name aliases - "module": "new-module", // alias "module" -> "new-module" and "module/path/file" -> "new-module/path/file" - "only-module$": "new-module", // alias "only-module" -> "new-module", but not "only-module/path/file" -> "new-module/path/file" - "module": path.resolve(__dirname, "app/third/module.js"), // alias "module" -> "./app/third/module.js" and "module/file" results in error // modules aliases are imported relative to the current context @@ -256,57 +230,44 @@ module.exports = { { name: "module", // the old request - alias: "new-module", // the new request - onlyModule: true // if true only "module" is aliased // if false "module/inner/path" is also aliased } ], -
/* Advanced resolve configuration (click to show) */ - [symlinks](/configuration/resolve#resolve-symlinks): true, // follow symlinks to new location - [descriptionFiles](/configuration/resolve#resolve-descriptionfiles): ["package.json"], // files that are read for package description - [mainFields](/configuration/resolve#resolve-mainfields): ["main"], // properties that are read from description file // when a folder is requested - [aliasFields](/configuration/resolve#resolve-aliasfields): ["browser"], // properites that are read from description file // to alias requests in this package - [enforceExtension](/configuration/resolve#resolve-enforceextension): false, // if true request must not include an extensions // if false request may already include an extension - [moduleExtensions](/configuration/resolve#resolveloader-moduleextensions): ["-module"], [enforceModuleExtension](/configuration/resolve#resolve-enforcemoduleextension): false, // like extensions/enforceExtension but for module names instead of files - [unsafeCache](/configuration/resolve#resolve-unsafecache): true, [unsafeCache](/configuration/resolve#resolve-unsafecache): {}, // enables caching for resolved requests // this is unsafe as folder structure may change // but performance improvement is really big - [cachePredicate](/configuration/resolve#resolve-cachepredicate): (path, request) => true, // predicate function which selects requests for caching - [plugins](/configuration/resolve#resolve-plugins): [ // ... ] // additional plugins applied to the resolver
}, - [performance](/configuration/performance): {
[hints](/configuration/performance#performance-hints): "warning", // enum [hints](/configuration/performance#performance-hints): "error", // emit errors for perf hints @@ -319,7 +280,6 @@ module.exports = { return assetFilename.endsWith('.css') || assetFilename.endsWith('.js'); } }, -
[devtool](/configuration/devtool): "source-map", // enum [devtool](/configuration/devtool): "inline-source-map", // inlines SourceMap into original file [devtool](/configuration/devtool): "eval-source-map", // inlines SourceMap per module @@ -330,12 +290,10 @@ module.exports = {
// enhance debugging by adding meta info for the browser devtools // source-map most detailed at the expense of build speed. - [context](/configuration/entry-context#context): __dirname, // string (absolute path!) // the home directory for webpack // the [entry](/configuration/entry-context) and [module.rules.loader](/configuration/module#rule-loader) option // is resolved relative to this directory -
[target](/configuration/target): "web", // enum [target](/configuration/target): "webworker", // WebWorker [target](/configuration/target): "node", // Node.js via require @@ -347,7 +305,6 @@ module.exports = {
// the environment in which the bundle should run // changes chunk loading behavior and available modules -
[externals](/configuration/externals): ["react", /^@angular\//], [externals](/configuration/externals): "react", // string (exact match) [externals](/configuration/externals): /^[a-z\-]+($|\/)/, // Regex @@ -363,14 +320,12 @@ module.exports = { [externals](/configuration/externals): (request) => { /* ... */ return "commonjs " + request }
// Don't follow/bundle these modules, but request them at runtime from the environment - [serve](https://github.com/webpack-contrib/webpack-serve#options): { //object port: 1337, content './dist', // ... }, // lets you provide options for webpack-serve -
[stats](/configuration/stats): "errors-only", [stats](/configuration/stats): { //object assets: true, @@ -382,7 +337,6 @@ module.exports = { },
// lets you precisely control what bundle information gets displayed - [devServer](/configuration/dev-server): { proxy: { // proxy URLs to backend development server '/api': 'http://localhost:3000' @@ -395,48 +349,35 @@ module.exports = { noInfo: true, // only errors & warns on hot reload // ... }, - [plugins](plugins): [ // ... ], // list of additional plugins - -
/* Advanced configuration (click to show) */ - [resolveLoader](/configuration/resolve#resolveloader): { /* same as resolve */ } // separate resolve options for loaders - [parallelism](other-options#parallelism): 1, // number // limit the number of parallel processed modules - [profile](other-options#profile): true, // boolean // capture timing information - [bail](other-options#bail): true, //boolean // fail out on the first error instead of tolerating it. - [cache](other-options#cache): false, // boolean // disable/enable caching - [watch](watch#watch): true, // boolean // enables watching - [watchOptions](watch#watchoptions): { [aggregateTimeout](watch#watchoptions-aggregatetimeout): 1000, // in ms // aggregates multiple changes to a single rebuild - [poll](watch#watchoptions-poll): true, [poll](watch#watchoptions-poll): 500, // intervall in ms // enables polling mode for watching // must be used on filesystems that doesn't notify on change // i. e. nfs shares }, - [node](node): { // Polyfills and mocks to run Node.js- // environment code in non-Node environments. - [console](node#node-console): false, // boolean | "mock" [global](node#node-global): true, // boolean | "mock" [process](node#node-process): true, // boolean @@ -445,12 +386,10 @@ module.exports = { [Buffer](node#node-buffer): true, // boolean | "mock" [setImmediate](node#node-setimmediate): true // boolean | "mock" | "empty" }, - [recordsPath](other-options#recordspath): path.resolve(__dirname, "build/records.json"), [recordsInputPath](other-options#recordsinputpath): path.resolve(__dirname, "build/records.json"), [recordsOutputPath](other-options#recordsoutputpath): path.resolve(__dirname, "build/records.json"), // TODO -
} ```