updating Encore docs for 1.0

weaverryan · weaverryan · commit 1aba68d3c0e2 · 2021-01-28T11:27:20.000-05:00
diff --git a/frontend.rst b/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
diff --git a/frontend/encore/advanced-config.rst b/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``
diff --git a/frontend/encore/copy-files.rst b/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">`;
 
diff --git a/frontend/encore/dev-server.rst b/frontend/encore/dev-server.rst
@@ -8,14 +8,14 @@ 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
@@ -33,6 +33,40 @@ server SSL certificate:
     # Windows
     $ encore dev-server --https --pfx=%UserProfile%\.symfony\certs\default.p12
 
+To avoid repeating yourself, you can also update ``package.json`` to include
+these options automatically:
+
+.. code-block:: diff
+
+    {
+        ...
+        "scripts": {
+    -        "dev-server": "encore dev-server",
+    +        "dev-server": "encore dev-server --https --pfx=$HOME/.symfony/certs/default.p12 --allowed-hosts=mydomain.wip",
+            ...
+        }
+    }
+
+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:
+
+.. code-block:: diff
+
+    {
+        ...
+        "scripts": {
+    -        "dev-server": "encore dev-server",
+    +        "dev-server": "encore dev-server --port 8080 --disable-host-check",
+            ...
+        }
+    }
+
+.. caution::
+
+    Beware that `it's not recommended to disable host checking`_ in general, but
+    here it's required to solve the CORS issue.
+
 dev-server Options
 ------------------
 
@@ -69,49 +103,17 @@ method in your ``webpack.config.js`` file:
 Hot Module Replacement HMR
 --------------------------
 
-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:
-
-.. code-block:: terminal
-
-    $ ./node_modules/.bin/encore dev-server --hot
-
-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:
-
-.. code-block:: diff
+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>`).
 
-    {
-        ...
-        "scripts": {
-    -        "dev-server": "encore dev-server",
-    +        "dev-server": "encore dev-server --https --pfx=$HOME/.symfony/certs/default.p12 --allowed-hosts=mydomain.wip",
-            ...
-        }
-    }
-
-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:
-
-.. code-block:: diff
-
-    {
-        ...
-        "scripts": {
-    -        "dev-server": "encore dev-server",
-    +        "dev-server": "encore dev-server --port 8080 --disable-host-check",
-            ...
-        }
-    }
-
-.. caution::
-
-    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/
diff --git a/frontend/encore/installation.rst b/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.
diff --git a/frontend/encore/reactjs.rst b/frontend/encore/reactjs.rst
@@ -11,7 +11,7 @@ Using React? First add some dependencies with Yarn:
 .. code-block:: terminal
 
     $ yarn add @babel/preset-react --dev
-    $ yarn add react react-dom prop-types
+    $ yarn add react react-dom prop-types --dev
 
 Enable react in your ``webpack.config.js``:
 
diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst
diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.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/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)
diff --git a/frontend/encore/split-chunks.rst b/frontend/encore/split-chunks.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') }}
 
diff --git a/frontend/encore/url-loader.rst b/frontend/encore/url-loader.rst
