Adding new Encore.enableSingleRuntimeChunk() + BC layer

This removes the BC breaks related to runtime.js, in favor of a
deprecation layer instead.

Author: weaverryan

CHANGELOG.md

@@ -5,16 +5,13 @@
  * [BC BREAK] Webpack was upgraded to version 4. This includes a number of major
    and minor changes. The changes are listed below.
 
- * [BC BREAK] A new `runtime.js` file is now *always* output and must be
-   included in your layout (before all other script tags for files output
-   by Encore). You can disable this by calling `Encore.disableSingleRuntimeChunk()`.
-   But note: if you include multiple entries on the same page, when the
-   runtime is disabled, each entry will *not* share modules (e.g. if they
-   both require `jquery`, they will receive 2 separate objects).
-
- * [BC BREAK] If you're using `createSharedEntry()`, the name of the
-   `manifest.js` file is now `runtime.js`. You will need to update
-   your `<script>` tag to point to the new `runtime.js`.
+ * [DEPRECATION] You must now call either `Encore.enableSingleRuntimeChunk()`
+   or `Encore.disableSingleRuntimeChunk()`: not calling either method is
+   deprecated. The recommended setting is `Encore.enableSingleRuntimeChunk()`.
+   This will cause a new `runtime.js` file to be created, which must be included
+   on your page with a script tag (before any other script tags for Encore
+   JavaScript files). See the documentation above `enableSingleRuntimeChunk()` in
+   `index.js` for more details.
 
  * [BEHAVIOR CHANGE] Previously, without any config, Babel was
    configured to "transpile" (i.e. re-write) your JavaScript so

index.js

@@ -405,13 +405,16 @@ class Encore {
     }
 
     /**
-     * Tell Webpack to *not* output a separate runtime.js file.
+     * Tell Webpack to output a separate runtime.js file.
+     *
+     * This file must be included via a script tag before all
+     * other JavaScript files output by Encore.
      *
      * The runtime.js file is useful when you plan to include
      * multiple entry files on the same page (e.g. a layout.js entry
      * and a page-specific entry). If you are *not* including
      * multiple entries on the same page, you can safely disable
-     * this and remove the extra script tags.
+     * this - disableSingleRuntimeChunk() - and remove the extra script tags.
      *
      * If you *do* include multiple entry files on the same page,
      * disabling the runtime.js file has two important consequences:
@@ -426,6 +429,19 @@ class Encore {
      *
      * @returns {Encore}
      */
+    enableSingleRuntimeChunk() {
+        webpackConfig.enableSingleRuntimeChunk();
+
+        return this;
+    }
+
+    /**
+     * Tell Webpack to *not* output a separate runtime.js file.
+     *
+     * See enableSingleRuntimeChunk() for more details.
+     *
+     * @returns {Encore}
+     */
     disableSingleRuntimeChunk() {
         webpackConfig.disableSingleRuntimeChunk();
 

lib/WebpackConfig.js

@@ -87,7 +87,7 @@ class WebpackConfig {
         this.stylusLoaderOptionsCallback = () => {};
         this.babelConfigurationCallback = () => {};
         this.cssLoaderConfigurationCallback = () => {};
-        this.shouldUseSingleRuntimeChunk = true;
+        this.shouldUseSingleRuntimeChunk = null;
         this.shouldSplitEntryChunks = false;
         this.splitChunksConfigurationCallback = () => {};
         this.vueLoaderOptionsCallback = () => {};
@@ -321,6 +321,10 @@ class WebpackConfig {
         this.cssLoaderConfigurationCallback = callback;
     }
 
+    enableSingleRuntimeChunk() {
+        this.shouldUseSingleRuntimeChunk = true;
+    }
+
     disableSingleRuntimeChunk() {
         this.shouldUseSingleRuntimeChunk = false;
     }

lib/config-generator.js

@@ -46,6 +46,7 @@ const fs = require('fs');
 const path = require('path');
 const stringEscaper = require('./utils/string-escaper');
 const crypto = require('crypto');
+const logger = require('./logger');
 
 class ConfigGenerator {
     /**
@@ -402,12 +403,36 @@ class ConfigGenerator {
             splitChunks.cacheGroups = cacheGroups;
         }
 
-        if (this.webpackConfig.shouldUseSingleRuntimeChunk) {
-            // causes a runtime.js to be emitted with the Webpack runtime
-            // this is important as a default because it causes different entry
-            // files to "share" modules, instead of each module getting their own
-            // fresh version of each module.
-            optimization.runtimeChunk = 'single';
+        switch (this.webpackConfig.shouldUseSingleRuntimeChunk) {
+            case true:
+                // causes a runtime.js to be emitted with the Webpack runtime
+                // this is important as a default because it causes different entry
+                // files to "share" modules, instead of each module getting their own
+                // fresh version of each module.
+                optimization.runtimeChunk = 'single';
+                break;
+            case false:
+                // add no runtimeChunk configuration
+                break;
+            case null:
+                /*
+                 * Not setting this option explicitly is deprecated.
+                 */
+                logger.deprecation('Either the Encore.enableSingleRuntimeChunk() or Encore.disableSingleRuntimeChunk() method should be called.');
+                if (this.webpackConfig.sharedCommonsEntryName) {
+                    logger.deprecation('Because you\'re using createSharedEntry(), the recommended setting is Encore.enableSingleRuntimeChunk().');
+                    logger.deprecation('After calling Encore.enableSingleRuntimeChunk(), the "manifest.js" file will be called "runtime.js": your script tag will need to be updated.');
+                    // output it, but keep the old filename
+                    optimization.runtimeChunk = {
+                        name: 'manifest'
+                    };
+                } else {
+                    logger.deprecation('The recommended setting is Encore.enableSingleRuntimeChunk().');
+                    logger.deprecation('After calling Encore.enableSingleRuntimeChunk(), a new "runtime.js" will be output and should be included on your page before any other script tags for Encore files.');
+                    // do not output the runtime
+                }
+
+                break;
         }
 
         optimization.splitChunks = applyOptionsCallback(

lib/plugins/mini-css-extract.js

@@ -26,6 +26,7 @@ module.exports = function(plugins, webpackConfig) {
     // CSS file mysteriously becomes a chunk. In other words, it
     // will have a filename like 1.css instead of entry_name.css
     // This is related to setting optimization.runtimeChunk = 'single';
+    // See https://github.com/webpack/webpack/issues/6598
     let chunkFilename = webpackConfig.useVersioning ? '[name].[contenthash:8].css' : '[name].css';
     if (webpackConfig.configuredFilenames.css) {
         filename = webpackConfig.configuredFilenames.css;

test/config-generator.js

@@ -17,6 +17,7 @@ const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 const ManifestPlugin = require('webpack-manifest-plugin');
 const CleanWebpackPlugin = require('clean-webpack-plugin');
 const webpack = require('webpack');
+const logger = require('../lib/logger');
 
 const isWindows = (process.platform === 'win32');
 
@@ -850,4 +851,58 @@ describe('The config-generator function', () => {
             expect(actualConfig.optimization.splitChunks.name).to.be.a('function');
         });
     });
+
+    describe('Test shouldUseSingleRuntimeChunk', () => {
+        before(() => {
+            logger.reset();
+            logger.quiet();
+        });
+
+        after(() => {
+            logger.quiet(false);
+        });
+
+        it('Set to true', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public/build';
+            config.setPublicPath('/build/');
+            config.enableSingleRuntimeChunk();
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.optimization.runtimeChunk).to.equal('single');
+            expect(logger.getMessages().deprecation).to.be.empty;
+        });
+
+        it('Set to false', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public/build';
+            config.setPublicPath('/build/');
+            config.disableSingleRuntimeChunk();
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.optimization.runtimeChunk).to.be.undefined;
+            expect(logger.getMessages().deprecation).to.be.empty;
+        });
+
+        it('Not set + createSharedEntry()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public/build';
+            config.setPublicPath('/build/');
+            config.createSharedEntry('foo', 'bar.js');
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.optimization.runtimeChunk.name).to.equal('manifest');
+            expect(JSON.stringify(logger.getMessages().deprecation)).to.contain('the recommended setting is Encore.enableSingleRuntimeChunk()');
+        });
+
+        it('Not set without createSharedEntry()', () => {
+            const config = createConfig();
+            config.outputPath = '/tmp/public/build';
+            config.setPublicPath('/build/');
+
+            const actualConfig = configGenerator(config);
+            expect(actualConfig.optimization.runtimeChunk).to.be.undefined;
+            expect(JSON.stringify(logger.getMessages().deprecation)).to.contain('the recommended setting is Encore.enableSingleRuntimeChunk()');
+        });
+    });
 });

test/functional.js

@@ -18,12 +18,16 @@ const fs = require('fs-extra');
 const sharedEntryTmpName = require('../lib/utils/sharedEntryTmpName');
 
 function createWebpackConfig(outputDirName = '', command, argv = {}) {
-    return testSetup.createWebpackConfig(
+    const webpackConfig = testSetup.createWebpackConfig(
         testSetup.createTestAppDir(),
         outputDirName,
         command,
         argv
     );
+
+    webpackConfig.enableSingleRuntimeChunk();
+
+    return webpackConfig;
 }
 
 function convertToManifestPath(assetSrc, webpackConfig) {
@@ -712,6 +716,36 @@ describe('Functional tests using webpack', function() {
             });
         });
 
+        it('createdSharedEntry() with shouldUseSingleRuntimeChunk not set', (done) => {
+            const config = createWebpackConfig('www/build', 'dev');
+            // set back to the "not set" value
+            config.shouldUseSingleRuntimeChunk = null;
+            config.setPublicPath('/build');
+            config.addEntry('main', ['./js/no_require', './js/code_splitting', './js/arrow_function', './js/print_to_app']);
+            config.createSharedEntry('shared', './js/shared_example');
+
+            testSetup.runWebpack(config, (webpackAssert) => {
+                // should be called manifest.js
+                webpackAssert.assertOutputFileContains(
+                    'manifest.js',
+                    'function __webpack_require__'
+                );
+
+                testSetup.requestTestPage(
+                    path.join(config.getContext(), 'www'),
+                    [
+                        'build/manifest.js',
+                        'build/shared.js',
+                    ],
+                    (browser) => {
+                        // assert that the javascript brought into shared is executed
+                        browser.assert.text('#app', 'Welcome to Encore!');
+                        done();
+                    }
+                );
+            });
+        });
+
         it('createdSharedEntry() does not run shared code twice', (done) => {
             const config = createWebpackConfig('www/build', 'dev');
             config.setPublicPath('/build');

test/index.js

@@ -134,6 +134,15 @@ describe('Public API', () => {
 
     });
 
+    describe('enableSingleRuntimeChunk', () => {
+
+        it('must return the API object', () => {
+            const returnedValue = api.enableSingleRuntimeChunk();
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
     describe('disableSingleRuntimeChunk', () => {
 
         it('must return the API object', () => {