more work on encore

Author: weaverryan

frontend/encore/babel.rst

@@ -2,8 +2,8 @@ Configuring Babel
 =================
 
 `Babel`_ is automatically configured for all ``.js`` and ``.jsx`` files via the
-``babel-loader`` with sensible defaults (e.g. with the ``env`` preset and
-``react`` if requested).
+``babel-loader`` with sensible defaults (e.g. with the ``@babel/preset-env`` and
+``@babel/preset-react`` if requested).
 
 Need to extend the Babel configuration further? The easiest way is via
 ``configureBabel()``:
@@ -16,17 +16,37 @@ Need to extend the Babel configuration further? The easiest way is via
     Encore
         // ...
 
-        // first, install any presets you want to use (e.g. yarn add babel-preset-es2017)
-        // then, modify the default Babel configuration
         .configureBabel(function(babelConfig) {
             // add additional presets
-            babelConfig.presets.push('es2017');
+            // babelConfig.presets.push('@babel/preset-flow');
 
             // no plugins are added by default, but you can add some
             // babelConfig.plugins.push('styled-jsx/babel');
+        }, {
+            // node_modules is not processed through Babel by default
+            // but you can whitelist specific modules to process
+            // include_node_modules: ['foundation-sites']
+
+            // or completely control the exclude
+            // exclude: /bower_components/
         })
     ;
 
+Configuring Browser Targets
+---------------------------
+
+The ``@babel/preset-env`` preset rewrites your JavaScript so that the final syntax
+will work in whatever browsers you want. To configure the browsers that you need
+to support, see :ref:`browserslist_package_config`.
+
+After change our "browerslist" config, you will need to manually remove the babel
+cache directory:
+
+.. code-block:: terminal
+
+    $ On Unix run this command. On Windows, clear this directory manually
+    $ rm -rf node_modules/.cache/babel-loader/
+
 Creating a .babelrc File
 ------------------------
 
@@ -37,21 +57,7 @@ Babel, but it has a downside: as soon as a ``.babelrc`` file is present,
 if you call ``Encore.enableReactPreset()``, the ``react`` preset will *not*
 automatically be added to Babel: you must add it yourself in ``.babelrc``.
 
-An example ``.babelrc`` file might look like this:
-
-.. code-block:: json
-
-    {
-        presets: [
-            ['env', {
-                modules: false,
-                targets: {
-                    browsers: '> 1%',
-                    uglify: true
-                },
-                useBuiltIns: true
-            }]
-        ]
-    }
+As soon as a ``.babelrc`` file is present, it will take priority over the Babel
+configuration added by Encore.
 
 .. _`Babel`: http://babeljs.io/

frontend/encore/css-preprocessors.rst

@@ -1,29 +1,7 @@
-CSS Preprocessors: Sass, LESS, etc.
-===================================
+CSS Preprocessors: Sass, LESS, Stylus, etc.
+===========================================
 
-Using Sass
-----------
-
-To use the Sass pre-processor, install the dependencies:
-
-.. code-block:: terminal
-
-    $ yarn add --dev sass-loader node-sass
-
-And enable it in ``webpack.config.js``:
-
-.. code-block:: javascript
-
-    // webpack.config.js
-    // ...
-
-    Encore
-        // ...
-        .enableSassLoader()
-    ;
-
-That's it! All files ending in ``.sass`` or ``.scss`` will be pre-processed. You
-can also pass options to ``sass-loader``:
+To use the Sass, LESS or Stylus pre-processors, enable the one you want in ``webpack.config.js``:
 
 .. code-block:: javascript
 
@@ -32,46 +10,24 @@ can also pass options to ``sass-loader``:
 
     Encore
         // ...
-        .enableSassLoader(function(options) {
-            // https://github.com/sass/node-sass#options
-            // options.includePaths = [...]
-        });
-    ;
-
-Using LESS
-----------
-
-To use the LESS pre-processor, install the dependencies:
 
-.. code-block:: terminal
+        // enable just the one you want
 
-    $ yarn add --dev less-loader less
-
-And enable it in ``webpack.config.js``:
-
-.. code-block:: javascript
-
-    // webpack.config.js
-    // ...
+        // processes files ending in .scss or .sass
+        .enableSassLoader()
 
-    Encore
-        // ...
+        // processes files ending in .less
         .enableLessLoader()
-    ;
 
-That's it! All files ending in ``.less`` will be pre-processed. You can also pass
-options to ``less-loader``:
+        // processes files ending in .styl
+        .enableStylusLoader()
+    ;
 
-.. code-block:: javascript
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
 
-    // webpack.config.js
-    // ...
+You can also pass configuration options to each of the loaders. See the
+`Encore's index.js file`_ for detailed documentation.
 
-    Encore
-        // ...
-        .enableLessLoader(function(options) {
-            // https://github.com/webpack-contrib/less-loader#examples
-            // http://lesscss.org/usage/#command-line-usage-options
-            // options.relativeUrls = false;
-        });
-    ;
+.. _`Encore's index.js file`: https://github.com/symfony/webpack-encore/blob/master/index.js

frontend/encore/installation.rst

@@ -10,7 +10,7 @@ run:
 
 .. code-block:: terminal
 
-    $ composer require symfony/webpack-encore-pack
+    $ composer require encore
     $ yarn install
 
 This will create a ``webpack.config.js`` file, add the ``assets/`` directory, and

frontend/encore/page-specific-assets.rst

@@ -5,46 +5,7 @@ If you're creating a single page app (SPA), then you probably only need to defin
 *one* entry in ``webpack.config.js``. But if you have multiple pages, you might
 want page-specific CSS and JavaScript.
 
-For example, suppose you have a checkout page that has its own JavaScript. Create
-a new ``checkout`` entry:
-
-.. code-block:: diff
-
-    // webpack.config.js
-
-    Encore
-        // an existing entry
-        .addEntry('app', './assets/js/app.js')
-
-    +     .addEntry('checkout', './assets/js/checkout.js')
-    ;
-
-Inside ``checkout.js``, add or require the JavaScript and CSS you need. Then, just
-call the ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
-*only* on the checkout page to include the new ``script`` and ``link`` tags
-(if any ``link`` tag is needed):
-
-.. code-block:: twig
-
-    {# templates/order/checkout.html.twig #}
-    {# ... #}
-
-    {#
-        Assuming you're using Symfony's standard base.html.twig setup, add
-        to the stylesheets and javascript blocks
-    #}
-
-    {% block javascripts %}
-        {{ parent() }}
-
-        {{ encore_entry_script_tags('checkout') }}
-    {% endblock %}
-
-    {% block stylesheets %}
-        {{ parent() }}
-
-        {{ encore_entry_link_tags('checkout') }}
-    {% endblock %}
+To learn how to set this up, see the :ref:`multiple-javascript-entries` example.
 
 Multiple Entries Per Page?
 --------------------------
@@ -55,10 +16,10 @@ you need.
 
 However, it's pretty common to need to include some global JavaScript and CSS on
 every page. For that reason, it usually makes sense to have one entry (e.g. ``app``)
-that contains this global code and is included on every page (i.e. it's included
-in the *layout* of your app). This means that you will always have one, global entry
-on every page (e.g. ``app``) and you *may* have one page-specific JavaScript and
-CSS file from a page-specific entry (e.g. ``checkout``).
+that contains this global code (both JavaScript & CSS) and is included on every
+page (i.e. it's included in the *layout* of your app). This means that you will
+always have one, global entry on every page (e.g. ``app``) and you *may* have one
+page-specific JavaScript and CSS file from a page-specific entry (e.g. ``checkout``).
 
 .. tip::
 

frontend/encore/postcss.rst

@@ -35,6 +35,8 @@ Then, Enable the loader in Encore!
     +     .enablePostCssLoader()
     ;
 
+Because you just modified ``webpack.config.js``, stop and restart Encore.
+
 That's it! The ``postcss-loader`` will now be used for all CSS, Sass, etc files.
 You can also pass options to the `postcss-loader`_ by passing a callback:
 
@@ -51,6 +53,8 @@ You can also pass options to the `postcss-loader`_ by passing a callback:
     +     })
     ;
 
+.. _browserslist_package_config:
+
 Adding browserslist to package.json
 -----------------------------------
 
@@ -61,17 +65,16 @@ support. The best-practice is to configure this directly in your ``package.json`
 .. code-block:: diff
 
     {
-    +     "browserslist": [ "last 2 versions", "ios >= 8" ]
+    +  "browserslist": [
+    +    "> 0.5%",
+    +    "last 2 versions",
+    +    "Firefox ESR",
+    +    "not dead"
+    +  ]
     }
 
 See `browserslist`_ for more details on the syntax.
 
-.. note::
-
-    Encore uses `babel-preset-env`_, which *also* needs to know which browsers you
-    want to support. But this does *not* read the ``browserslist`` config key. You
-    must configure the browsers separately via :doc:`configureBabel() </frontend/encore/babel>`.
-
 .. _`PostCSS`: http://postcss.org/
 .. _`autoprefixing`: https://github.com/postcss/autoprefixer
 .. _`linting`: https://stylelint.io/

frontend/encore/reactjs.rst

@@ -1,25 +1,23 @@
 Enabling React.js
 =================
 
-Using React? Make sure you have React installed, along with the `babel-preset-react`_:
+Using React? First enable support for it in ``webpack.config.js``:
 
-.. code-block:: terminal
-
-    $ yarn add --dev react react-dom prop-types babel-preset-react
-
-Enable react in your ``webpack.config.js``:
-
-.. code-block:: javascript
+.. code-block:: diff
 
     // webpack.config.js
     // ...
 
     Encore
         // ...
-        .enableReactPreset()
+    +     .enableReactPreset()
     ;
 
-That's it! Your ``.js`` and ``.jsx`` files will now be transformed through
-``babel-preset-react``.
+
+Then restart Encore. When you do, it will give you a command you can run to
+install any missing dependencies. After running that command and restarting
+Encore, you're done!
+
+Your ``.js`` and ``.jsx`` files will now be transformed through ``babel-preset-react``.
 
 .. _`babel-preset-react`: https://babeljs.io/docs/plugins/preset-react/