symfony · weaverryan · Jun 26, 2017 · Jun 24, 2017 · Jun 24, 2017 · Jun 25, 2017
diff --git a/frontend.rst b/frontend.rst
@@ -58,6 +58,13 @@ Guides
 * :doc:`jQuery and Legacy Applications </frontend/encore/legacy-apps>`
 * :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 & plugins </frontend/encore/custom-loaders-plugins>`
+* :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
+
+Troubleshooting
+...............
+
+* :doc:`FAQ & Common Issues </frontend/encore/faq>`

 Full API
 ........

diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst
@@ -0,0 +1,44 @@
+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 easily added on your own.
+
+For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
+modify the config 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
diff --git a/frontend/encore/custom-loaders-plugins.rst b/frontend/encore/custom-loaders-plugins.rst
@@ -0,0 +1,64 @@
+Adding Custom Loaders & Plugins
+===============================
+
+Adding Custom Loaders
+---------------------
+
+Encore already comes with a variety of different loaders out of the box,
+but if there is a specific loader that you want to use that is not currently supported, you
+can add your own loader through the ``addLoader`` function.
+The ``addLoader`` takes any valid webpack rules config.
+
+If, for example, you want to add the `handlebars-loader`_, call ``addLoader`` with
+your loader config
+
+.. code-block:: javascript
+
+    Encore
+        // ...
+        .addLoader({ test: /\.handlebars$/, loader: 'handlebars-loader' })
+    ;
+
+Since the loader config accepts any valid Webpack rules object, you can pass any
+additional information your need for the loader
+
+.. code-block:: javascript
+
+    Encore
+        // ...
+        .addLoader({
+            test: /\.handlebars$/,
+		    loader: 'handlebars-loader',
+		    query: {
+			    helperDirs: [
+				    __dirname + '/helpers1',
+				    __dirname + '/helpers2',
+                ],
+                partialDirs: [
+                    path.join(__dirname, 'templates', 'partials')
+                ]
+		    }
+        })
+    ;
+
+Adding Custom Plugins
+---------------------
+
+Encore uses a variety of different `plugins`_ internally. But, you can add your own
+via the ``addPlugin()`` method. For example, if you use `Moment.js`_, you might want
+to use the `IgnorePlugin`_ (see `moment/moment#2373`_):
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        + .addPlugin(new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/))
+    ;
+
+.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader
+.. _`plugins`: https://webpack.js.org/plugins/
+.. _`Moment.js`: https://momentjs.com/
+.. _`IgnorePlugin`: https://webpack.js.org/plugins/ignore-plugin/
+.. _`moment/moment#2373`: https://github.com/moment/moment/issues/2373
diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst
@@ -0,0 +1,80 @@
+FAQ and Common Issues
+=====================
+
+My App Lives under a Subdirectory
+---------------------------------
+
+If your app does not live at the root of your web server (i.e. it lives under a subdirectory,
+like ``/myAppSubdir``), you just need to configure that when calling ``Encore.setPublicPrefix()``:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        .setOutputPath('web/build/')
+
+        - .setPublicPath('/build')
+        + // this is your *true* public path
+        + .setPublicPath('/myAppSubdir/build')
+
+        + // this is now needed so that your manifest.json keys are still `build/foo.js`
+        + // i.e. you won't need to change anything in your Symfony app
+        + config.setManifestKeyPrefix('build')
+    ;
+
+If you're :ref:`processing your assets through manifest.json <load-manifest-files>`,
+you're done! The ``manifest.json`` file will now include the subdirectory in the
+final paths:
+
+.. code-block:: json
+
+    {
+        "build/app.js": "/myAppSubdir/build/app.123abc.js",
+        "build/dashboard.css": "/myAppSubdir/build/dashboard.a4bf2d.css"
+    }
+
+"jQuery is not defined" or "$ is not defined"
+---------------------------------------------
+
+This error happens when your code (or some library that you are using) expects ``$``
+or ``jQuery`` to be a global variable. But, when you use Webpack and ``require('jquery')``,
+no global variables are set.
+
+The fix depends on if the error is happening in your code or inside some third-party
+code that you're using. See :doc:`/frontend/encore/legacy-apps` for the fix.
+
+Uncaught ReferenceError: webpackJsonp is not defined
+----------------------------------------------------
+
+If you get this error, it's probably because you've just added a :doc:`shared entry </frontend/encore/shared-entry>`
+but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the
+information about the :ref:`script tags <encore-shared-entry-script>` in that section.
+
+This dependency was not found: some-module in ./path/to/file.js
+---------------------------------------------------------------
+
+Usually, after you install a package via yarn, you can require / import it to use
+it. For example, after running ``yarn add respond.js``, you try to require that module:
+
+.. code-block:: javascript
+
+    require('respond.js');
+
+But, instead of working, you see an error:
+
+    This dependency was not found:
+
+    * respond.js in ./app/Resources/assets/js/app.js
+
+Typically, a package will "advertise" its "main" file by adding a ``main`` key to
+its ``package.json``. But sometimes, old libraries won't have this. Instead, you'll
+need to specifically require the file you need. In this case, the file you should
+use is located at ``node_modules/respond.js/dest/respond.src.js``. You can require
+this via:
+
+.. code-block:: javascript
+
+    // require a non-minified file whenever possible
+    require('respond.js/dest/respond.src.js');
diff --git a/frontend/encore/legacy-apps.rst b/frontend/encore/legacy-apps.rst
@@ -1,6 +1,21 @@
 jQuery and Legacy Applications
 ==============================

+Inside Webpack, when you require a module, it does *not* (usually) set a global variable.
+Instead, it just returns a value:
+
+.. code-block:: javascript
+
+    // this loads jquery, but does *not* set a global $ or jQuery variable
+    const $ = require('jquery');
+
+In practice, this will cause problems with some outside libraries that *rely* on
+jQuery to be global. It will be a problem if some of *your* JavaScript isn't being
+processed through Webpack (e.g. you have some JavaScript in your templates).
+
+Using Libraries that Expect jQuery to be Global
+-----------------------------------------------
+
 Some legacy JavaScript applications use programming practices that don't play
 well with the new practices promoted by Webpack. The most common of these
 problems is using code (e.g. jQuery plugins) that assume that jQuery is already
@@ -27,7 +42,7 @@ So, when working with legacy applications, you may need to add the following to
    +     .autoProvidejQuery()
    ;

-Internally, this ``autoProvidejQuery()`` method uses the ``autoProvideVariables()``
+Internally, this ``autoProvidejQuery()`` method calls the ``autoProvideVariables()``
 method from Encore. In practice, it's equivalent to doing:

 .. code-block:: javascript
@@ -38,16 +53,33 @@ method from Encore. In practice, it's equivalent to doing:
        .autoProvideVariables({
            $: 'jquery',
            jQuery: 'jquery'
+            'window.jQuery': 'jquery',
        })
        // ...
    ;

+Accessing jQuery from outside of Webpack JavaScript Files
+---------------------------------------------------------
+
 If you also need to provide access to ``$`` and ``jQuery`` variables outside of
-JavaScript files processed by Webpack, you must create the global variables
-yourself in some file loaded before the legacy JavaScript code. For example, you
-can define a ``common.js`` file processed by Webpack and loaded in every page
-with the following content:
+JavaScript files processed by Webpack (e.g. JavaScript that still lives in your
+templates), you need to manually set these as global variables in some JavaScript
+file that is loaded before your legacy code.
+
+For example, you could define a ``common.js`` file that's processed by Webpack and
+loaded on every page with the following content:

 .. code-block:: javascript

-    window.$ = window.jQuery = require('jquery');
+    // require jQuery normally
+    const $ = require('jquery');
+
+    // create global $ and jQuery variables
+    global.$ = global.jQuery = $;
+
+.. tip::
+
+    The ``global`` variable is a special way of setting things in the ``window``
+    variable. In a web context, using ``global`` and ``window`` are equivalent,
+    except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
+    In other words, use ``global``.
diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst
@@ -27,6 +27,8 @@ that's included on every page:
 As soon as you make this change, you need to include two extra JavaScript files
 on your page before any other JavaScript file:

+.. _encore-shared-entry-script:
+
 .. code-block:: twig

    <!-- these two files now must be included in every page -->

diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
@@ -72,7 +72,7 @@ To build the assets, use the ``encore`` executable:

 .. note::

-    Restart ``encore`` each time you update your ``webpack.config.js`` file.
+    Re-run ``encore`` each time you update your ``webpack.config.js`` file.

 Actually, to use ``enableSassLoader()``, you'll need to install a few
 more packages. But Encore will tell you *exactly* what you need.