From 3d9905e093925ba681810a5891c5f5c25f35db2d Mon Sep 17 00:00:00 2001 From: Pierre du Plessis Date: Sat, 24 Jun 2017 15:44:42 +0200 Subject: [PATCH 01/10] Add docs for custom loaders --- frontend.rst | 1 + frontend/encore/custom-loaders.rst | 39 ++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 frontend/encore/custom-loaders.rst diff --git a/frontend.rst b/frontend.rst index 4db7b1d0f4d..662870c405a 100644 --- a/frontend.rst +++ b/frontend.rst @@ -58,6 +58,7 @@ Guides * :doc:`jQuery and Legacy Applications ` * :doc:`Passing Information from Twig to JavaScript ` * :doc:`webpack-dev-server and Hot Module Replacement (HMR) ` +* :doc:`Adding custom loaders ` Full API ........ diff --git a/frontend/encore/custom-loaders.rst b/frontend/encore/custom-loaders.rst new file mode 100644 index 00000000000..c9639bbdc89 --- /dev/null +++ b/frontend/encore/custom-loaders.rst @@ -0,0 +1,39 @@ +Adding Custom Loaders +===================== + +Encore already comes with a variety of different loaders that you can use out of the box, +but if there is a specific loader that you want to use that is not currently supported, then you +can easily 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`_, you can just ``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:: twig + + Encore + // ... + .addLoader( + { + test: /\.handlebars$/, + loader: 'handlebars-loader', + query: { + helperDirs: [ + __dirname + '/helpers1', + __dirname + '/helpers2', + ], + partialDirs: [ + path.join(__dirname, 'templates', 'partials') + ] + } + } + ) \ No newline at end of file From 0ff1c3cf359095e49b7ef19297af9986661b43df Mon Sep 17 00:00:00 2001 From: Pierre du Plessis Date: Sat, 24 Jun 2017 16:04:19 +0200 Subject: [PATCH 02/10] Add missing link to handlebars-loader --- frontend/encore/custom-loaders.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/frontend/encore/custom-loaders.rst b/frontend/encore/custom-loaders.rst index c9639bbdc89..5bd395c10e5 100644 --- a/frontend/encore/custom-loaders.rst +++ b/frontend/encore/custom-loaders.rst @@ -36,4 +36,6 @@ additional information your need for the loader ] } } - ) \ No newline at end of file + ) + +.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader \ No newline at end of file From 62dd63e8c3aae419613b8af3b9bf419edaaad6cf Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 17:51:33 -0400 Subject: [PATCH 03/10] Adding docs about adding custom config - see #8067 --- frontend.rst | 1 + frontend/encore/advanced-config.rst | 45 +++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 frontend/encore/advanced-config.rst diff --git a/frontend.rst b/frontend.rst index 662870c405a..18708892a62 100644 --- a/frontend.rst +++ b/frontend.rst @@ -59,6 +59,7 @@ Guides * :doc:`Passing Information from Twig to JavaScript ` * :doc:`webpack-dev-server and Hot Module Replacement (HMR) ` * :doc:`Adding custom loaders ` +* :doc:`Advanced Webpack Configuration ` Full API ........ diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst new file mode 100644 index 00000000000..a6466662503 --- /dev/null +++ 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 \ No newline at end of file From 8b0a22afb9310dec7e0834da57d58cdfeae60312 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:00:12 -0400 Subject: [PATCH 04/10] [Encore] Adding docs about deploying to a subdirectory - see #8069 --- frontend.rst | 5 +++++ frontend/encore/faq.rst | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 frontend/encore/faq.rst diff --git a/frontend.rst b/frontend.rst index 18708892a62..0f6beadf5d6 100644 --- a/frontend.rst +++ b/frontend.rst @@ -61,6 +61,11 @@ Guides * :doc:`Adding custom loaders ` * :doc:`Advanced Webpack Configuration ` +Troubleshooting +............... + +* :doc:`FAQ ` + Full API ........ diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst new file mode 100644 index 00000000000..9a04396a9cb --- /dev/null +++ b/frontend/encore/faq.rst @@ -0,0 +1,39 @@ +Frequently Asked Questions +========================== + +My App Lives under a Subdirectory +--------------------------------- + + My app doesn't live at the root of my web server: it lives under a subdirectory + (e.g. ``/myAppSubdir/``). How can I configure Encore to work? + +If your app lives under a subdirectory, you just need to include 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 `, +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" + } From a099bff51969f815d664b298b5dc0caf8e30149b Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:10:54 -0400 Subject: [PATCH 05/10] Documenting (better) how to expose global variables - see #8071 --- frontend/encore/legacy-apps.rst | 44 ++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/frontend/encore/legacy-apps.rst b/frontend/encore/legacy-apps.rst index 7c0d189f807..4c9350dba37 100644 --- 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 pn 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``. From 807b83fa9f3dd505e09a74c29e6531bed9bf8add Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:25:16 -0400 Subject: [PATCH 06/10] [Encore] Documenting addPlugin - see #8070 --- frontend.rst | 2 +- frontend/encore/custom-loaders-plugins.rst | 64 ++++++++++++++++++++++ frontend/encore/custom-loaders.rst | 41 -------------- 3 files changed, 65 insertions(+), 42 deletions(-) create mode 100644 frontend/encore/custom-loaders-plugins.rst delete mode 100644 frontend/encore/custom-loaders.rst diff --git a/frontend.rst b/frontend.rst index 0f6beadf5d6..9dbe006fe93 100644 --- a/frontend.rst +++ b/frontend.rst @@ -58,7 +58,7 @@ Guides * :doc:`jQuery and Legacy Applications ` * :doc:`Passing Information from Twig to JavaScript ` * :doc:`webpack-dev-server and Hot Module Replacement (HMR) ` -* :doc:`Adding custom loaders ` +* :doc:`Adding custom loaders & plugins ` * :doc:`Advanced Webpack Configuration ` Troubleshooting diff --git a/frontend/encore/custom-loaders-plugins.rst b/frontend/encore/custom-loaders-plugins.rst new file mode 100644 index 00000000000..701333247b2 --- /dev/null +++ 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/custom-loaders.rst b/frontend/encore/custom-loaders.rst deleted file mode 100644 index 5bd395c10e5..00000000000 --- a/frontend/encore/custom-loaders.rst +++ /dev/null @@ -1,41 +0,0 @@ -Adding Custom Loaders -===================== - -Encore already comes with a variety of different loaders that you can use out of the box, -but if there is a specific loader that you want to use that is not currently supported, then you -can easily 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`_, you can just ``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:: twig - - Encore - // ... - .addLoader( - { - test: /\.handlebars$/, - loader: 'handlebars-loader', - query: { - helperDirs: [ - __dirname + '/helpers1', - __dirname + '/helpers2', - ], - partialDirs: [ - path.join(__dirname, 'templates', 'partials') - ] - } - } - ) - -.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader \ No newline at end of file From a0982ece904699c9ba0fa82b4677aca46577f7be Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:40:25 -0400 Subject: [PATCH 07/10] [Encore] Adding more FAQs for #8072 --- frontend.rst | 2 +- frontend/encore/faq.rst | 28 +++++++++++++++++++++------- frontend/encore/shared-entry.rst | 2 ++ 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/frontend.rst b/frontend.rst index 9dbe006fe93..f9f72d007c8 100644 --- a/frontend.rst +++ b/frontend.rst @@ -64,7 +64,7 @@ Guides Troubleshooting ............... -* :doc:`FAQ ` +* :doc:`FAQ & Common Issues ` Full API ........ diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst index 9a04396a9cb..4aa643ea3f8 100644 --- a/frontend/encore/faq.rst +++ b/frontend/encore/faq.rst @@ -1,14 +1,11 @@ -Frequently Asked Questions -========================== +FAQ and Common Issues +===================== My App Lives under a Subdirectory --------------------------------- - My app doesn't live at the root of my web server: it lives under a subdirectory - (e.g. ``/myAppSubdir/``). How can I configure Encore to work? - -If your app lives under a subdirectory, you just need to include that when calling -``Encore.setPublicPrefix()``: +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 @@ -37,3 +34,20 @@ final paths: "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 ` +but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the +information about the :ref:`script tags ` in that section. diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst index e4a2678216f..c883f6ef390 100644 --- 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 From f5c22a691802d53d073602ac1b1646f3b0f61769 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:45:40 -0400 Subject: [PATCH 08/10] minor rewording --- frontend/encore/simple-example.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst index 3b3b64252ae..93ea8e9dc2a 100644 --- 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. From f8461d3598740148ebb438451b8402aaa5406686 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 25 Jun 2017 18:54:01 -0400 Subject: [PATCH 09/10] adding anotehr faq for old packages without a main script --- frontend/encore/faq.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst index 4aa643ea3f8..bad07d40270 100644 --- a/frontend/encore/faq.rst +++ b/frontend/encore/faq.rst @@ -51,3 +51,30 @@ Uncaught ReferenceError: webpackJsonp is not defined If you get this error, it's probably because you've just added a :doc:`shared entry ` but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the information about the :ref:`script tags ` 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'); From 15e816e040fa0e64f48efdea6dc7d0e940775f5e Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Mon, 26 Jun 2017 14:58:51 -0400 Subject: [PATCH 10/10] Tweaks thanks to Javier --- frontend/encore/advanced-config.rst | 5 ++--- frontend/encore/legacy-apps.rst | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/frontend/encore/advanced-config.rst b/frontend/encore/advanced-config.rst index a6466662503..3854c425dac 100644 --- a/frontend/encore/advanced-config.rst +++ b/frontend/encore/advanced-config.rst @@ -3,10 +3,10 @@ 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. +`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 it after fetching the it from Encore: +modify the config after fetching the it from Encore: .. code-block:: javascript @@ -23,7 +23,6 @@ modify the config it after fetching the it from Encore: // 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; diff --git a/frontend/encore/legacy-apps.rst b/frontend/encore/legacy-apps.rst index 4c9350dba37..184877f7c94 100644 --- a/frontend/encore/legacy-apps.rst +++ b/frontend/encore/legacy-apps.rst @@ -79,7 +79,7 @@ loaded on every page with the following content: .. tip:: - The ``global`` variable is a special way of setting things pn the ``window`` + 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``.