Changing to "fetch" option from webpackMode

Author: weaverryan

CHANGELOG.md

@@ -11,10 +11,13 @@
   Before: `@symfony/ux-dropzone/dropzone`
   After: `symfony--ux-dropzone--dropzone`
 
-* Support for "lazy controllers" was added. By setting the `webpackMode`
-  in `controllers.json` to `lazy-controller`, your controller will not
+* Support for "lazy controllers" was added. By setting the `fetch`
+  in `controllers.json` to `lazy`, your controller will not
   be downloaded until the controller element first appears on the page.
 
+* The `webpackMode` option in `controllers.json` was deprecated. Use
+  the new `fetch` option instead.
+
 ## 1.1.0
 
 * Support for Stimulus 1 dropped and support for Stimulus 2 added - #4.

README.md

@@ -74,7 +74,7 @@ look like this:
         "@symfony/ux-dropzone": {
             "dropzone": {
                 "enabled": true,
-                "webpackMode": "eager",
+                "fetch": "eager",
                 "autoimport": {
                     "@symfony/ux-dropzone/src/style.css": true
                 }
@@ -90,14 +90,12 @@ registered with a specific name - in this case the controller would
 be called `symfony--ux-dropzone--dropzone` (the `/` becomes `--`).
 
 By default, the new controller will always be included in your
-JavaScript package. You can control that with the `webpackMode` option,
+JavaScript package. You can control that with the `fetch` option,
 ordered from least to most lazy:
 
-* `webpackMode: 'eager'`: controller & dependencies are included in the JavaScript
+* `fetch: 'eager'`: controller & dependencies are included in the JavaScript
   that's downloaded when the page is loaded.
-* `webpackMode: 'lazy'`: controller & dependencies are isolated into a separate
-  JavaScript file, but immediately downloaded asynchronously after the page is loaded.
-* `webpackMode: 'lazy-controller'`: controller & dependencies are isolated into a
+* `fetch: 'lazy'`: controller & dependencies are isolated into a
   separate file and only downloaded asynchronously if (and when) the `data-controller`
   HTML appears on the page.
 

dist/webpack/create-controllers-module.js

@@ -14,6 +14,7 @@ module.exports = function createControllersModule(config) {
   var controllerContents = 'export default {';
   var autoImportContents = '';
   var hasLazyControllers = false;
+  var deprecations = [];
 
   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.');
@@ -43,10 +44,23 @@ module.exports = function createControllersModule(config) {
       }
 
       var controllerMain = packageName + '/' + controllerPackageConfig.main;
-      var webpackMode = controllerUserConfig.webpackMode;
-      var moduleValueContents = "import(/* webpackMode: \"".concat(webpackMode, "\" */ '").concat(controllerMain, "')");
+      var fetchMode = 'eager';
 
-      if (webpackMode === 'lazy-controller') {
+      if ('undefined' !== typeof controllerUserConfig.webpackMode) {
+        deprecations.push('The "webpackMode" config key is deprecated in controllers.json. Use "fetch" instead, set to either "eager" or "lazy".');
+      }
+
+      if ('undefined' !== typeof controllerUserConfig.fetch) {
+        if (!['eager', 'lazy'].includes(controllerUserConfig.fetch)) {
+          throw new Error("Invalid \"fetch\" value \"".concat(controllerUserConfig.fetch, "\" in controllers.json. Expected \"eager\" or \"lazy\"."));
+        }
+
+        fetchMode = controllerUserConfig.fetch;
+      }
+
+      var moduleValueContents = "import(/* webpackMode: \"eager\" */ '".concat(controllerMain, "')");
+
+      if (fetchMode === 'lazy') {
         hasLazyControllers = true;
         moduleValueContents = "\nnew Promise((resolve, reject) => resolve({ default:\n".concat(generateLazyController(controllerMain, 6), "\n  }))\n                ").trim();
       }
@@ -65,5 +79,8 @@ module.exports = function createControllersModule(config) {
     controllerContents = "import { Controller } from 'stimulus';\n".concat(controllerContents);
   }
 
-  return "".concat(autoImportContents).concat(controllerContents, "\n};");
+  return {
+    finalSource: "".concat(autoImportContents).concat(controllerContents, "\n};"),
+    deprecations: deprecations
+  };
 };

dist/webpack/loader.js

@@ -25,6 +25,8 @@ var createControllersModule = require('./create-controllers-module');
 
 
 module.exports = function (source) {
+  var _this = this;
+
   var logger = this.getLogger('stimulus-bridge-loader');
   /*
    * The following code prevents the normal JSON loader from
@@ -44,5 +46,12 @@ module.exports = function (source) {
   this._module.parser = factory.getParser(requiredType);
   /* End workaround */
 
-  return createControllersModule(JSON.parse(source));
+  var _createControllersMod = createControllersModule(JSON.parse(source)),
+      finalSource = _createControllersMod.finalSource,
+      deprecations = _createControllersMod.deprecations;
+
+  deprecations.forEach(function (message) {
+    _this.emitWarning(new Error(message));
+  });
+  return finalSource;
 };

src/webpack/create-controllers-module.js

@@ -15,6 +15,7 @@ module.exports = function createControllersModule(config) {
     let controllerContents = 'export default {';
     let autoImportContents = '';
     let hasLazyControllers = false;
+    const deprecations = [];
 
     if ('undefined' !== typeof config['placeholder']) {
         throw new Error(
@@ -49,10 +50,26 @@ module.exports = function createControllersModule(config) {
             }
 
             const controllerMain = packageName + '/' + controllerPackageConfig.main;
-            const webpackMode = controllerUserConfig.webpackMode;
+            let fetchMode = 'eager';
 
-            let moduleValueContents = `import(/* webpackMode: "${webpackMode}" */ '${controllerMain}')`;
-            if (webpackMode === 'lazy-controller') {
+            if ('undefined' !== typeof controllerUserConfig.webpackMode) {
+                deprecations.push(
+                    'The "webpackMode" config key is deprecated in controllers.json. Use "fetch" instead, set to either "eager" or "lazy".'
+                );
+            }
+
+            if ('undefined' !== typeof controllerUserConfig.fetch) {
+                if (!['eager', 'lazy'].includes(controllerUserConfig.fetch)) {
+                    throw new Error(
+                        `Invalid "fetch" value "${controllerUserConfig.fetch}" in controllers.json. Expected "eager" or "lazy".`
+                    );
+                }
+
+                fetchMode = controllerUserConfig.fetch;
+            }
+
+            let moduleValueContents = `import(/* webpackMode: "eager" */ '${controllerMain}')`;
+            if (fetchMode === 'lazy') {
                 hasLazyControllers = true;
                 moduleValueContents = `
 new Promise((resolve, reject) => resolve({ default:
@@ -75,5 +92,8 @@ ${generateLazyController(controllerMain, 6)}
         controllerContents = `import { Controller } from 'stimulus';\n${controllerContents}`;
     }
 
-    return `${autoImportContents}${controllerContents}\n};`;
+    return {
+        finalSource: `${autoImportContents}${controllerContents}\n};`,
+        deprecations,
+    };
 };

src/webpack/loader.js

@@ -40,5 +40,11 @@ module.exports = function (source) {
     this._module.parser = factory.getParser(requiredType);
     /* End workaround */
 
-    return createControllersModule(JSON.parse(source));
+    const { finalSource, deprecations } = createControllersModule(JSON.parse(source));
+
+    deprecations.forEach((message) => {
+        this.emitWarning(new Error(message));
+    });
+
+    return finalSource;
 };

test/controllers.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "eager",
+                "fetch": "eager",
                 "enabled": true
             }
         }

test/fixtures/lazy-controller-no-autoimport.json renamed to test/fixtures/deprecated-webpack-mode.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "lazy-controller",
+                "webpackMode": "eager",
                 "enabled": true
             }
         }

test/fixtures/disabled-autoimport.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "lazy",
+                "fetch": "eager",
                 "enabled": true,
                 "autoimport": {
                     "@symfony/mock-module/dist/style.css": false

test/fixtures/disabled-controller.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "eager",
+                "fetch": "eager",
                 "enabled": false,
                 "autoimport": {
                     "@symfony/mock-module/dist/style.css": false

test/fixtures/lazy-autoimport.json renamed to test/fixtures/eager-autoimport.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "lazy",
+                "fetch": "eager",
                 "enabled": true,
                 "autoimport": {
                     "@symfony/mock-module/dist/style.css": true

test/fixtures/eager-no-autoimport.json

@@ -2,7 +2,7 @@
     "controllers": {
         "@symfony/mock-module": {
             "mock": {
-                "webpackMode": "eager",
+                "fetch": "eager",
                 "enabled": true
             }
         }

test/fixtures/lazy-no-autoimport.json

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

test/webpack/create-controllers-module.test.js

@@ -15,48 +15,59 @@ describe('createControllersModule', () => {
     describe('empty.json', () => {
         it('must return an empty file', () => {
             const config = require('../fixtures/empty.json');
-            expect(createControllersModule(config)).toEqual('export default {\n};');
+            expect(createControllersModule(config).finalSource).toEqual('export default {\n};');
         });
     });
 
     describe('disabled-controller.json', () => {
         it('must return an empty file', () => {
             const config = require('../fixtures/disabled-controller.json');
-            expect(createControllersModule(config)).toEqual('export default {\n};');
+            expect(createControllersModule(config).finalSource).toEqual('export default {\n};');
         });
     });
 
     describe('disabled-autoimport.json', () => {
         it('must return file with no autoimport', () => {
             const config = require('../fixtures/disabled-autoimport.json');
-            expect(createControllersModule(config)).toEqual(
-                "export default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"lazy\" */ '@symfony/mock-module/dist/controller.js'),\n};"
+            expect(createControllersModule(config).finalSource).toEqual(
+                "export default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"eager\" */ '@symfony/mock-module/dist/controller.js'),\n};"
             );
         });
     });
 
     describe('eager-no-autoimport.json', () => {
         it('must return file with no autoimport', () => {
             const config = require('../fixtures/eager-no-autoimport.json');
-            expect(createControllersModule(config)).toEqual(
+            expect(createControllersModule(config).finalSource).toEqual(
+                "export default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"eager\" */ '@symfony/mock-module/dist/controller.js'),\n};"
+            );
+        });
+    });
+
+    describe('deprecated-webpack-mode.json', () => {
+        it('must return eager mode with deprecation', () => {
+            const config = require('../fixtures/deprecated-webpack-mode.json');
+            const result = createControllersModule(config);
+            expect(result.finalSource).toEqual(
                 "export default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"eager\" */ '@symfony/mock-module/dist/controller.js'),\n};"
             );
+            expect(result.deprecations).toHaveLength(1);
         });
     });
 
-    describe('lazy-autoimport.json', () => {
-        it('must return a file with the enabled controller', () => {
-            const config = require('../fixtures/lazy-autoimport.json');
-            expect(createControllersModule(config)).toEqual(
-                "import '@symfony/mock-module/dist/style.css';\nexport default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"lazy\" */ '@symfony/mock-module/dist/controller.js'),\n};"
+    describe('eager-autoimport.json', () => {
+        it('must return a file with the enabled controller and auto-import', () => {
+            const config = require('../fixtures/eager-autoimport.json');
+            expect(createControllersModule(config).finalSource).toEqual(
+                "import '@symfony/mock-module/dist/style.css';\nexport default {\n  'symfony--mock-module--mock': import(/* webpackMode: \"eager\" */ '@symfony/mock-module/dist/controller.js'),\n};"
             );
         });
     });
 
     describe('lazy-controller-no-autoimport.json', () => {
-        it('must return a file with the enabled controller', () => {
-            const config = require('../fixtures/lazy-controller-no-autoimport.json');
-            expect(createControllersModule(config)).toEqual(
+        it('must return a file with a lazy controller', () => {
+            const config = require('../fixtures/lazy-no-autoimport.json');
+            expect(createControllersModule(config).finalSource).toEqual(
                 `
 import { Controller } from 'stimulus';
 export default {