More configuration updates

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 { <key>: 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
+When combining with the [`output.library`](/configuration/output#output-library) option: If an array is passed only the last item is exported.

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`
+