diff --git a/content/configuration/entry-context.md b/content/configuration/entry-context.md index 9b4c804fd143..a769caf32926 100644 --- a/content/configuration/entry-context.md +++ b/content/configuration/entry-context.md @@ -11,26 +11,32 @@ contributors: `string` -The base directory, an absolute path, for resolving entry points. +The base directory, an **absolute path**, for resolving entry points and loaders from configuration. -```js -context: path.resolve(__dirname, ‘src’) +``` js +context: path.resolve(__dirname, "app") ``` +By default the current directory is used, but it's recommended to pass a value in your configuration. This makes your configuration independend from CWD. + --- ### `entry` -`string` `array` `object` +`string | [string] | object { : string | [string] }` + +The point or points to enter the application. At this point the application starts executing. If an array is passed all items will be executed. + +A dynamically loaded module is **not** an entry point. -The point or points to enter the application. +Simple rule: one entry point per HTML page. SPA: one entry point, MPA: multiple entry points. ```js entry: { - home: ‘./home.js’, - about: ‘./about.js’, - contact: ‘./contact.js’ + home: "./home.js", + about: "./about.js", + contact: "./contact.js" } ``` -?> Add more details on passing a string/array and how this will affect bundle names \ No newline at end of file +When combining with the [`output.library`](/configuration/output#output-library) option: If an array is passed only the last item is exported. diff --git a/content/configuration/index.md b/content/configuration/index.md index dc7c0395f3e1..6b0f08964c59 100644 --- a/content/configuration/index.md +++ b/content/configuration/index.md @@ -17,9 +17,9 @@ T> Notice that throughout the configuration we use Node's built-in [path module] // click on the name of the option to get to the detailed documentation // click on the items with arrows to show more examples / advanced options -
[entry](#entry): "./app/entry", // string | object | array - [entry](#entry): ["./app/entry1", "./app/entry2"], - [entry](#entry): { +
[entry](/configuration/entry-context#entry): "./app/entry", // string | object | array + [entry](/configuration/entry-context#entry): ["./app/entry1", "./app/entry2"], + [entry](/configuration/entry-context#entry): { a: "./app/entry-a", b: ["./app/entry-b1", "./app/entry-b2"] }, @@ -27,128 +27,131 @@ T> Notice that throughout the configuration we use Node's built-in [path module] // Here the application starts executing // and webpack starts bundling - [output](#output): { + [output](/configuration/output): { // options related how webpack emits results - [path](#output-path): path.resolve(__dirname, "dist"), // string + [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](#output-filename): "bundle.js", // string - [filename](#output-filename): "[name].js", // for multiple entry points - [filename](#output-filename): "[chunkhash].js", // for [long term caching](/how-to/cache) +
[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](/how-to/cache)
// the filename template for [entry chunks](chunks) -
[publicPath](#output-publicPath): "/assets/", // string - [publicPath](#output-publicPath): "", - [publicPath](#output-publicPath): "https://cdn.example.com/", +
[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](#output-library): "MyLibrary", // string, + [library](/configuration/output#output-library): "MyLibrary", // string, // the name of the exported library -
[libraryTarget](#output-librarytarget): "umd", // enum - [libraryTarget](#output-librarytarget): "umd-module", // ES6 module wrapped in UMD - [libraryTarget](#output-librarytarget): "commonjs-module", // ES6 module wrapped in CommonJs - [libraryTarget](#output-librarytarget): "commonjs2", // exported with module.exports - [libraryTarget](#output-librarytarget): "commonjs", // exported as properties to exports - [libraryTarget](#output-librarytarget): "amd", // defined with AMD defined method - [libraryTarget](#output-librarytarget): "this", // property set on this - [libraryTarget](#output-librarytarget): "var", // variable defined in root scope +
[libraryTarget](/configuration/output#output-librarytarget): "umd", // enum + [libraryTarget](/configuration/output#output-librarytarget): "umd-module", // ES6 module wrapped in UMD + [libraryTarget](/configuration/output#output-librarytarget): "commonjs-module", // ES6 module wrapped in CommonJs + [libraryTarget](/configuration/output#output-librarytarget): "commonjs2", // exported with module.exports + [libraryTarget](/configuration/output#output-librarytarget): "commonjs", // exported as properties to exports + [libraryTarget](/configuration/output#output-librarytarget): "amd", // defined with AMD defined method + [libraryTarget](/configuration/output#output-librarytarget): "this", // property set on this + [libraryTarget](/configuration/output#output-librarytarget): "var", // variable defined in root scope
// the type of the exported library
/* Advanced output configuration (click to show) */ - [pathinfo](#output-pathinfo): true, // boolean + [pathinfo](/configuration/output#output-pathinfo): true, // boolean // include useful path info about modules, exports, requests, etc. into the generated code - [chunkFilename](#output-chunkfilename): "[id].js", - [chunkFilename](#output-chunkfilename): "[chunkhash].js", // for [long term caching](/how-to/cache) + [chunkFilename](/configuration/output#output-chunkfilename): "[id].js", + [chunkFilename](/configuration/output#output-chunkfilename): "[chunkhash].js", // for [long term caching](/how-to/cache) // the filename template for additional chunks - [jsonpFunction](#output-jsonpFunction): "myWebpackJsonp", // string + [jsonpFunction](/configuration/output#output-jsonpfunction): "myWebpackJsonp", // string // name of the JSONP function used to load chunks - [sourceMapFilename](#output-sourceMapFilename): "[file].map", // string - [sourceMapFilename](#output-sourceMapFilename): "sourcemaps/[file].map", // string + [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](#output-devtoolModuleFilenameTemplate): "webpack:///[resource-path]", // string + [devtoolModuleFilenameTemplate](/configuration/output#output-devtoolmodulefilenametemplate): "webpack:///[resource-path]", // string // the name template for modules in a devtool - [devtoolFallbackModuleFilenameTemplate](#output-devtoolFallbackModuleFilenameTemplate): "webpack:///[resource-path]?[hash]", // string + [devtoolFallbackModuleFilenameTemplate](/configuration/output#output-devtoolfallbackmodulefilenametemplate): "webpack:///[resource-path]?[hash]", // string // the name template for modules in a devtool (used for conflicts) - [umdNamedDefine](#output-umdNamedDefine): true, // boolean + [umdNamedDefine](/configuration/output#output-umdnameddefine): true, // boolean // use a named AMD module in UMD library - [crossOriginLoading](#output-crossOriginLoading): "use-credentials", // enum - [crossOriginLoading](#output-crossOriginLoading): "anonymous", - [crossOriginLoading](#output-crossOriginLoading): false, + [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](#output-devtoolLineToLine): { + [devtoolLineToLine](/configuration/output#output-devtoollinetoline): { test: /\.jsx$/ }, // use a simple 1:1 mapped SourceMaps for these modules (faster) - [hotUpdateMainFilename](#output-hotUpdateMainFilename): "[hash].hot-update.json", // string + [hotUpdateMainFilename](/configuration/output#output-hotupdatemainfilename): "[hash].hot-update.json", // string // filename template for HMR manifest - [hotUpdateChunkFilename](#output-hotUpdateChunkFilename): "[id].[hash].hot-update.js", // string + [hotUpdateChunkFilename](/configuration/output#output-hotupdatechunkfilename): "[id].[hash].hot-update.js", // string // filename template for HMR chunks - [sourcePrefix](#output-sourcePrefix): "\t", // string + [sourcePrefix](/configuration/output#output-sourceprefix): "\t", // string // prefix module sources in bundle for better readablitity
}, - [module](#module): { + [module](/configuration/module): { // configuration regarding modules - [loaders](#module-loaders): [ - // rules to assign loaders to modules + [rules](/configuration/module#module-rules): [ + // rules for modules (configure loaders, parser options, etc.) { - [test](#module-loaders-test): /\.jsx?$/, - [include](#module-loaders-include): [ + [test](/configuration/module#rule-test): /\.jsx?$/, + [include](/configuration/module#rule-include): [ path.resolve(__dirname, "app") ], - [exclude](#module-loaders-exclude): [ + [exclude](/configuration/module#rule-exclude): [ path.resolve(__dirname, "app/demo-files") ] // matching conditions, each accepting regular expression or string // test and include behave equal, both must be matched - // exclude must not be matched + // exclude must not be matched (takes preferrence over test and include) // Best practices: // - 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 - [loader](#module-loaders-loader): "babel-loader", + [issuer](/configuration/module#rule-issuer): { test, include, exclude }, + // conditions for the issuer (the origin of the import) + + [enforce](/configuration/module#rule-enfore): "pre", + [enforce](/configuration/module#rule-enfore): "post", + // apply these rule even if rules are overriden (advanced option) + + [loader](/configuration/module#rule-loader): "babel-loader", // the loader which should be applied, it'll be resolve relative to the context - [options](#module-loaders-options): { + [options](/configuration/module#rule-options): { presets: ["es2015"] - } + }, // options for the loader - - enforce: "before", - enforce: "after", - // (deprecated) apply these rule even if rules are overriden }, { - test: "\.html$" + [test](/configuration/module#rule-test): "\.html$" - [loaders](#module-loaders-loaders): [ - // apply multiple loaders + [use](/configuration/module#rule-use): [ + // apply multiple loaders and options "htmllint-loader", { loader: "html-loader", @@ -157,13 +160,28 @@ T> Notice that throughout the configuration we use Node's built-in [path module] } } ] - } + }, + { [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](#module.noParse): [ + [noParse](/configuration/module#module-noparse): [ /special-library\.js$/ ], // do not parse this module @@ -183,111 +201,115 @@ T> Notice that throughout the configuration we use Node's built-in [path module]
}, - [resolve](#resolve): { + [resolve](/configuration/resolve): { // options for resolving module requests // (does not apply to resolving to loaders) - [modules](#resolve-modules): [ + [modules](/configuration/resolve#resolve-modules): [ "node_modules", path.resolve(__dirname, "app") ], // directories where to look for modules - [extensions](#resolve-extensions): [".js", ".json", ".jsx", ".css"], + [extensions](/configuration/resolve#resolve-extensions): [".js", ".json", ".jsx", ".css"], // extensions that are used - [alias](#resolve-alias): [ + [alias](/configuration/resolve#resolve-alias): { // a list of module name aliasings + "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 "module/path/file" -> "new-module/path/file" + }, +
/* alternative alias syntax (click to show) */ + [alias](/configuration/resolve#resolve-alias): [ { - [name](#resolve-alias-name): "module", + [name](/configuration/resolve#resolve-alias-name): "module", // the old request - [alias](#resolve-alias-alias): "new-module", + [alias](/configuration/resolve#resolve-alias-alias): "new-module", // the new request - [onlyModule](#resolve-alias-onlyModule): true + [onlyModule](/configuration/resolve#resolve-alias-onlyModule): true // if true only "module" is aliased // if false "module/inner/path" is also aliased } ], - [alias](#resolve-alias): { - // alternative syntax (recommended) - - "only-module$": "new-module", - "module": "new-module" - }, +
/* Advanced resolve configuration (click to show) */ - [symlinks](#resolve-symlinks): true, + [symlinks](/configuration/resolve#resolve-symlinks): true, // follow symlinks to new location - [descriptionFiles](#resolve-descriptionFiles): ["package.json"], + [descriptionFiles](/configuration/resolve#resolve-descriptionfiles): ["package.json"], // files that are read for package description - [mainFields](#resolve-mainFields): ["main"], + [mainFields](/configuration/resolve#resolve-mainfields): ["main"], // properties that are read from description file // when a folder is requested - [aliasFields](#resolve-aliasFields): ["browser"], + [aliasFields](/configuration/resolve#resolve-aliasfields): ["browser"], // properites that are read from description file // to alias requests in this package - [enforceExtension](#resolve-enforceExtension): false, + [enforceExtension](/configuration/resolve#resolve-enforceextension): false, // if true request must not include an extensions // if false request may already include an extension - [moduleExtensions](#resolve-moduleExtensions): ["-module"], - [enforceModuleExtension](#resolve-enforceModuleExtension): false, + [moduleExtensions](/configuration/resolve#resolve-moduleextensions): ["-module"], + [enforceModuleExtension](/configuration/resolve#resolve-enforcemoduleextension): false, // like extensions/enforceExtension but for module names instead of files - [unsafeCache](#resolve-unsafeCache): true, - [unsafeCache](#resolve-unsafeCache): {}, + [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 preformance improvement is really big - [cachePredicate](#resolve-cachePredicate): (path, request) => true, + [cachePredicate](/configuration/resolve#resolve-cachepredicate): (path, request) => true, // predicate function which selects requests for caching - [plugins](#resolve-plugins): [ + [plugins](/configuration/resolve#resolve-plugins): [ // ... ] // additional plugins applied to the resolver
}, -
[devtool](#devtool): "source-map", // enum - [devtool](#devtool): "inline-source-map", // inlines SourceMap into orginal file - [devtool](#devtool): "eval-source-map", // inlines SourceMap per module - [devtool](#devtool): "hidden-source-map", // SourceMap without reference in original file - [devtool](#devtool): "cheap-source-map", // cheap-variant of SourceMap without module mappings - [devtool](#devtool): "cheap-module-source-map", // cheap-variant of SourceMap with module mappings - [devtool](#devtool): "eval", // no SourceMap, but named modules +
[devtool](/configuration/devtool): "source-map", // enum + [devtool](/configuration/devtool): "inline-source-map", // inlines SourceMap into orginal file + [devtool](/configuration/devtool): "eval-source-map", // inlines SourceMap per module + [devtool](/configuration/devtool): "hidden-source-map", // SourceMap without reference in original file + [devtool](/configuration/devtool): "cheap-source-map", // cheap-variant of SourceMap without module mappings + [devtool](/configuration/devtool): "cheap-module-source-map", // cheap-variant of SourceMap with module mappings + [devtool](/configuration/devtool): "eval", // no SourceMap, but named modules
// enhance debugging by adding meta info for the browser devtools - [context](#context): __dirname, // string + [context](/configuration/entry-context#context): __dirname, // string (absolute path!) // the home directory for webpack - // the [entry](#entry) and [module.loaders.loader](#module-loaders-loader) option + // the [entry](entry) and [module.rules.loader](/configuration/module#rule-loader) option // is resolved relative to this directory -
[target](#target): "web", // enum - [target](#target): "webworker", // WebWorker - [target](#target): "node", // node.js via require - [target](#target): "async-node", // node.js via fs and vm - [target](#target): "node-webkit", // nw.js - [target](#target): "electron-main", // electron, main process - [target](#target): "electron-renderer", // electron, renderer process - [target](#target): (compiler) => { /* ... */ }, // custom +
[target](/configuration/target): "web", // enum + [target](/configuration/target): "webworker", // WebWorker + [target](/configuration/target): "node", // node.js via require + [target](/configuration/target): "async-node", // node.js via fs and vm + [target](/configuration/target): "node-webkit", // nw.js + [target](/configuration/target): "electron-main", // electron, main process + [target](/configuration/target): "electron-renderer", // electron, renderer process + [target](/configuration/target): (compiler) => { /* ... */ }, // custom
// the environment in which the bundle should run // changes chunk loading behavior and available modules - [externals](#externals): ["angular", "react"], // array - [externals](#externals): /^[a-z\-]+($|\/)/, // Regex - [externals](#externals): { +
[externals](/configuration/externals): ["react", /^@angular\//], + [externals](/configuration/externals): "react", // string (exact match) + [externals](/configuration/externals): /^[a-z\-]+($|\/)/, // Regex + [externals](/configuration/externals): { // object angular: "this angular", // this["angular"] react: { // UMD commonjs: "react", @@ -295,55 +317,56 @@ T> Notice that throughout the configuration we use Node's built-in [path module] amd: "react", root: "React" } - } - [externals](#externals): (request) => { /* ... */ return "commonjs " + request } + }, + [externals](/configuration/externals): (request) => { /* ... */ return "commonjs " + request } +
// Don't follow/bundle these modules, but request them at runtime from the environment - [stats](#stats): { + [stats](stats): { /* TODO */ }, - [devServer](#devServer): { + [devServer](/configuration/dev-server): { /* TODO */ }, - [plugins](#plugins): [ + [plugins](plugins): [ // ... ], // list of additional plugins
/* Advanced configuration (click to show) */ - [resolveLoader](#resolveLoader): { /* same as resolve */ } + [resolveLoader](/configuration/resolve#resolveloader): { /* same as resolve */ } // separate resolve options for loaders - [profile](#profile): true, // boolean + [profile](other-options#profile): true, // boolean // capture timing information - [cache](#cache): false, // boolean + [cache](other-options#cache): false, // boolean // disable/enable caching - [watch](#watch): true, // boolean + [watch](watch#watch): true, // boolean // enables watching - [watchOptions](#watchOptions): { - [aggregateTimeout](#watchOptions.aggregateTimeout): 1000, // in ms + [watchOptions](watch#watchoptions): { + [aggregateTimeout](#watchoptions.aggregatetimeout): 1000, // in ms // aggregates multiple changes to a single rebuild - [poll](#watchOptions.poll): true, - [poll](#watchOptions.poll): 500, // intervall in ms + [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): { + [node](node): { /* TODO */ }, - [recordsPath](#recordsPath): path.resolve(__dirname, "build/records.json"), - [recordsInputPath](#recordsInputPath): path.resolve(__dirname, "build/records.json"), - [recordsOutputPath](#recordsOutputPath): path.resolve(__dirname, "build/records.json"), + [recordsPath](other-options#recordspath): path.resolve(__dirname, "build/records.json"), + [recordsInputPath](other-options#recordsinputpath): path.resolve(__dirname, "build/records.json"), + [recordsOutputPath](other-options#recordsiutputpath): path.resolve(__dirname, "build/records.json"), // TODO
diff --git a/content/configuration/module.md b/content/configuration/module.md index 6b57fe56e1f0..ecad9d278f64 100644 --- a/content/configuration/module.md +++ b/content/configuration/module.md @@ -5,75 +5,231 @@ contributors: - gregvenech --- -### `module` +These options determine how the [different types of modules](/concepts/everything-is-a-module) within a project will be treated. -`object` +### `module.rules` -These options determine how the [different types of modules](/concepts/everything-is-a-module) within a project will be treated. +`array` +An array of [Rules](#rule) 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. -### Loader Objects -Loader objects are used in a few places throughout the configuration. They identify groups of modules using regular expressions. [Loaders](/concepts/loaders) can then be used, and chained together, to process, transform, or manipulate that group of modules in a variety of ways. Loader objects can contain the following properties: +### `Rule` -`test: /\.js/` - Identify one or more file extensions using a [regex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp), string, or function +A Rule can be separated into three parts: Conditions, Results and nested Rules. -`include: /\/src/` - Include modules using a regex, string, or function +#### `Rule` conditions -`exclude: /node_modules/` - Exclude modules using a regex, string, or function +There are two input values for the conditions: -`loader: "babel-loader!eslint-loader"` - A `!` delimited string of loaders to use on these modules +The resource: An absolute path to the file requested. It's already resolved according the [`resolve` rules](/configuration/resolve). -`loaders: [ "babel-loader", "eslint-loader" ]` - An array of loaders to use on these modules +The issuer: An absolute path to the file of the module which requested the resource. It's the location of the import. -T> Loaders are always read from **right to left** whether passed via a string or an array. In the example above, the [eslint-loader](https://github.com/MoOx/eslint-loader) will lint the JavaScript modules and then hand them off to the [babel-loader](https://github.com/babel/babel-loader) for transpiling. It's useful to think of this process as a series of nested function calls, i.e. `babelLoader(eslintLoader(...))`, each one passing it's return value on to the next. +Example: The `import "./style.css"` from `app.js`: +Resource is `/path/to/style.css`. Issuer is `/path/to/app.js`. -### `module.preLoaders` +In a Rule the properties [`test`](#rule-test), [`include`](#rule-include), [`exclude`](#rule-exclude) and [`resource`](#rule-resource) are matched with the resource and the property [`issuer`](#rule-issuer) is matched with the issuer. -`array` +When using multiple conditions, all conditions must match. -An array of [loader objects](#loader-objects) to be used as the first step in the loading process. In the example above, linting could be broken out into a *preLoader*: +#### `Rule` results -```js -module: { - preLoaders: [ - { test: /\.js/, exclude: /node_modules/, loader: 'eslint-loader' } - ], - ... +Rule results are only used when the Rule condition matches. + +There are two output values of a Rule: + +The applied loaders: An array of loaders applied to the resource. Separated in pre-, post- and normal loaders. + +The parser options: An object with options which should be used to create the parser for this module. + +These properties affect the loaders: [`loader`](#rule-loader), [`options`](#rule-options), [`use`](#rule-use). + +For compatibility also these properties: [`query`](#rule-query), [`loaders`](#rule-loaders). + +The [`enforce`](#rule-enforce) property affect the loader category. Whether it's an normal, pre- or post- loader. + +The [`parser`](#rule-parser) property affect the parser options. + + +### `Rule` nested rules + +With the properties [`rules`](#rule-rules) and [`oneOf`](#rule-oneof) nested rules can be specified. + +Nested rules are used when the Rule condition matches. + + +### `Rule.test` + +`Rule.test` is a shortcut to `Rule.resource.test`. See [`Rule.resource`](#rule-resource) and [`Condition.test`](#condition) for details. + + +### `Rule.include` + +`Rule.include` is a shortcut to `Rule.resource.include`. See [`Rule.resource`](#rule-resource) and [`Condition.include`](#condition) for details. + + +### `Rule.exclude` + +`Rule.exclude` is a shortcut to `Rule.resource.exclude`. See [`Rule.resource`](#rule-resource) and [`Condition.exclude`](#condition) for details. + + +### `Rule.resource` + +A [`Condtion`](#condition) matched with the resource. See details in [`Rule` conditions](#rule-conditions). + + +### `Rule.issuer` + +A [`Condtion`](#condition) matched with the issuer. See details in [`Rule` conditions](#rule-conditions). + + +### `Rule.loader` + +`Rule.loader` is a shortcut to `Rule.use: [ { loader } ]`. See [`Rule.use`](#rule-use) and [`UseEntry.loader`](#useentry-loader) for details. + + +### `Rule.options` +### `Rule.query` + +`Rule.options` and `Rule.query` are shortcuts to `Rule.use: [ { options } ]`. See [`Rule.use`](#rule-use) and [`UseEntry.options`](#useentry-options) for details. + +`Rule.query` only exists for compatiblity reasons. Use `Rule.options` instead. + + +### `Rule.loaders` + +`Rule.loaders` is an alias to `Rule.use`. See [`Rule.use`](#rule-use) for details. + +It exists for compatiblity reasons. Use `Rule.use` instead. + + +### `Rule.use` + +A list of [UseEntries](#useentry) which are applied to the module. Each entry specified a loader which should be used. + +Passing a string (i. e. `use: [ "style-loader" ]`) is a shortcut to the loader property (i. e. `use: [ { loader: "style-loader "} ]`). + +See [UseEntry](#useentry) for details. + + +### `Rule.enforce` + +Either `"pre"`, `"post" or no value. + +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. + +All loaders are sorted in the order `post, inline, normal, pre` and used in this order. + +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. + +Inline loaders and `!` prefixes should not be used as they are non-standard. They may be use by loader generated code. + + +### `Rule.rules` + +An array of [`Rules`](#rule) that is also used when the Rule matches. + + +### `Rule.oneOf` + +An array of [`Rules`](#rule) from which only the first matching Rule is used when the Rule matches. + + +### `Rule.parser` + +An object with parser options. All applied parser options are merged. + +For each different parser options object a new parser is created and plugins can apply plugins depending on the parser options. Many of the default plugins apply their parser plugins only if a property in the parser options is not set or true. + +Examples (parser options by the default plugins): + +``` js-with-links +parser: { + amd: false, // disable AMD + commonjs: false, // disable CommonJs + system: false, // disable System + harmony: false, // disable 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. + node: {...} // reconfigure [node](/configuration/node) layer on module level } ``` -### `module.loaders` +### `Condition` -`array` +Conditions can be one of these: -An array of [loader objects](#loader-objects) to be used as the second step in the loading process. Many times `module.loaders` will be the only set of loader objects needed. A basic configuration might look like this: +* A string: To match the input must start with the provided string. I. e. an absolute directory path, or absolute path to the file. +* A RegExp: It's tested with the input. +* A function: It's called with the input and must return a truthy value to match. +* An array of Conditions: At least one of the Condition must match. +* A object: All properties must match. Each property has a defined behavior. -```js -module: { - loaders: [ - { test: /\.js/, exclude: /node_modules/, loader: 'babel-loader!eslint-loader' }, - { test: /\.css/, loader: 'style-loader!css-loader' }, - { test: /\.(jpg|png|gif), loader: 'file-loader!img-loader' } +`{ test: Condition }`: The Condition must match. The convention is the provide a RegExp or array of RegExps here, but it's not enforced. + +`{ include: Condition }`: The Condition must match. The convention is the provide a string or array of strings here, but it's not enforced. + +`{ exclude: Condition }`: The Condition must NOT match. The convention is the provide a string or array of strings here, but it's not enforced. + +`{ and: [Condition] }`: All Conditions must match. + +`{ or: [Condition] }`: Any Condition must match. + +`{ not: Condition }`: The Condition must NOT match. + +Example: + +``` js +{ + test: /\.css$/, + include: [ + path.resolve(__dirname, "app/styles"), + path.resolve(__dirname, "vendor/styles") ] } ``` -### `module.postLoaders` +### `UseEntry` -`array` +`object` + +It must have a `loader` property being a string. It is resolved relative to the configuration [`context`](/configuration/entry-context#context) with the loader resolving options ([resolveLoader](/configuration/resolve#resolveloader)). -An array of [loader objects](#loader-objects) to be used as the last step in the loading process. +It can have a `options` property being a string or object. This value is passed to the loader, which should interpret it as loader options. -?> Any good examples? +For compatibility a `query` property is also possible, which is an alias for the `options` property. Use the `options` property instead. + +Example: + +``` js +{ + loader: "css-loader", + options: { + modules: true + } +} +``` + +Note that webpack need to generate an unique module identifier from 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%, but may be not unique if you apply the same loaders with different options to the same resource and the options have some 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. ### `module.noParse` -`regex` `array` +`RegExp | [RegExp]` 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... @@ -84,19 +240,26 @@ noParse: /jquery|backbone/ ### Module Contexts -General description... +(Deprecated) + +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: ```js module: { - ..., unknownContextRequest: ".", - unknownContextRegExp: /^\.\/.*$/, + unknownContextRegExp: false, unknownContextRecursive: true, unknownContextCritical: true, exprContextRequest: ".", - exprContextRegExp: /^\.\/.*$/, + exprContextRegExp: false, exprContextRecursive: true, exprContextCritical: true, wrappedContextRegExp: /.*/, @@ -105,4 +268,11 @@ module: { } ``` -?> Need help on this, frankly I haven't needed these options and am a bit confused about what they're used for even after reading through the [current section](http://webpack.github.io/docs/configuration.html#automatically-created-contexts-defaults-module-xxxcontextxxx) a few times. +Note: You can use the [`ContextReplacementPlugin`]() to modify these values for individual dependencies. This also removes the warning. + +A few usecases: + +* Warn for dynamic dependencies: `wrappedContextCritical: true`. +* `require(expr)` should include the whole directory: `exprContextRegExp: /^\.\//` +* `require("./templates/" + expr)` should not include subdirectories by default: `wrappedContextRecursive: false` + diff --git a/content/configuration/output.md b/content/configuration/output.md index 0a4ebcc01750..8a1020c760bb 100644 --- a/content/configuration/output.md +++ b/content/configuration/output.md @@ -5,108 +5,161 @@ contributors: - gregvenech --- -The top-level `output` key contains set of options instructing webpack on how and where it should output your bundles, assets and anything else you bundle or load with webpack. +The top-level `output` key contains set of options instructing webpack on how and where it should output your bundles, assets and anything else you bundle or load with webpack. -### `output` +### `output.path` -`object` +`string` -Below is a simple example followed by descriptions of each individual `output` option: +The output directory as an **absolute** path. -```js -output: { - filename: ‘[name].bundle.js’, - path: path.resolve(__dirname, ‘dist/assets’), - publicPath: ‘/assets/’ -} +``` js +path: path.resolve(__dirname, 'dist/assets') ``` +Note that `[hash]` in this parameter will be replaced with an hash of the compilation. See the [Caching guide](/how-to/cache) for details. -### `output.filename` + +### `output.publicPath` `string` -This option determines the name of each output bundle. For a single `entry` point with no children, this can be a static name. 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... +This is a pretty 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 `` 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. + +The default value is an empty string `""`. -Using entry/chunk names: -```js -filename: [name].bundle.js +Simple rule: The URL of your [`output.path`](#output-path) from the view of the HTML page. + +``` js +path: path.resolve(__dirname, "public/assets"), +publicPath: "https://cdn.example.com/assets/" ``` -Using the unique hash generated for every build: -```js -filename: [name].[hash].bundle.js +For this configuration: + +``` js +publicPath: "/assets/", +chunkFilename: "[id].chunk.js" ``` -Using hashes based on each chunks' content: -```js -filename: [chunkhash].bundle.js +A request to a chunk will look like `/assets/4.chunk.js`. + +A loader outputting HTML might emit something like this: + +``` html + ``` +or when loading an image in CSS: -### `output.path` +``` css +background-image: url(/assets/spinner.gif); +``` -`string` +The [webpack-dev-server]() also takes a hint from `publicPath`, using it to determine where to serve the output files from. -The output directory as an **absolute** path. Note that the `[hash]` subsitution may be used here as well. +Note that `[hash]` in this parameter will be replaced with an hash of the compilation. See the [Caching guide](/how-to/cache) for details. -```js -path: path.resolve(__dirname, 'dist/assets') +Examples: + +``` js +publicPath: "https://cdn.example.com/assets/", // CDN (always HTTPS) +publicPath: "//cdn.example.com/assets/", // CDM (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) ``` -### `output.publicPath` +### `output.filename` `string` -This option specifies the public address of the output files when referenced in a browser. For [loaders](/concepts/loaders) that embed `