[RCF][WIP] Proposed symfony/ux-meta Recipe

[weaverryan]

Q	A
License	MIT
Doc issue/PR	Later if accepted

This is a proposal to split Stimulus/Symfony UX out of the symfony/webpack-encore-bundle. 2 reasons:

1. Some people (e.g. #1089) don't want Stimulus. Alone, I don't personally think this is a good enough reason. You have to optimize one path, it won't work for everyone.

2. Separating it MAY make the purpose and functionality of Symfony UX more clear. Currently, to install Symfony UX, you run composer require symfony/webpack-encore-bundle... which is a little weird. After, you would run composer require symfony/ux. THAT is quite beautiful 😄

How it would work:

• A) We create a new symfony/ux-package which requires symfony/webpack-encore-bundle and symfony/ux-meta

• B) We create a new symfony/ux-meta package. This will hold the "full UX setup", which is equivalent to the current symfony/webpack-encore-bundle recipe.

That's it! When you run composer require symfony/ux, it will install WebpackEncoreBundle, but thesymfony/ux-meta recipe will take precedence.

Complications

• i) In the future, when people run composer recipes:update symfony/webpack-encore-bundle, it will try to delete some files like assets/controllers.json, assets/bootstrap.js and will try to remove the import './bootstrap' line from assets/app.js. A blog post about what's happening could alleviate this.
• ii) If you install symfony/webpack-encore-bundle FIRST and THEN symfony/ux, you will NOT have a complete setup. You will be missing the import './bootstrap' line from assets/app.js, 2 packages from package.json and 1 line from webpack.config.js.

To fix (ii), we would need (A) a simple "patch" system in Flex to basically "insert" some a line into the middle of an existing file (e.g. webpack.config.js or assets/app.js and (B) a Flex configurator for package.json (we have such a thing, but we would need to extend it to read some packages from manifest.json.

Relates to #1089

[github-actions[bot]]

Thanks for the PR 😍

How to test these changes in your application

1. Define the SYMFONY_ENDPOINT environment variable:

   # On Unix-like (BSD, Linux and macOS)
   export SYMFONY_ENDPOINT=https://raw.githubusercontent.com/symfony/recipes/flex/pull-1090/index.json
   # On Windows
   SET SYMFONY_ENDPOINT=https://raw.githubusercontent.com/symfony/recipes/flex/pull-1090/index.json
   

2. Install the package(s) related to this recipe:

   composer req 'symfony/flex:^1.16'
   composer req 'symfony/ux-meta:^1.0' 'symfony/webpack-encore-bundle:^1.10'
   

3. Don't forget to unset the SYMFONY_ENDPOINT environment variable when done:

   # On Unix-like (BSD, Linux and macOS)
   unset SYMFONY_ENDPOINT
   # On Windows
   SET SYMFONY_ENDPOINT=
   

Diff between recipe versions

In order to help with the review stage, I'm in charge of computing the diff between the various versions of patched recipes. I'm going keep this comment up to date with any updates of the attached patch.

symfony/webpack-encore-bundle

1.0 vs 1.6

diff --git a/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml
new file mode 100644
index 0000000..02a7651
--- /dev/null
+++ b/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml
@@ -0,0 +1,2 @@
+#webpack_encore:
+#    strict_mode: false
diff --git a/symfony/webpack-encore-bundle/1.0/config/packages/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.6/config/packages/webpack_encore.yaml
index ce02f6b..a1335c5 100644
--- a/symfony/webpack-encore-bundle/1.0/config/packages/webpack_encore.yaml
+++ b/symfony/webpack-encore-bundle/1.6/config/packages/webpack_encore.yaml
@@ -1,14 +1,25 @@
 webpack_encore:
-    # The path where Encore is building the assets.
-    # This should match Encore.setOutputPath() in webpack.config.js.
+    # The path where Encore is building the assets - i.e. Encore.setOutputPath()
     output_path: '%kernel.project_dir%/public/build'
     # If multiple builds are defined (as shown below), you can disable the default build:
     # output_path: false
 
-    # if using Encore.enableIntegrityHashes() specify the crossorigin attribute value (default: false, or use 'anonymous' or 'use-credentials')
+    # If using Encore.enableIntegrityHashes() and need the crossorigin attribute (default: false, or use 'anonymous' or 'use-credentials')
     # crossorigin: 'anonymous'
 
-    # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes).
-    # To enable caching for the production environment, creating a webpack_encore.yaml in the config/packages/prod directory with this value set to true
-    # Available in version 1.2
-    #cache: false
+    # Preload all rendered script and link tags automatically via the HTTP/2 Link header
+    # preload: true
+
+    # Throw an exception if the entrypoints.json file is missing or an entry is missing from the data
+    # strict_mode: false
+
+    # If you have multiple builds:
+    # builds:
+        # pass "frontend" as the 3rg arg to the Twig functions
+        # {{ encore_entry_script_tags('entry1', null, 'frontend') }}
+
+        # frontend: '%kernel.project_dir%/public/frontend/build'
+
+    # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
+    # Put in config/packages/prod/webpack_encore.yaml
+    # cache: true

1.6 vs 1.9

diff --git a/symfony/webpack-encore-bundle/1.6/assets/controllers/hello_controller.js b/symfony/webpack-encore-bundle/1.9/assets/controllers/hello_controller.js
index 8c79f65..e847027 100644
--- a/symfony/webpack-encore-bundle/1.6/assets/controllers/hello_controller.js
+++ b/symfony/webpack-encore-bundle/1.9/assets/controllers/hello_controller.js
@@ -1,4 +1,4 @@
-import { Controller } from 'stimulus';
+import { Controller } from '@hotwired/stimulus';
 
 /*
  * This is an example Stimulus controller!
diff --git a/symfony/webpack-encore-bundle/1.6/config/packages/assets.yaml b/symfony/webpack-encore-bundle/1.6/config/packages/assets.yaml
deleted file mode 100644
index 051d36d..0000000
--- a/symfony/webpack-encore-bundle/1.6/config/packages/assets.yaml
+++ /dev/null
@@ -1,3 +0,0 @@
-framework:
-    assets:
-        json_manifest_path: '%kernel.project_dir%/public/build/manifest.json'
diff --git a/symfony/webpack-encore-bundle/1.6/config/packages/prod/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.6/config/packages/prod/webpack_encore.yaml
deleted file mode 100644
index d0b3ba8..0000000
--- a/symfony/webpack-encore-bundle/1.6/config/packages/prod/webpack_encore.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-#webpack_encore:
-    # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
-    # Available in version 1.2
-    #cache: true
diff --git a/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml
deleted file mode 100644
index 02a7651..0000000
--- a/symfony/webpack-encore-bundle/1.6/config/packages/test/webpack_encore.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-#webpack_encore:
-#    strict_mode: false
diff --git a/symfony/webpack-encore-bundle/1.6/config/packages/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.9/config/packages/webpack_encore.yaml
index a1335c5..46834f0 100644
--- a/symfony/webpack-encore-bundle/1.6/config/packages/webpack_encore.yaml
+++ b/symfony/webpack-encore-bundle/1.9/config/packages/webpack_encore.yaml
@@ -4,6 +4,16 @@ webpack_encore:
     # If multiple builds are defined (as shown below), you can disable the default build:
     # output_path: false
 
+    # Set attributes that will be rendered on all script and link tags
+    script_attributes:
+        defer: true
+        # Uncomment (also under link_attributes) if using Turbo Drive
+        # https://turbo.hotwired.dev/handbook/drive#reloading-when-assets-change
+        # 'data-turbo-track': reload
+    # link_attributes:
+        # Uncomment if using Turbo Drive
+        # 'data-turbo-track': reload
+
     # If using Encore.enableIntegrityHashes() and need the crossorigin attribute (default: false, or use 'anonymous' or 'use-credentials')
     # crossorigin: 'anonymous'
 
@@ -23,3 +33,17 @@ webpack_encore:
     # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
     # Put in config/packages/prod/webpack_encore.yaml
     # cache: true
+
+framework:
+    assets:
+        json_manifest_path: '%kernel.project_dir%/public/build/manifest.json'
+
+#when@prod:
+#    webpack_encore:
+#        # Cache the entrypoints.json (rebuild Symfony's cache when entrypoints.json changes)
+#        # Available in version 1.2
+#        cache: true
+
+#when@test:
+#    webpack_encore:
+#        strict_mode: false
diff --git a/symfony/webpack-encore-bundle/1.6/package.json b/symfony/webpack-encore-bundle/1.9/package.json
index ba0e4f4..813010a 100644
--- a/symfony/webpack-encore-bundle/1.6/package.json
+++ b/symfony/webpack-encore-bundle/1.9/package.json
@@ -1,10 +1,10 @@
 {
     "devDependencies": {
-        "@symfony/stimulus-bridge": "^2.0.0",
-        "@symfony/webpack-encore": "^1.0.0",
+        "@hotwired/stimulus": "^3.0.0",
+        "@symfony/stimulus-bridge": "^3.0.0",
+        "@symfony/webpack-encore": "^1.7.0",
         "core-js": "^3.0.0",
         "regenerator-runtime": "^0.13.2",
-        "stimulus": "^2.0.0",
         "webpack-notifier": "^1.6.0"
     },
     "license": "UNLICENSED",
diff --git a/symfony/webpack-encore-bundle/1.9/post-install.txt b/symfony/webpack-encore-bundle/1.9/post-install.txt
new file mode 100644
index 0000000..6169d37
--- /dev/null
+++ b/symfony/webpack-encore-bundle/1.9/post-install.txt
@@ -0,0 +1,5 @@
+  * Install Yarn and run yarn install
+
+  * Uncomment the Twig helpers in templates/base.html.twig (they may be already)
+
+  * Start the development server: yarn encore dev-server

1.9 vs 1.10

diff --git a/symfony/webpack-encore-bundle/1.9/assets/app.js b/symfony/webpack-encore-bundle/1.10/assets/app.js
index bb0a6aa..8506504 100644
--- a/symfony/webpack-encore-bundle/1.9/assets/app.js
+++ b/symfony/webpack-encore-bundle/1.10/assets/app.js
@@ -7,6 +7,3 @@
 
 // any CSS you import will output into a single css file (app.css in this case)
 import './styles/app.css';
-
-// start the Stimulus application
-import './bootstrap';
diff --git a/symfony/webpack-encore-bundle/1.9/assets/bootstrap.js b/symfony/webpack-encore-bundle/1.9/assets/bootstrap.js
deleted file mode 100644
index 4ab2df6..0000000
--- a/symfony/webpack-encore-bundle/1.9/assets/bootstrap.js
+++ /dev/null
@@ -1,11 +0,0 @@
-import { startStimulusApp } from '@symfony/stimulus-bridge';
-
-// Registers Stimulus controllers from controllers.json and in the controllers/ directory
-export const app = startStimulusApp(require.context(
-    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
-    true,
-    /\.[jt]sx?$/
-));
-
-// register any custom, 3rd party controllers here
-// app.register('some_controller_name', SomeImportedController);
diff --git a/symfony/webpack-encore-bundle/1.9/assets/controllers/hello_controller.js b/symfony/webpack-encore-bundle/1.9/assets/controllers/hello_controller.js
deleted file mode 100644
index e847027..0000000
--- a/symfony/webpack-encore-bundle/1.9/assets/controllers/hello_controller.js
+++ /dev/null
@@ -1,16 +0,0 @@
-import { Controller } from '@hotwired/stimulus';
-
-/*
- * This is an example Stimulus controller!
- *
- * Any element with a data-controller="hello" attribute will cause
- * this controller to be executed. The name "hello" comes from the filename:
- * hello_controller.js -> "hello"
- *
- * Delete this file or adapt it for your use!
- */
-export default class extends Controller {
-    connect() {
-        this.element.textContent = 'Hello Stimulus! Edit me in assets/controllers/hello_controller.js';
-    }
-}
diff --git a/symfony/webpack-encore-bundle/1.9/assets/controllers.json b/symfony/webpack-encore-bundle/1.9/assets/controllers.json
deleted file mode 100644
index a1c6e90..0000000
--- a/symfony/webpack-encore-bundle/1.9/assets/controllers.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-    "controllers": [],
-    "entrypoints": []
-}
diff --git a/symfony/webpack-encore-bundle/1.9/config/packages/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.10/config/packages/webpack_encore.yaml
index 46834f0..e38afc4 100644
--- a/symfony/webpack-encore-bundle/1.9/config/packages/webpack_encore.yaml
+++ b/symfony/webpack-encore-bundle/1.10/config/packages/webpack_encore.yaml
@@ -20,8 +20,8 @@ webpack_encore:
     # Preload all rendered script and link tags automatically via the HTTP/2 Link header
     # preload: true
 
-    # Throw an exception if the entrypoints.json file is missing or an entry is missing from the data
-    # strict_mode: false
+    # Set to true to throw an exception if the entrypoints.json file is missing or an entry is missing from the data
+    strict_mode: false
 
     # If you have multiple builds:
     # builds:
diff --git a/symfony/webpack-encore-bundle/1.9/manifest.json b/symfony/webpack-encore-bundle/1.10/manifest.json
index 84ab396..a2728ca 100644
--- a/symfony/webpack-encore-bundle/1.9/manifest.json
+++ b/symfony/webpack-encore-bundle/1.10/manifest.json
@@ -14,5 +14,8 @@
         "/%PUBLIC_DIR%/build/",
         "npm-debug.log",
         "yarn-error.log"
-    ]
+    ],
+    "conflict": {
+        "symfony/framework-bundle": "<5.4"
+    }
 }
diff --git a/symfony/webpack-encore-bundle/1.9/package.json b/symfony/webpack-encore-bundle/1.10/package.json
index 813010a..b6fc583 100644
--- a/symfony/webpack-encore-bundle/1.9/package.json
+++ b/symfony/webpack-encore-bundle/1.10/package.json
@@ -1,8 +1,6 @@
 {
     "devDependencies": {
-        "@hotwired/stimulus": "^3.0.0",
-        "@symfony/stimulus-bridge": "^3.0.0",
-        "@symfony/webpack-encore": "^1.7.0",
+        "@symfony/webpack-encore": "^2.0.0",
         "core-js": "^3.0.0",
         "regenerator-runtime": "^0.13.2",
         "webpack-notifier": "^1.6.0"
diff --git a/symfony/webpack-encore-bundle/1.9/post-install.txt b/symfony/webpack-encore-bundle/1.10/post-install.txt
index 6169d37..e53f05d 100644
--- a/symfony/webpack-encore-bundle/1.9/post-install.txt
+++ b/symfony/webpack-encore-bundle/1.10/post-install.txt
@@ -1,5 +1,3 @@
   * Install Yarn and run yarn install
 
-  * Uncomment the Twig helpers in templates/base.html.twig (they may be already)
-
   * Start the development server: yarn encore dev-server
diff --git a/symfony/webpack-encore-bundle/1.9/webpack.config.js b/symfony/webpack-encore-bundle/1.10/webpack.config.js
index 056b04a..915c26a 100644
--- a/symfony/webpack-encore-bundle/1.9/webpack.config.js
+++ b/symfony/webpack-encore-bundle/1.10/webpack.config.js
@@ -22,9 +22,6 @@ Encore
      */
     .addEntry('app', './assets/app.js')
 
-    // enables the Symfony UX Stimulus bridge (used in assets/bootstrap.js)
-    .enableStimulusBridge('./assets/controllers.json')
-
     // When enabled, Webpack "splits" your files into smaller pieces for greater optimization.
     .splitEntryChunks()
 

[fabpot]

@weaverryan What do we need to move forward here?

[weaverryan]

I can close this for now. I DO think we should split the Stimulus stuff out of WebpackEncoreBundle into its own package. When we do that, some recipe changes will be needed and we can revisit.