Document the new in-app webpack configuration files and API

Author: javan

README.md

@@ -268,10 +268,9 @@ precedence over the ones already set in the configuration file.
 ### Webpack
 
 Webpacker gives you a default set of configuration files for test, development and
-production environments. They all live together with the shared
-points in `config/webpack/*.js`.
-
-![screen shot 2017-05-23 at 19 56 18](https://cloud.githubusercontent.com/assets/771039/26371229/0983add2-3ff2-11e7-9dc3-d9c2c1094032.png)
+production environments in `config/webpack/*.js`. You can configure each individual
+environment in their respective files or configure them all in the base
+`config/webpack/environment.js` file.
 
 By default, you shouldn't have to make any changes to `config/webpack/*.js`
 files since it's all standard production-ready configuration. However,
@@ -280,28 +279,57 @@ if you do need to customize or add a new loader, this is where you would go.
 
 ### Loaders
 
-Webpack enables the use of loaders to preprocess files. This allows you to
-bundle any static resource way beyond JavaScript. All base loaders
-that ship with webpacker are located inside `config/webpack/loaders`.
-
-If you want to add a new loader, for example, to process `json` files via webpack:
+You can add additional loaders beyond the base set that webpacker provides by
+adding it to your environment. We'll use `json-loader` as an example:
 
 ```
 yarn add json-loader
 ```
 
-And create a `json.js` file inside `loaders` directory:
-
 ```js
-module.exports = {
+// config/webpack/environment.js
+const { environment } = require('webpacker')
+
+environment.loaders.add('json', {
   test: /\.json$/,
   use: 'json-loader'
-}
+})
+
+module.exports = environment
 ```
 
 Finally add `.json` to the list of extensions in `config/webpacker.yml`. Now if you `import()` any `.json` files inside your javascript
 they will be processed using `json-loader`. Voila!
 
+You can also modify the loaders that webpacker pre-configures for you. We'll update
+the `babel` loader as an example:
+
+```js
+// config/webpack/environment.js
+const { environment } = require('webpacker')
+
+// Update an option directly
+const babelLoader = environment.loaders.get('babel')
+babelLoader.options.cacheDirectory = false
+
+module.exports = environment
+```
+
+### Plugins
+
+The process for adding or modifying webpack plugins is the same as the process
+for loaders above:
+```js
+// config/webpack/environment.js
+const { environment } = require('webpacker')
+
+// Get a pre-configured plugin
+environment.plugins.get("ExtractText") // Is an ExtractTextPlugin instance
+// Add an additional plugin of your choosing
+environment.plugins.add('Fancy', new MyFancyWebpackPlugin)
+
+module.exports = environment
+```
 
 ### Paths
 
@@ -685,41 +713,21 @@ You can follow same steps for Angular too.
 
 The CommonsChunkPlugin is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in the cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from the cache, rather than being forced to load a larger bundle whenever a new page is visited.
 
-Create a `app-config.js` file inside `config/webpack` and in that file add:
+Add the plugins in `config/webpack/environment.js`:
 
 ```js
-  module.exports = {
-    plugins: [
-      // Creates a common vendor.js with all shared modules
-      new webpack.optimize.CommonsChunkPlugin({
-        name: 'vendor',
-        minChunks: (module) => {
-          // this assumes your vendor imports exist in the node_modules directory
-          return module.context && module.context.indexOf('node_modules') !== -1;
-        }
-      }),
-      // Webpack code chunk - manifest.js
-      new webpack.optimize.CommonsChunkPlugin({
-        name: 'manifest',
-        minChunks: Infinity
-      })
-    ]
+environment.plugins.add('CommonsChunkVendor', new webpack.optimize.CommonsChunkPlugin({
+  name: 'vendor',
+  minChunks: (module) => {
+    // this assumes your vendor imports exist in the node_modules directory
+    return module.context && module.context.indexOf('node_modules') !== -1;
   }
-```
+}))
 
-You can add this in `shared.js` too but we are doing this to ensure smoother upgrades.
-
-```js
-// config/webpack/shared.js
-// .... rest of the config
-
-const appConfig = require('./app-config.js')
-
-plugins: appConfig.plugins.concat([
-
-  // ...existing plugins
-
-])
+environment.plugins.add('CommonsChunkManifest', new webpack.optimize.CommonsChunkPlugin({
+  name: 'manifest',
+  minChunks: Infinity
+}))
 ```
 
 Now, add these files to your `layouts/application.html.erb`:
@@ -833,16 +841,7 @@ yarn remove prop-types
 }
 ```
 
-3. Add a new loader `config/webpack/loaders/typescript.js`:
-
-``` js
-module.exports = {
-  test: /.(ts|tsx)$/,
-  loader: 'ts-loader'
-}
-```
-
-4. Finally add `.tsx` to the list of extensions in `config/webpacker.yml`
+3. Finally add `.tsx` to the list of extensions in `config/webpacker.yml`
 and rename your generated `hello_react.js` using react installer
 to `hello_react.tsx` and make it valid typescript and now you can use
 typescript, JSX with React.
@@ -859,10 +858,10 @@ you would need to follow these steps to add HTML templates support:
 yarn add html-loader
 ```
 
-2. Add html-loader to `config/webpacker/loaders/html.js`
+2. Add html-loader to `config/webpack/environment.js`
 
 ```js
-module.exports = {
+environment.loaders.add('html', {
   test: /\.html$/,
   use: [{
     loader: 'html-loader',
@@ -874,7 +873,7 @@ module.exports = {
       customAttrAssign: [ /\)?\]?=/ ]
     }
   }]
-}
+})
 ```
 
 3. Add `.html` to `config/webpacker.yml`
@@ -921,48 +920,6 @@ export class AppComponent {
 
 That's all. Voila!
 
-
-### CSS modules
-
-To enable CSS modules, you would need to update `config/webpack/loaders/sass.js`
-file, particularly `css-loader`:
-
-```js
-// Add css-modules
-
-{
-  loader: 'css-loader',
-  options: {
-    minimize: env.NODE_ENV === 'production',
-    modules: true,
-    localIdentName: '[path][name]__[local]--[hash:base64:5]'
-  }
-}
-```
-
-That's all. Now, you can use CSS modules within your JS app:
-
-```js
-import React from 'react'
-import styles from './styles'
-
-const Hello = props => (
-  <div className={styles.wrapper}>
-    <img src={clockIcon} alt="clock" className={styles.img} />
-    <h5 className={styles.name}>
-      {props.message} {props.name}!
-    </h5>
-  </div>
-)
-```
-
-
-### CSS-Next
-
-[css-next](http://cssnext.io/) is supported out-of-box in Webpacker allowing the use of
-latest CSS features, today.
-
-
 ### Ignoring swap files
 
 If you are using vim or emacs and want to ignore certain files you can add `ignore-loader`:
@@ -1068,7 +1025,7 @@ yarn add dotenv
 ```
 
 ```javascript
-// config/webpack/shared.js
+// config/webpack/environment.js
 
 ...
 const dotenv = require('dotenv');
@@ -1097,44 +1054,6 @@ If you'd like to pass custom variables to the compiler, use `Webpack::Compiler.e
 Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
 ```
 
-## Extending
-
-We suggest you don't directly overwrite the provided configuration files
-and extend instead for smoother upgrades. Here is one way to do it:
-
-Create a `app-config.js` file inside `config/webpack`, and in that add:
-
-```js
-module.exports = {
-  production: {
-    plugins: [
-      // ... Add plugins
-    ]
-  },
-
-  development: {
-    output: {
-      // ... Custom output path
-    }
-  }
-}
-```
-
-```js
-// config/webpack/production.js
-
-const { plugins } = require('./app-config.js')
-
-plugins: appConfig.plugins.concat([
-
-  // ...existing plugins
-
-])
-```
-
-But this could be done million other ways.
-
-
 ## Deployment
 
 Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`. If you are not using sprockets you