Adding docs for runtime.js and fixed a few other things

Author: weaverryan

frontend/encore/faq.rst

@@ -94,9 +94,10 @@ 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.
+If you get this error, it's probably because you've forgotten to add a ``script``
+tag for the ``runtime.js`` file that contains Webpack's runtime. If you're using
+the ``encore_entry_script_tags()`` Twig function, this should never happen: the
+file script tag is rendered automatically.
 
 This dependency was not found: some-module in ./path/to/file.js
 ---------------------------------------------------------------

frontend/encore/installation-no-flex.rst

@@ -58,6 +58,10 @@ Next, create a new ``webpack.config.js`` file at the root of your project:
         //.addEntry('page1', './assets/js/page1.js')
         //.addEntry('page2', './assets/js/page2.js')
 
+        // will require an extra script tag for runtime.js
+        // but, you probably want this, unless you're building a single-page app
+        .enableSingleRuntimeChunk()
+
         .cleanupOutputBeforeBuild()
         .enableSourceMaps(!Encore.isProduction())
         // enables hashed filenames (e.g. app.abc123.css)

frontend/encore/page-specific-assets.rst

@@ -14,32 +14,53 @@ a new ``checkout`` entry:
 
     Encore
         // an existing entry
-        .addEntry('app', './assets/js/main.js')
-        // a global styles entry
-        .addStyleEntry('global', './assets/css/global.scss')
+        .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
-include a ``script`` tag for ``checkout.js`` on the checkout page (and a ``link``
-tag for ``checkout.css`` if you import any CSS).
+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 %}
 
 Multiple Entries Per Page?
 --------------------------
 
-Typically, you should include only *one* JavaScript entry per page. This means
-the checkout page will include ``checkout.js``, but will *not* include the
-``app.js`` that's used on the other pages. Think of the checkout page as its
-own "app", where ``checkout.js`` includes all the functionality you need.
+Typically, you should include only *one* JavaScript entry per page. Think of the
+checkout page as its own "app", where ``checkout.js`` includes all the functionality
+you need.
 
-However, if there is some global JavaScript that you want included on *every*
-page, you *can* create an entry that contains that code and include both that
-entry *and* your page-specific entry. For example, suppose that the ``app``
-entry above contains JavaScript you want on every page. In that case, include
-both ``app.js`` and ``checkout.js`` on the checkout page.
+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``).
 
 .. tip::
 
-    Be sure to create a :doc:`shared entry </frontend/encore/shared-entry>` to avoid duplicating
-    the Webpack bootstrap logic and any shared modules.
+    Be sure to use split chunks :doc:`shared entry </frontend/encore/split-chunks>`
+    to avoid duplicating and shared code between your entry files.

frontend/encore/shared-entry.rst

@@ -24,33 +24,13 @@ Update your code to use ``createSharedEntry()``:
         .addEntry('blog', './assets/js/blog.js')
         .addEntry('store', './assets/js/store.js')
 
-As soon as you make this change, you need to include *one* extra JavaScript file
-in your layout, *before* ``app.js``:
-
-.. _encore-shared-entry-script:
-
-.. code-block:: twig
-
-    {# templates/base.html.twig #}
-    <!-- these two files now must be included on every page -->
-    <script src="{{ asset('build/manifest.js') }}"></script>
-    <script src="{{ asset('build/app.js') }}"></script>
-
-    <!-- you can still include page-specific JavaScript, like normal -->
-    <script src="{{ asset('build/store.js') }}"></script>
-
-    <!-- continue including app.css on every page -->
-    <link rel="stylesheet" href="{{ asset('build/app.css') }}" />
-
 Before making this change, if both ``app.js`` and ``store.js`` require ``jquery``,
 then ``jquery`` would be packaged into *both* files, which is wasteful. By making
 ``app.js`` your "shared" entry, *any* code required by ``app.js`` (like jQuery) will
 *no longer* be packaged into any other files. The same is true for any CSS.
 
 Because ``app.js`` contains all the common code that other entry files depend on,
-it's obvious that its script (and link) tag must be on every page. The other file
-(``manifest.js``) is less obvious: it's needed so that Webpack knows how to load
-these shared modules.
+it's obvious that its script (and link) tag must be on every page.
 
 .. tip::
 

frontend/encore/simple-example.rst

@@ -90,15 +90,21 @@ WebpackEncoreBundle:
             <!-- ... -->
 
             {% block stylesheets %}
-                {# will render <link rel="stylesheet" src="/build/app.css"> #}
+                <!--
+                    Will render a link tag if your module requires CSS
+                        <link rel="stylesheet" src="/build/app.css">
+                -->
                 {{ encore_entry_link_tags('app') }}
             {% endblock %}
         </head>
         <body>
             <!-- ... -->
 
             {% block javascripts %}
-                {# will render <script src="/build/app.js"></script> #}
+                <!--
+                    Will render app.js & a webpack runtime.js file
+                        <script src="/build/runtime.js"></script>
+                        <script src="/build/app.js"></script>
                 {{ encore_entry_script_tags('app') }}
             {% endblock %}
         </body>
@@ -108,7 +114,7 @@ WebpackEncoreBundle:
 
 The ``encore_entry_link_tags()`` and ``encore_entry_script_tags()`` functions
 read from an ``entrypoints.json`` file that's generated by Encore to know the exact
-filename to render. This file is *especially* useful because you can
+filename(s) to render. This file is *especially* useful because you can
 :doc:`enable versioning</frontend/versioning>` or
 :doc:`point assets to a CDN</frontend/cdn>` without making *any* changes to your
 template: the paths in ``entrypoints.json`` will always be the final, correct paths.

frontend/encore/split-chunks.rst

@@ -37,6 +37,7 @@ tags as needed:
 
     {#
         May now render multiple script tags:
+            <script src="/build/runtime.js"></script>
             <script src="/build/homepage.js"></script>
             <script src="/build/vendor~homepage.js"></script>
     #}