Always outputting runtime.js

This is a subjective decision we made, because we thought it would cause
less "confusing" moments (i.e. when 2 different entries would not share
the same modules).

Unfortunately, the single runtime chunk causes a strange bug with
mini-css-extract plugin where, under some conditions, the output CSS
uses the chunk filename instead of "filename".

Author: weaverryan

CHANGELOG.md

@@ -5,6 +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`.

index.js

@@ -404,6 +404,34 @@ class Encore {
         return this;
     }
 
+    /**
+     * Tell Webpack to *not* output a separate runtime.js file.
+     *
+     * 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.
+     *
+     * If you *do* include multiple entry files on the same page,
+     * disabling the runtime.js file has two important consequences:
+     *  A) Each entry file will contain the Webpack runtime, which
+     *     means each contains some code that is duplicated in the other.
+     *  B) If two entry files require the same module (e.g. jquery),
+     *     they will receive *different* objects - not the *same* object.
+     *     This can cause some confusion if you expect a "layout.js" entry
+     *     to be able to "initialize" some jQuery plugins, because the
+     *     jQuery required by the other entry will be a different instance,
+     *     and so won't have the plugins initialized on it.
+     *
+     * @returns {Encore}
+     */
+    disableSingleRuntimeChunk() {
+        webpackConfig.disableSingleRuntimeChunk();
+
+        return this;
+    }
+
     /**
      * Tell Webpack to "split" your entry chunks.
      *

lib/WebpackConfig.js

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

lib/config-generator.js

@@ -400,7 +400,13 @@ 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';
         }
 

lib/plugins/mini-css-extract.js

@@ -20,18 +20,30 @@ const PluginPriorities = require('./plugin-priorities');
 module.exports = function(plugins, webpackConfig) {
     // Default filename can be overridden using Encore.configureFilenames({ css: '...' })
     let filename = webpackConfig.useVersioning ? '[name].[contenthash:8].css' : '[name].css';
-    let chunkFilename = webpackConfig.useVersioning ? '[id].[contenthash:8].css' : '[id].css';
+    // the chunk filename should use [id], not [name]. But, due
+    // to weird behavior (bug?) that's exposed in a functional test
+    // (in production mode, code is uglified), in some cases, an entry
+    // 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';
+    let chunkFilename = webpackConfig.useVersioning ? '[name].[contenthash:8].css' : '[name].css';
     if (webpackConfig.configuredFilenames.css) {
         filename = webpackConfig.configuredFilenames.css;
+
+        // see above: originally we did NOT set this, because this was
+        // only for split chunks. But now, sometimes the "entry" CSS chunk
+        // will use chunkFilename. So, we need to always respect the
+        // user's wishes
+        chunkFilename = webpackConfig.configuredFilenames.css;
     }
 
-    const extractTextPluginOptions = {
+    const miniCssPluginOptions = {
         filename: filename,
-        chunkFilename
+        chunkFilename: chunkFilename
     };
 
     plugins.push({
-        plugin: new MiniCssExtractPlugin(extractTextPluginOptions),
+        plugin: new MiniCssExtractPlugin(miniCssPluginOptions),
         priority: PluginPriorities.MiniCssExtractPlugin
     });
 };