nwb.config.js format changes to reduce nesting

- webpack.plugins is deprecated, just use webpack instead - Allow loader query config to be specified in the loader config object, rather than requiring a nested query object
insin · May 30, 2016 · a25ac14 · a25ac14
1 parent aaf7ef7
commit a25ac14
Show file tree

Hide file tree

Showing 8 changed files with 295 additions and 140 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -3,16 +3,71 @@
 - Replaced the deprecated `autoprefixer-loader` with `postcss-loader` in default style pipelines - it's configured to do the same autoprefixing by default [[#57](https://github.com/insin/nwb/issues/57)]
   - If you were configuring vendor prefixing using `webpack.loaders.autoprefixer`, you will now need to manage an `autprefixer` dependency yourself and use [`webpack.postcss`](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#postcss-object) to perform this configuration.
 
+**`nwb.config.js` Config Format Changes:**
+
+> For deprecations, nwb v0.11 will support the old format and display warning messages about the changes required.
+
+* `webpack.plugins` is deprecated - config under `webpack.plugins` should be moved up into `webpack` instead. Having certain config under a `plugins` prop was an implementation detail which wasn't relevant to end-users.
+
+  ```js
+  // < v0.11
+  module.exports = {
+    webpack: {
+      plugins: {
+        define: {...},
+        html: {...}
+      }
+    }
+  }
+  ```
+  ```js
+  // v0.11
+  module.exports = {
+    webpack: {
+      define: {...},
+      html: {...}
+    }
+  }
+  ```
+* Support for flatter [Wwebpack loader configuration](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#loaders-object) was added. Having a `query` object is now optional - loader query configuration can now be placed directly under the loader's id:
+
+  ```js
+  // < v0.11
+  module.exports = {
+    webpack: {
+      loaders: {
+        css: {
+          query: {
+            modules: true
+          }
+        }
+      }
+    }
+  }
+  ```
+  ```js
+  // v0.11
+  module.exports = {
+    webpack: {
+      loaders: {
+        css: {
+          modules: true
+        }
+      }
+    }
+  }
+  ```
+
 **Added:**
 
 - Added [`webpack.compat` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#compat-object) to enable compatibility configuration for modules which are commonly problematic with Webpack - initially this includes support for Enzyme, Moment.js and Sinon.js 1.x.
 - Added [`webpack.postcss` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#postcss-object) to customise the PostCSS plugins applied to each style pipeline.
-- Added [`webpack.plugins.vendorBundle` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#pluginsvendorbundle-boolean) to disable extracting anything imported from `node_modules/` out into a separate `vendor` chunk [[#106](https://github.com/insin/nwb/issues/106)]
+- Added [`webpack.vendorBundle` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#vendorbundle-boolean) to disable extracting anything imported from `node_modules/` out into a separate `vendor` chunk [[#106](https://github.com/insin/nwb/issues/106)]
 - Added [documentation for creating and using a test context module](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#test-context-module) if there's code you need to run prior to any tests running, such as configuring your assertion library with new assertions.
 
 **Changed:**
 
-- Apps are no longer required to provide their own HTML template. The default template path of `src/index.html` will continue to be used if it exists. If an alternative template is not provided via [`webpack.plugins.html` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#pluginshtml-object), nwb will now fall back to using a basic template.
+- Apps are no longer required to provide their own HTML template. The default template path of `src/index.html` will continue to be used if it exists. If an alternative template is not provided via [`webpack.html` config](https://github.com/insin/nwb/blob/v0.11.0/docs/Configuration.md#html-object), nwb will now fall back to using a basic template.
 - Restored default use of the Babel polyfill in Karma config so tests (and their dependencies) can assume a modern environment.
 
 **Dependencies:**
@@ -87,7 +142,7 @@
 
 **Removed:**
 
-- Backwards compatibility for `nwb.config.js` format changes made in 0.8 have been removed.
+- Backwards compatibility for `nwb.config.js` format changes made in 0.8 has been removed.
 
 **Added:**
 
@@ -135,13 +190,11 @@
 
   If you were configuring automatic npm installation using a `loaders.install.query.cli` config object, this should be moved to `webpack.plugins.install` instead.
 
-**Changed:**
-
-*`nwb.config.js` format changes:*
+**`nwb.config.js` Config Format Changes:**
 
 > nwb v0.8 will support the old format and display warning messages about the changes required before upgrading to nwb v0.9.
 
-1. React component and vanilla JS module npm build configuration must now be specificed as a `build` object:
+* React component and vanilla JS module npm build configuration must now be specificed as a `build` object:
 
   ```js
   // < v0.9
@@ -165,7 +218,7 @@
     }
   }
   ```
-1. Webpack configuration must now be specified as a `webpack` object:
+* Webpack configuration must now be specified as a `webpack` object:
 
   ```js
   // < v0.9
@@ -195,7 +248,7 @@
     }
   }
   ```
-1. Webpack `define` config must now be specified in a `plugins` object:
+* Webpack `define` config must now be specified in a `plugins` object:
 
   ```js
   // < v0.9
@@ -219,7 +272,7 @@
     }
   }
   ```
-1. All "extra" Webpack config must be specified in a an `extra` object, including extra loaders. The new object must correspond with Webpack's config file layout.
+* All "extra" Webpack config must be specified in a an `extra` object, including extra loaders. The new object must correspond with Webpack's config file layout.
 
   ```js
   // < v0.9

diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -24,13 +24,12 @@ The object exported or returned by your nwb config can use the following fields:
   * [`webpack.loaders`](#loaders-object)
     * [Default loaders](#default-loaders)
     * [Test loaders](#test-loaders)
-  * [`webpack.plugins`](#plugins-object)
-    * [`plugins.define`](#pluginsdefine-object)
-    * [`plugins.extractText`](#pluginsextracttext-object)
-    * [`plugins.html`](#pluginshtml-object)
-    * [`plugins.install`](#pluginsinstall-object)
-    * [`plugins.vendorBundle`](#pluginsvendorbundle-boolean)
-  * [`webpack.postcss`](#postcss-object)
+  * [`webpack.define`](#define-object)
+  * [`webpack.extractText`](#extracttext-object)
+  * [`webpack.html`](#html-object)
+  * [`webpack.install`](#install-object)
+  * [`webpack.vendorBundle`](#vendorbundle-boolean)
+  * [`webpack.postcss`](#postcss-array-object)
   * [`webpack.compat`](#compat-object)
   * [`webpack.extra`](#extra-object)
 * Karma Configuration
@@ -99,33 +98,48 @@ If provided, Babel config will also be used to configure the `babel-loader` Webp
 
 #### `webpack`: `Object`
 
-Webpack configuration must be provided in a `webpack` object.
+Webpack configuration can be provided in a `webpack` object.
 
 ##### `loaders`: `Object`
 
 Each [Webpack loader](https://webpack.github.io/docs/loaders.html) configured by default has a unique id you can use to customise it.
 
 To customise a loader, add a prop to the `loaders` object matching its id with a configuration object.
 
-Refer to each loader's documentation for configuration options which can be set via `query`.
+Refer to each loader's documentation (linked to for each [default loader](#default-loaders) documented below) for configuration options which can be set.
 
-e.g., to enable [CSS Modules][CSS Modules]:
+Generic loader options such as `include` and `exclude` can be configured alongside loader-specific query options - you can also use an explicit `query` object if necessary to separate this configuration.
+
+e.g. to enable [CSS Modules][CSS Modules] for your app's CSS, the following loader configs are equivalent:
 
+```js
+module.exports = {
+  webpack: {
+    loaders: {
+      css: {
+        modules: true,
+        localIdentName: '[hash:base64:5]'
+      }
+    }
+  }
+}
+```
 ```js
 module.exports = {
   webpack: {
     loaders: {
       css: {
         query: {
-          modules: true
+          modules: true,
+          localIdentName: '[hash:base64:5]'
         }
       }
     }
   }
 }
 ```
 
-If a loader supports configuration via a top-level webpack configuration property, this can be provided as `config`. This is primarily for loaders which can't be configured via `query` as they have configuration which can't be serialised, such as instances of plugins.
+If a loader supports configuration via a top-level webpack configuration property, this can be provided as a `config` prop. This is primarily for loaders which can't be configured via query parameters as they have configuration which can't be serialised, such as instances of plugins.
 
 e.g. to use the `nib` plugin with the [Stylus](http://learnboost.github.io/stylus/) preprocessor provided by [nwb-stylus](https://github.com/insin/nwb-stylus):
 
@@ -149,9 +163,9 @@ Alternatively, you can also add new properties directly to the top-level Webpack
 
 ###### Default Loaders
 
-Default loaders and their ids are:
+Default loaders configured by nwb and the ids it gives them are:
 
-* `babel` - handles `.js` and `.jsx` files with [babel-loader][babel-loader]
+* `babel` - handles `.js` (and `.jsx`) files with [babel-loader][babel-loader]
 
   > Default config: `{exclude: /node_modules/}`
 
@@ -165,19 +179,19 @@ Default loaders and their ids are:
   * `css` - handles URLs, minification and CSS Modules using [css-loader][css-loader]
   * `postcss` - processes CSS with PostCSS plugins using [postcss-loader][postcss-loader]; by default, this is configured to automatically add vendor prefixes to CSS using [autoprefixer][autoprefixer]
 
-* `vendor-css-pipeline` - handles `.css` files required from `node_modules`, with the same set of chained loaders as `css-pipeline` but with a `vendor-` prefix in their id.
+* `vendor-css-pipeline` - handles `.css` files required from `node_modules/`, with the same set of chained loaders as `css-pipeline` but with a `vendor-` prefix in their id.
 
   > Default config: `{include: /node_modules/}`
 
 * `graphics` - handles `.gif` and `.png` files using using [url-loader][url-loader]
 
-  > Default config: `{query: {limit: 10240}}`
+  > Default config: `{limit: 10240}`
 
 * `jpeg` - handles `.jpeg` files using [file-loader][file-loader]
 
 * `fonts` - handles `.otf`, `.svg`, `.ttf`, `.woff` and `.woff2` files using [url-loader][url-loader]
 
-  > Default config: `{query: {limit: 10240}}`
+  > Default config: `{limit: 10240}`
 
 * `eot` - handles `.eot` files using [file-loader][file-loader]
 
@@ -205,29 +219,25 @@ When running Karma tests with coverage enabled, the following loader will be add
   }
   ```
 
-##### `plugins`: `Object`
-
-###### `plugins.define`: `Object`
+##### `define`: `Object`
 
 By default, nwb will use Webpack's [`DefinePlugin`](https://webpack.github.io/docs/list-of-plugins.html#defineplugin) to replace all occurances of `process.env.NODE_ENV` with a string containing `NODE_ENV`'s current value.
 
-You can configure a `plugins.define` object to add your own constant values.
+You can configure a `define` object to add your own constant values.
 
 e.g. to replace all occurrences of `__VERSION__` with a string containing your app's version from its `package.json`:
 
 ```js
 module.exports = {
   webpack: {
-    plugins: {
-      define: {
-        __VERSION__: JSON.stringify(require('./package.json').version)
-      }
+    define: {
+      __VERSION__: JSON.stringify(require('./package.json').version)
     }
   }
 }
 ```
 
-###### `plugins.extractText`: `Object`
+##### `extractText`: `Object`
 
 Configures [options for `ExtractTextWebpackPlugin`](https://github.com/webpack/extract-text-webpack-plugin#readme).
 
@@ -236,16 +246,14 @@ This can be used to control whether or not CSS is extracted from all chunks in a
 ```js
 module.exports = {
   webpack: {
-    plugins: {
-      extractText: {
-        allChunks: true
-      }
+    extractText: {
+      allChunks: true
     }
   }
 }
 ```
 
-###### `plugins.html`: `Object`
+##### `html`: `Object`
 
 For apps, nwb will look for a `src/index.html` template to inject `<link>` and `<script>` tags into for each CSS and JavaScript bundle generated by Webpack.
 
@@ -254,10 +262,8 @@ Use `template`config if you have an HTML file elsewhere you want to use:
 ```js
 module.exports = {
   webpack: {
-    plugins: {
-      html: {
-        template: 'html/index.html'
-      }
+    html: {
+      template: 'html/index.html'
     }
   }
 }
@@ -276,11 +282,9 @@ If you don't have a template at `src/index.html` or specify one via `template`,
 ```js
 module.exports = {
   webpack: {
-    plugins: {
-      html: {
-        mountId: 'root',
-        title: 'Unimaginative documentation example'
-      }
+    html: {
+      mountId: 'root',
+      title: 'Unimaginative documentation example'
     }
   }
 }
@@ -291,39 +295,55 @@ Oher [`HtmlWebpackPlugin` options](https://github.com/ampedandwired/html-webpack
 ```js
 module.exports = {
   webpack: {
-    plugins: {
-      html: {
-        favicon: 'src/favicon.ico'
-      }
+    html: {
+      favicon: 'src/favicon.ico'
     }
   }
 }
 ```
 
-###### `plugins.install`: `Object`
+##### `install`: `Object`
 
 Configures [options for `NpmInstallPlugin`](https://github.com/ericclemmons/npm-install-webpack-plugin#usage), which will be used if you pass `--auto-install` flag to `nwb serve`.
 
-###### `plugins.vendorBundle`: `Boolean`
+##### `vendorBundle`: `Boolean`
 
 Setting this to `false` disables extraction of anything imported from `node_modules/` into a `vendor` bundle.
 
-##### `postcss`: `Object`
+##### `postcss`: `Array | Object`
 
 By default, nwb configures the `postcss-loader` in each style pipeline to automatically add vendor prefixes to CSS rules.
 
-You can configure a `postcss` object to provide your own list of PostCSS plugins to be used for each pipeline, which will completely overwrite nwb's default configuration.
+Use `postcss` configuration to provide your own list of PostCSS plugins to be used for each pipeline, which will completely overwrite nwb's default configuration.
+
+If you're *only* configuring PostCSS plugins for your app's own CSS, you can just provide a list:
+
+```js
+module.exports = {
+  webpack: {
+    postcss: [
+      require('precss'),
+      require('autoprefixer'),
+      require('cssnano')
+    ]
+  }
+}
+```
 
-PostCSS plugins for the default style pipeline (applied to your app's own CSS) must be configured using a `plugins` property:
+Use an object if you're configuring other style pipelines or additional style pipeline. When using an object, PostCSS plugins for the default style pipeline (applied to your app's own CSS) must be configured using a `defaults` property:
 
 ```js
+var autoprefixer = require('autoprefixer')
 module.exports = {
   webpack: {
     postcss: {
-      plugins: [
+      defaults: [
         require('precss'),
-        require('autoprefixer'),
+        autoprefixer,
         require('cssnano')
+      ],
+      vendor: [
+        autoprefixer({add: false})
       ]
     }
   }

diff --git a/src/createWebpackConfig.js b/src/createWebpackConfig.js
@@ -491,7 +491,7 @@ export default function createWebpackConfig(buildConfig, nwbPluginConfig = {}, u
     module: {
       loaders: createLoaders(server, loaders, userConfig.loaders, nwbPluginConfig)
     },
-    plugins: createPlugins(server, plugins, userConfig.plugins),
+    plugins: createPlugins(server, plugins, userConfig),
     resolve: merge({
       extensions: ['', '.web.js', '.js', '.jsx', '.json'],
       // Fall back to resolving runtime dependencies from nwb's dependencies,