feature #14 Replacing virtual-modules with a loader for controller.json (weaverryan)

This PR was squashed before being merged into the main branch.

Discussion
----------

Replacing virtual-modules with a loader for controller.json

Hi!

The motivation behind this was a few things:

1) the wepback-virtual-modules plugin emits a worrying warning in Webpack 5 and, in general, doesn't seem to be super-actively developed.
2) sokra says that a loader is the correct solution: webpack/webpack#11074 (comment)
3) Since loaders are native/normal, this works well with `watch` mode and should work just fine with Webpack 5 persistent build caching.

This also includes a tricky NormalModuleReplacementPlugin() so that we can continue to handling the parsing of the user's controller.json inside this library (instead of putting the import + loader code in their app).

This will require a partner PR in webpack-encore (symfony/webpack-encore#888). The only line users will need to change in their app is to remove `import '@symfony/autoimport';` from their `assets/bootstrap.js` file.

Cheers!

Commits
-------

fb5aaf7 Replacing virtual-modules with a loader for controller.json

Author: tgalopin

README.md

@@ -20,9 +20,6 @@ yarn add @symfony/stimulus-bridge
 
 ## Usage
 
-This package relies on [webpack-virtual-modules](https://github.com/sysgears/webpack-virtual-modules)
-to build dynamic modules referencing vendor Stimulus controllers and styles.
-
 To use it, first configure Webpack Encore:
 
 ```javascript
@@ -38,11 +35,24 @@ Then use the package in your JavaScript code:
 // app.js (or bootstrap.js if you use the standard Symfony structure)
 
 import { startStimulusApp } from '@symfony/stimulus-bridge';
-import '@symfony/autoimport';
 
 export const app = startStimulusApp(require.context('./controllers', true, /\.(j|t)sx?$/));
 ```
 
+If you get this error:
+
+> ./assets/bootstrap.js contains a reference to the file @symfony/autoimport.
+> This file can not be found.
+
+Remove the following line in the mentioned file: it's not needed anymore:
+
+```diff
+// assets/bootstrap.js
+
+// ...
+- import '@symfony/autoimport';
+```
+
 ## Run tests
 
 ```sh

controllers.json

@@ -0,0 +1,3 @@
+{
+    "placeholder": true
+}

dist/index.js

@@ -17,10 +17,12 @@ var _stimulus = require("stimulus");
 
 var _webpackHelpers = require("stimulus/webpack-helpers");
 
-var _controllers = _interopRequireDefault(require("@symfony/controllers"));
+var _controllers = _interopRequireDefault(require("./webpack/loader!@symfony/stimulus-bridge/controllers.json"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 
+// The @symfony/stimulus-bridge/controllers.json should be changed
+// to point to the real controllers.json file via a Webpack alias
 function startStimulusApp(context) {
   var application = _stimulus.Application.start();
 
@@ -36,7 +38,7 @@ function startStimulusApp(context) {
 
     _controllers["default"][_controllerName].then(function (module) {
       // Normalize the controller name: remove the initial @ and use Stimulus format
-      _controllerName = _controllerName.substr(1).replace(/_/g, "-").replace(/\//g, "--");
+      _controllerName = _controllerName.substr(1).replace(/_/g, '-').replace(/\//g, '--');
       application.register(_controllerName, module["default"]);
     });
 

dist/webpack/create-autoimport-module.js

@@ -8,8 +8,13 @@
  */
 'use strict';
 
-module.exports = function createControllersVirtualModule(config) {
-  var file = 'export default {';
+module.exports = function createControllersModule(config) {
+  var controllerContents = 'export default {';
+  var autoImportContents = '';
+
+  if ('undefined' !== typeof config['placeholder']) {
+    throw new Error('Your controllers.json file was not found. Be sure to add a Webpack alias from "@symfony/stimulus-bridge/controllers.json" to *your* controllers.json file.');
+  }
 
   if ('undefined' === typeof config['controllers']) {
     throw new Error('Your Stimulus configuration file (assets/controllers.json) lacks a "controllers" key.');
@@ -34,9 +39,15 @@ module.exports = function createControllersVirtualModule(config) {
 
       var controllerMain = packageName + '/' + controllerPackageConfig.main;
       var webpackMode = controllerUserConfig.webpackMode;
-      file += "\n  '" + controllerReference + '\': import(/* webpackMode: "' + webpackMode + '" */ \'' + controllerMain + "'),";
+      controllerContents += "\n  '" + controllerReference + '\': import(/* webpackMode: "' + webpackMode + '" */ \'' + controllerMain + "'),";
+
+      for (var autoimport in controllerUserConfig.autoimport || []) {
+        if (controllerUserConfig.autoimport[autoimport]) {
+          autoImportContents += "import '" + autoimport + "';\n";
+        }
+      }
     }
   }
 
-  return file + '\n};';
+  return "".concat(autoImportContents).concat(controllerContents, "\n};");
 };

dist/webpack/create-controllers-module.js

@@ -0,0 +1,28 @@
+"use strict";
+
+var LoaderDependency = require('webpack/lib/dependencies/LoaderDependency');
+
+var createControllersModule = require('./create-controllers-module');
+
+module.exports = function (source) {
+  var logger = this.getLogger('stimulus-bridge-loader');
+  /*
+   * The following code prevents the normal JSON loader from
+   * executing after our loader. This is a workaround from WebpackEncore.
+   */
+
+  var requiredType = 'javascript/auto';
+
+  var factory = this._compilation.dependencyFactories.get(LoaderDependency);
+
+  if (factory === undefined) {
+    throw new Error('Could not retrieve module factory for type LoaderDependency');
+  }
+
+  this._module.type = requiredType;
+  this._module.generator = factory.getGenerator(requiredType);
+  this._module.parser = factory.getParser(requiredType);
+  /* End workaround */
+
+  return createControllersModule(JSON.parse(source));
+};

dist/webpack/loader.js

@@ -8,15 +8,13 @@
  */
 'use strict';
 
-var VirtualModulesPlugin = require('webpack-virtual-modules');
+var webpack = require('webpack');
 
-var createAutoimportVirtualModule = require('./create-autoimport-module');
+module.exports = function createStimulusBridgePlugin(controllersJsonPath) {
+  return new webpack.NormalModuleReplacementPlugin(/stimulus-bridge\/controllers-placeholder\.json$/, function (resource) {
+    // controls how the import string will be parsed, includes loader
+    resource.request = "./webpack/loader!".concat(controllersJsonPath); // controls the physical file that will be read
 
-var createControllersVirtualModule = require('./create-controllers-module');
-
-module.exports = function createStimulusBridgePlugin(config) {
-  return new VirtualModulesPlugin({
-    'node_modules/@symfony/autoimport.js': createAutoimportVirtualModule(config),
-    'node_modules/@symfony/controllers.js': createControllersVirtualModule(config)
+    resource.createData.resource = controllersJsonPath;
   });
 };

dist/webpack/plugin.js

@@ -16,15 +16,13 @@
         "stimulus": "^2.0"
     },
     "dependencies": {
-        "@babel/plugin-proposal-class-properties": "^7.12.1",
-        "webpack-virtual-modules": "^0.3.2"
+        "@babel/plugin-proposal-class-properties": "^7.12.1"
     },
     "devDependencies": {
         "@babel/cli": "^7.12.1",
         "@babel/core": "^7.12.3",
         "@babel/plugin-proposal-class-properties": "^7.12.1",
         "@babel/preset-env": "^7.12.7",
-        "@symfony/controllers": "file:test/fixtures/controllers",
         "@symfony/mock-module": "file:test/fixtures/module",
         "@symfony/stimulus-testing": "^1.0.0",
         "stimulus": "^2.0",
@@ -40,6 +38,7 @@
     "files": [
         "src/",
         "dist/",
-        "webpack-helper.js"
+        "webpack-helper.js",
+        "controllers.json"
     ]
 }

package.json

@@ -11,7 +11,10 @@
 
 import { Application } from 'stimulus';
 import { definitionsFromContext } from 'stimulus/webpack-helpers';
-import symfonyControllers from '@symfony/controllers';
+
+// The @symfony/stimulus-bridge/controllers.json should be changed
+// to point to the real controllers.json file via a Webpack alias
+import symfonyControllers from './webpack/loader!@symfony/stimulus-bridge/controllers.json';
 
 export function startStimulusApp(context) {
     const application = Application.start();
@@ -27,7 +30,7 @@ export function startStimulusApp(context) {
 
         symfonyControllers[controllerName].then((module) => {
             // Normalize the controller name: remove the initial @ and use Stimulus format
-            controllerName = controllerName.substr(1).replace(/_/g, "-").replace(/\//g, "--");
+            controllerName = controllerName.substr(1).replace(/_/g, '-').replace(/\//g, '--');
 
             application.register(controllerName, module.default);
         });

src/index.js

@@ -9,8 +9,15 @@
 
 'use strict';
 
-module.exports = function createControllersVirtualModule(config) {
-    let file = 'export default {';
+module.exports = function createControllersModule(config) {
+    let controllerContents = 'export default {';
+    let autoImportContents = '';
+
+    if ('undefined' !== typeof config['placeholder']) {
+        throw new Error(
+            'Your controllers.json file was not found. Be sure to add a Webpack alias from "@symfony/stimulus-bridge/controllers.json" to *your* controllers.json file.'
+        );
+    }
 
     if ('undefined' === typeof config['controllers']) {
         throw new Error('Your Stimulus configuration file (assets/controllers.json) lacks a "controllers" key.');
@@ -39,16 +46,22 @@ module.exports = function createControllersVirtualModule(config) {
             const controllerMain = packageName + '/' + controllerPackageConfig.main;
             const webpackMode = controllerUserConfig.webpackMode;
 
-            file +=
+            controllerContents +=
                 "\n  '" +
                 controllerReference +
                 '\': import(/* webpackMode: "' +
                 webpackMode +
                 '" */ \'' +
                 controllerMain +
                 "'),";
+
+            for (let autoimport in controllerUserConfig.autoimport || []) {
+                if (controllerUserConfig.autoimport[autoimport]) {
+                    autoImportContents += "import '" + autoimport + "';\n";
+                }
+            }
         }
     }
 
-    return file + '\n};';
+    return `${autoImportContents}${controllerContents}\n};`;
 };

src/webpack/create-autoimport-module.js

@@ -0,0 +1,22 @@
+const LoaderDependency = require('webpack/lib/dependencies/LoaderDependency');
+const createControllersModule = require('./create-controllers-module');
+
+module.exports = function (source) {
+    const logger = this.getLogger('stimulus-bridge-loader');
+
+    /*
+     * The following code prevents the normal JSON loader from
+     * executing after our loader. This is a workaround from WebpackEncore.
+     */
+    const requiredType = 'javascript/auto';
+    const factory = this._compilation.dependencyFactories.get(LoaderDependency);
+    if (factory === undefined) {
+        throw new Error('Could not retrieve module factory for type LoaderDependency');
+    }
+    this._module.type = requiredType;
+    this._module.generator = factory.getGenerator(requiredType);
+    this._module.parser = factory.getParser(requiredType);
+    /* End workaround */
+
+    return createControllersModule(JSON.parse(source));
+};

src/webpack/create-controllers-module.js

@@ -0,0 +1,11 @@
+{
+    "controllers": {
+        "@symfony/mock-module": {
+            "mock": {
+                "webpackMode": "eager",
+                "enabled": true
+            }
+        }
+    },
+    "entrypoints": []
+}

src/webpack/loader.js

@@ -19,6 +19,6 @@ describe('startStimulusApp', () => {
         await new Promise(setImmediate);
 
         expect(app.router.modules.length).toBe(1);
-        expect(app.router.modules[0].definition.identifier).toBe('symfony--mock-module--mock-controller');
+        expect(app.router.modules[0].definition.identifier).toBe('symfony--mock-module--mock');
     });
 });