Adding docs about adding custom config - see #8067

weaverryan · weaverryan · commit 62dd63e8c3aa · 2017-06-25T18:30:39.000-04:00
diff --git a/frontend.rst b/frontend.rst
@@ -59,6 +59,7 @@ Guides
 * :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
 * :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
 * :doc:`Adding custom loaders </frontend/encore/custom-loaders>`
+* :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
 
 Full API
 ........
diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst
@@ -0,0 +1,45 @@
+Advanced Webpack Config
+=======================
+
+Quite simply, Encore generates the Webpack configuration that's used in your
+``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
+`configuration options`_, because many can be easy added on your own. 
+
+For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
+modify the config it after fetching the it from Encore:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+
+    var Encore = require('@symfony/webpack-encore');
+
+    // ... all Encore config here
+
+    // fetch the config, then modify it!
+    var config = Encore.getWebpackConfig();
+    config.watchOptions = { poll: true, ignored: /node_modules/ };
+
+    // other examples: add an alias or extension
+    // config.resolve.alias.local = path.resolve(__dirname, './resources/src');
+    // config.resolve.extensions.push('json');
+    
+
+    // export the final config
+    module.exports = config;
+
+But be careful not to accidentally override any config from Encore:
+
+.. code-block:: javascript
+
+    // webpack.config.js
+    // ...
+
+    // GOOD - this modifies the config.resolve.extensions array
+    // config.resolve.extensions.push('json');
+
+    // BAD - this replaces any extensions added by Encore
+    // config.resolve.extensions = ['json'];
+
+.. _`configuration options`: https://webpack.js.org/configuration/
+.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
