adding a small entry about ajax code splitting

Author: weaverryan

frontend.rst

@@ -58,6 +58,7 @@ Optimizing
 
 * :doc:`Versioning (and the entrypoints.json/manifest.json files) </frontend/encore/versioning>`
 * :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`

frontend/encore/code-splitting.rst

@@ -0,0 +1,64 @@
+Async Code Splitting
+====================
+
+When you require/import a JavaScript or CSS module, Webpack compiles that code into
+the final JavaScript or CSS file. Usually, that's exactly what you want. But what
+if you only need to use a piece of code under certain conditions? For example,
+what if you want to use `video.js`_ to play a video, but only once a user has
+clicked a link:
+
+.. code-block:: javascript
+
+    // assets/js/app.js
+
+    import $ from 'jquery';
+    // a fictional "large" module (e.g. it imports video.js internally)
+    import VideoPlayer from './components/VideoPlayer';
+
+    $('.js-open-video').on('click', function() {
+        // use the larger VideoPlayer module
+        const player = new VideoPlayer('some-element');
+    });
+
+In this example, the VidePlayer module and everything it imports will be packaged
+into the final, built JavaScript file, even though it may not be very common for
+someone to actually need it. A better solution is to use `dynamic imports`_: load
+the code via AJAX when it's needed:
+
+.. code-block:: javascript
+
+    // assets/js/app.js
+
+    import $ from 'jquery';
+
+    $('.js-open-video').on('click', function() {
+        // you could start a loading animation here
+    
+        // use import() as a function - it returns a Promise
+        import('./components/VideoPlayer').then(({ default: VideoPlayer }) => {
+            // you could stop a loading animation here
+
+            // use the larger VideoPlayer module
+            const player = new VideoPlayer('some-element');
+
+        }).catch(error => 'An error occurred while loading the component');
+    });
+
+By using ``import()`` like a function, the module will be downloaded async and
+the ``.then()`` callback will be executed when it's finished. The ``VideoPlayer``
+argument to the callback will be the loaded module. In other words, it works like
+normal AJAX calls! Behind the scenes, Webpack will package the ``VideoPlayer`` module
+into a separate file (e.g. ``0.js``) so it can be downloaded. All the details are
+handled for you.
+
+The ``{ default: VideoPlayer }`` part may look strange. When using the async
+import, your ``.then()`` callback is passed an object, where the *actual* module
+is on a ``.default`` key. There are reasons why this is done, but it does look
+quirky. The ``{ default: VideoPlayer }`` code makes sure that the ``VideoPlayer``
+module we want is read from this ``.default`` property.
+
+For more details and configuration options, see `dynamic imports`_ on Webpack's
+documentation.
+
+.. _`video.js`: https://videojs.com/
+.. _`dynamic imports`: https://webpack.js.org/guides/code-splitting/#dynamic-imports