feature #14895 updating Encore docs for 1.0 (weaverryan)

This PR was squashed before being merged into the 5.2 branch.

Discussion
----------

updating Encore docs for 1.0

Hi!

I do an entire, quick read-through of the docs and updated for 1.0 (and modernized a few spots - like `var` -> `const` - symfony/recipes#886

Cheers!

Commits
-------

a85f968 updating Encore docs for 1.0

Author: weaverryan

.doctor-rst.yaml

@@ -88,6 +88,7 @@ whitelist:
         - '.. versionadded:: 1.3' # MakerBundle
         - '.. versionadded:: 1.8' # MakerBundle
         - '.. versionadded:: 1.6' # Flex in setup/upgrade_minor.rst
+        - '.. versionadded:: 1.0.0' # Encore
         - '0 => 123' # assertion for var_dumper - components/var_dumper.rst
         - '1 => "foo"' # assertion for var_dumper - components/var_dumper.rst
         - '123,' # assertion for var_dumper - components/var_dumper.rst

_build/redirection_map

@@ -511,3 +511,4 @@
 /messenger/message-recorder messenger/dispatch_after_current_bus
 /components/stopwatch https://github.com/symfony/stopwatch
 /service_container/3.3-di-changes https://symfony.com/doc/3.4/service_container/3.3-di-changes.html
+/frontend/encore/shared-entry /frontend/encore/split-chunks

frontend.rst

@@ -61,7 +61,6 @@ Optimizing
 * :doc:`Using a CDN </frontend/encore/cdn>`
 * :doc:`/frontend/encore/code-splitting`
 * :doc:`/frontend/encore/split-chunks`
-* :doc:`Creating a "Shared" entry for re-used modules </frontend/encore/shared-entry>`
 * :doc:`/frontend/encore/url-loader`
 
 Guides

frontend/encore/advanced-config.rst

@@ -12,12 +12,12 @@ To do that, modify the config after fetching it from Encore:
 
     // webpack.config.js
 
-    var Encore = require('@symfony/webpack-encore');
+    const Encore = require('@symfony/webpack-encore');
 
     // ... all Encore config here
 
     // fetch the config, then modify it!
-    var config = Encore.getWebpackConfig();
+    const config = Encore.getWebpackConfig();
 
     // add an extension
     config.resolve.extensions.push('json');
@@ -208,8 +208,8 @@ The following code is equivalent:
 The following loaders are configurable with ``configureLoaderRule()``:
   - ``javascript`` (alias ``js``)
   - ``css``
-  - ``images``
-  - ``fonts``
+  - ``images`` (but use ``configureImageRule()`` instead)
+  - ``fonts`` (but use ``configureFontRule()`` instead)
   - ``sass`` (alias ``scss``)
   - ``less``
   - ``stylus``

frontend/encore/copy-files.rst

@@ -16,7 +16,7 @@ To reference an image tag from inside a JavaScript file, *require* the file:
 
     // returns the final, public path to this file
     // path is relative to this file - e.g. assets/images/logo.png
-    const logoPath = require('../images/logo.png');
+    import logoPath from '../images/logo.png';
 
     let html = `<img src="${logoPath}" alt="ACME logo">`;
 

frontend/encore/dev-server.rst

@@ -8,31 +8,16 @@ While developing, instead of using ``yarn encore dev --watch``, you can use the
 
     $ yarn encore dev-server
 
-This builds and serves the front-end assets from a new server. This server runs at 
-``localhost:8080`` by default, meaning your build assets are available at ``localhost:8080/build``. 
-This server does not actually write the files to disk; instead it servers them from memory, 
+This builds and serves the front-end assets from a new server. This server runs at
+``localhost:8080`` by default, meaning your build assets are available at ``localhost:8080/build``.
+This server does not actually write the files to disk; instead it servers them from memory,
 allowing for hot module reloading.
 
-As a consequence, the ``link`` and ``script`` tags need to point to the new server. If you're using the 
-``encore_entry_script_tags()`` and ``encore_entry_link_tags()`` Twig shortcuts (or are 
-:ref:`processing your assets through entrypoints.json <load-manifest-files>` in some other way), 
+As a consequence, the ``link`` and ``script`` tags need to point to the new server. If you're using the
+``encore_entry_script_tags()`` and ``encore_entry_link_tags()`` Twig shortcuts (or are
+:ref:`processing your assets through entrypoints.json <load-manifest-files>` in some other way),
 you're done: the paths in your templates will automatically point to the dev server.
 
-Enabling HTTPS using the Symfony Web Server
--------------------------------------------
-
-If you're using the :doc:`Symfony web server </setup/symfony_server>` locally with HTTPS,
-you'll need to also tell the dev-server to use HTTPS. To do this, you can reuse the Symfony web
-server SSL certificate:
-
-.. code-block:: terminal
-
-    # Unix-based systems
-    $ yarn dev-server --https --pfx=$HOME/.symfony/certs/default.p12
-
-    # Windows
-    $ encore dev-server --https --pfx=%UserProfile%\.symfony\certs\default.p12
-
 dev-server Options
 ------------------
 
@@ -66,53 +51,65 @@ method in your ``webpack.config.js`` file:
 
     The ``Encore.configureDevServerOptions()`` method was introduced in Encore 0.28.4.
 
-Hot Module Replacement HMR
---------------------------
+Enabling HTTPS using the Symfony Web Server
+-------------------------------------------
+
+If you're using the :doc:`Symfony web server </setup/symfony_server>` locally with HTTPS,
+you'll need to also tell the dev-server to use HTTPS. To do this, you can reuse the Symfony web
+server SSL certificate:
+
+.. code-block:: javascript
 
-Encore *does* support `HMR`_ for :doc:`Vue.js </frontend/encore/vuejs>`, but
-does *not* work for styles anywhere at this time. To activate it, pass the ``--hot``
-option:
+    // webpack.config.js
+    // ...
+    const path = require('path');
+
+    Encore
+        // ...
+
+        .configureDevServerOptions(options => {
+            options.https = {
+                pfx: path.join(process.env.HOME, '.symfony/certs/default.p12'),
+            }
+        })
+
+Then make sure you run the ``dev-server`` with the ``--https`` option:
 
 .. code-block:: terminal
 
-    $ ./node_modules/.bin/encore dev-server --hot
+    $ yarn encore dev-server --https
 
-If you want to use SSL with self-signed certificates, add the ``--https``,
-``--pfx=``, and  ``--allowed-hosts`` options to the ``dev-server`` command in
-the ``package.json`` file:
+CORS Issues
+-----------
 
-.. code-block:: diff
+If you experience issues related to CORS (Cross Origin Resource Sharing), set
+the ``firewall`` option:
 
-    {
-        ...
-        "scripts": {
-    -        "dev-server": "encore dev-server",
-    +        "dev-server": "encore dev-server --https --pfx=$HOME/.symfony/certs/default.p12 --allowed-hosts=mydomain.wip",
-            ...
-        }
-    }
+.. code-block:: javascript
 
-If you experience issues related to CORS (Cross Origin Resource Sharing), add
-the ``--disable-host-check`` and ``--port`` options to the ``dev-server``
-command in the ``package.json`` file:
+    // webpack.config.js
+    // ...
+
+    Encore
+        // ...
 
-.. code-block:: diff
+        .configureDevServerOptions(options => {
+            options.firewall = false;
+        })
 
-    {
-        ...
-        "scripts": {
-    -        "dev-server": "encore dev-server",
-    +        "dev-server": "encore dev-server --port 8080 --disable-host-check",
-            ...
-        }
-    }
+Hot Module Replacement HMR
+--------------------------
 
-.. caution::
+Hot module replacement is a superpower of the ``dev-server`` where styles and
+(in some cases) JavaScript can automatically update without needing to reload
+your page. HMR works automatically with CSS (as long as you're using the
+``dev-server`` and Encore 1.0 or higher) but only works with some JavaScript
+(like :doc:`Vue.js </frontend/encore/vuejs>`).
 
-    Beware that `it's not recommended to disable host checking`_ in general, but
-    here it's required to solve the CORS issue.
+.. versionadded:: 1.0.0
 
+    Before Encore 1.0, you needed to pass a ``--hot`` flag at the command line
+    to enable HMR. You also needed to disable CSS extraction to enable HMR for
+    CSS. That is no longer needed.
 
 .. _`webpack-dev-server`: https://webpack.js.org/configuration/dev-server/
-.. _`HMR`: https://webpack.js.org/concepts/hot-module-replacement/
-.. _`it's not recommended to disable host checking`: https://webpack.js.org/configuration/dev-server/#devserverdisablehostcheck

frontend/encore/installation.rst

@@ -54,7 +54,7 @@ is the main config file for both Webpack and Webpack Encore:
 
 .. code-block:: javascript
 
-    var Encore = require('@symfony/webpack-encore');
+    const Encore = require('@symfony/webpack-encore');
 
     // Manually configure the runtime environment if not already configured yet by the "encore" command.
     // It's useful when you use tools that rely on webpack.config.js file.

frontend/encore/shared-entry.rst

@@ -19,8 +19,6 @@ application: it will *require* all of the dependencies it needs (e.g. jQuery or
 
     import './styles/app.css';
 
-    // import $ from 'jquery';
-
 Encore's job (via Webpack) is simple: to read and follow *all* of the ``require()``
 statements and create one final ``app.js`` (and ``app.css``) that contains *everything*
 your app needs. Encore can do a lot more: minify files, pre-process Sass/LESS,
@@ -35,7 +33,7 @@ of your project. It already holds the basic config you need:
 .. code-block:: javascript
 
     // webpack.config.js
-    var Encore = require('@symfony/webpack-encore');
+    const Encore = require('@symfony/webpack-encore');
 
     Encore
         // directory where compiled assets will be stored
@@ -130,6 +128,8 @@ filename(s) to render. This file is *especially* useful because you can
 :doc:`enable versioning </frontend/encore/versioning>` or
 :doc:`point assets to a CDN </frontend/encore/cdn>` without making *any* changes to your
 template: the paths in ``entrypoints.json`` will always be the final, correct paths.
+And if you use :doc:`splitEntryChunks() </frontend/encore/split-chunks>` (where Webpack splits the output into even
+more files), all the necessary ``script`` and ``link`` tags will render automatically.
 
 If you're *not* using Symfony, you can ignore the ``entrypoints.json`` file and
 point to the final, built file directly. ``entrypoints.json`` is only required for
@@ -147,13 +147,13 @@ some optional features.
 Requiring JavaScript Modules
 ----------------------------
 
-Webpack is a module bundler, which means that you can ``require`` other JavaScript
+Webpack is a module bundler, which means that you can ``import`` other JavaScript
 files. First, create a file that exports a function:
 
 .. code-block:: javascript
 
     // assets/greet.js
-    module.exports = function(name) {
+    export default function(name) {
         return `Yo yo ${name} - welcome to Encore!`;
     };
 
@@ -163,19 +163,19 @@ We'll use jQuery to print this message on the page. Install it via:
 
     $ yarn add jquery --dev
 
-Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
+Great! Use ``import`` to import ``jquery`` and ``greet.js``:
 
 .. code-block:: diff
 
     // assets/app.js
     // ...
 
     + // loads the jquery package from node_modules
-    + var $ = require('jquery');
+    + import jquery from 'jquery';
 
     + // import the function from greet.js (the .js extension is optional)
     + // ./ (or ../) means to look for a local file
-    + var greet = require('./greet');
+    + import greet from './greet';
 
     + $(document).ready(function() {
     +     $('body').prepend('<h1>'+greet('jill')+'</h1>');
@@ -185,37 +185,6 @@ That's it! If you previously ran ``encore dev --watch``, your final, built files
 have already been updated: jQuery and ``greet.js`` have been automatically
 added to the output file (``app.js``). Refresh to see the message!
 
-The import and export Statements
---------------------------------
-
-Instead of using ``require()`` and ``module.exports`` like shown above, JavaScript
-provides an alternate syntax based on the `ECMAScript 6 modules`_ that includes
-the ability to use dynamic imports.
-
-To export values using the alternate syntax, use ``export``:
-
-.. code-block:: diff
-
-    // assets/greet.js
-    - module.exports = function(name) {
-    + export default function(name) {
-        return `Yo yo ${name} - welcome to Encore!`;
-    };
-
-To import values, use ``import``:
-
-.. code-block:: diff
-
-    // assets/app.js
-    - require('../styles/app.css');
-    + import './styles/app.css';
-
-    - var $ = require('jquery');
-    + import $ from 'jquery';
-
-    - var greet = require('./greet');
-    + import greet from './greet';
-
 .. _multiple-javascript-entries:
 
 Page-Specific JavaScript or CSS (Multiple Entries)
@@ -357,5 +326,4 @@ Encore supports many more features! For a full list of what you can do, see
 `Encore's index.js file`_. Or, go back to :ref:`list of Encore articles <encore-toc>`.
 
 .. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js
-.. _`ECMAScript 6 modules`: https://hacks.mozilla.org/2015/08/es6-in-depth-modules/
 .. _`WebpackEncoreBundle Configuration`: https://github.com/symfony/webpack-encore-bundle#configuration

frontend/encore/simple-example.rst

@@ -23,9 +23,10 @@ To enable this, call ``splitEntryChunks()``:
 
 
 Now, each output file (e.g. ``homepage.js``) *may* be split into multiple file
-(e.g. ``homepage.js``, ``vendor~homepage.js``). This means that you *may* need to
-include *multiple* ``script`` tags (or ``link`` tags for CSS) in your template.
-Encore creates an :ref:`entrypoints.json <encore-entrypointsjson-simple-description>`
+(e.g. ``homepage.js`` & ``vendors-node_modules_jquery_dist_jquery_js.js`` - the
+filename of the second will be less obvious when you build for production). This
+means that you *may* need to include *multiple* ``script`` tags (or ``link`` tags
+for CSS) in your template. Encore creates an :ref:`entrypoints.json <encore-entrypointsjson-simple-description>`
 file that lists exactly which CSS and JavaScript files are needed for each entry.
 
 If you're using the ``encore_entry_link_tags()`` and ``encore_entry_script_tags()``
@@ -37,9 +38,9 @@ tags as needed:
 
     {#
         May now render multiple script tags:
-            <script src="/build/runtime.js"></script>
-            <script src="/build/vendor~homepage.js"></script>
-            <script src="/build/homepage.js"></script>
+            <script src="/build/runtime.js" defer></script>
+            <script src="/build/vendors-node_modules_jquery_dist_jquery_js.js" defer></script>
+            <script src="/build/homepage.js" defer></script>
     #}
     {{ encore_entry_script_tags('homepage') }}