Recommend NPM instead of Yarn

[nicolas-grekas]

Q	A
License	MIT
Doc issue/PR	-

/cc @weaverryan @dunglas

[github-actions]

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-1229/index.json
   # On Windows
   SET SYMFONY_ENDPOINT=https://raw.githubusercontent.com/symfony/recipes/flex/pull-1229/index.json

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

   composer req 'symfony/flex:^1.16'
   composer req 'api-platform/admin-pack:^1.0' 'symfony/webpack-encore-bundle:^2.0'

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/config/packages/webpack_encore.yaml b/symfony/webpack-encore-bundle/1.10/config/packages/webpack_encore.yaml
index 46834f0..4c009ee 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
@@ -25,14 +25,10 @@ webpack_encore:
 
     # 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
+        # pass the build name as the 3rd argument to the Twig functions
+        # {{ encore_entry_script_tags('entry1', null, 'frontend') }}
 
 framework:
     assets:
diff --git a/symfony/webpack-encore-bundle/1.9/manifest.json b/symfony/webpack-encore-bundle/1.10/manifest.json
index 84ab396..39b0363 100644
--- a/symfony/webpack-encore-bundle/1.9/manifest.json
+++ b/symfony/webpack-encore-bundle/1.10/manifest.json
@@ -8,11 +8,14 @@
         "package.json": "package.json",
         "webpack.config.js": "webpack.config.js"
     },
-    "aliases": ["ux", "encore", "webpack", "webpack-encore"],
+    "aliases": ["encore", "webpack", "webpack-encore"],
     "gitignore": [
         "/node_modules/",
         "/%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..d83a414 100644
--- a/symfony/webpack-encore-bundle/1.9/package.json
+++ b/symfony/webpack-encore-bundle/1.10/package.json
@@ -1,11 +1,15 @@
 {
     "devDependencies": {
+        "@babel/core": "^7.17.0",
+        "@babel/preset-env": "^7.16.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",
-        "webpack-notifier": "^1.6.0"
+        "@symfony/stimulus-bridge": "^3.2.0",
+        "@symfony/webpack-encore": "^4.0.0",
+        "core-js": "^3.23.0",
+        "regenerator-runtime": "^0.13.9",
+        "webpack": "^5.74.0",
+        "webpack-cli": "^4.10.0",
+        "webpack-notifier": "^1.15.0"
     },
     "license": "UNLICENSED",
     "private": true,
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..408012f 100644
--- a/symfony/webpack-encore-bundle/1.9/webpack.config.js
+++ b/symfony/webpack-encore-bundle/1.10/webpack.config.js
@@ -11,7 +11,7 @@ Encore
     .setOutputPath('public/build/')
     // public path used by the web server to access the output path
     .setPublicPath('/build')
-    // only needed for CDN's or sub-directory deploy
+    // only needed for CDN's or subdirectory deploy
     //.setManifestKeyPrefix('build/')
 
     /*
@@ -45,14 +45,15 @@ Encore
     // enables hashed filenames (e.g. app.abc123.css)
     .enableVersioning(Encore.isProduction())
 
-    .configureBabel((config) => {
-        config.plugins.push('@babel/plugin-proposal-class-properties');
-    })
+    // configure Babel
+    // .configureBabel((config) => {
+    //     config.plugins.push('@babel/a-babel-plugin');
+    // })
 
-    // enables @babel/preset-env polyfills
+    // enables and configure @babel/preset-env polyfills
     .configureBabelPresetEnv((config) => {
         config.useBuiltIns = 'usage';
-        config.corejs = 3;
+        config.corejs = '3.23';
     })
 
     // enables Sass/SCSS support

1.10 vs 2.0

diff --git a/symfony/webpack-encore-bundle/1.10/assets/app.js b/symfony/webpack-encore-bundle/2.0/assets/app.js
index bb0a6aa..8506504 100644
--- a/symfony/webpack-encore-bundle/1.10/assets/app.js
+++ b/symfony/webpack-encore-bundle/2.0/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.10/assets/bootstrap.js b/symfony/webpack-encore-bundle/1.10/assets/bootstrap.js
deleted file mode 100644
index 4ab2df6..0000000
--- a/symfony/webpack-encore-bundle/1.10/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.10/assets/controllers/hello_controller.js b/symfony/webpack-encore-bundle/1.10/assets/controllers/hello_controller.js
deleted file mode 100644
index e847027..0000000
--- a/symfony/webpack-encore-bundle/1.10/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.10/assets/controllers.json b/symfony/webpack-encore-bundle/1.10/assets/controllers.json
deleted file mode 100644
index a1c6e90..0000000
--- a/symfony/webpack-encore-bundle/1.10/assets/controllers.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-    "controllers": [],
-    "entrypoints": []
-}
diff --git a/symfony/webpack-encore-bundle/1.10/manifest.json b/symfony/webpack-encore-bundle/2.0/manifest.json
index 39b0363..6c2c542 100644
--- a/symfony/webpack-encore-bundle/1.10/manifest.json
+++ b/symfony/webpack-encore-bundle/2.0/manifest.json
@@ -8,7 +8,7 @@
         "package.json": "package.json",
         "webpack.config.js": "webpack.config.js"
     },
-    "aliases": ["encore", "webpack", "webpack-encore"],
+    "aliases": ["ux", "encore", "webpack", "webpack-encore"],
     "gitignore": [
         "/node_modules/",
         "/%PUBLIC_DIR%/build/",
@@ -16,6 +16,23 @@
         "yarn-error.log"
     ],
     "conflict": {
-        "symfony/framework-bundle": "<5.4"
-    }
+        "symfony/framework-bundle": "<5.4",
+        "symfony/flex": "<1.20.0 || >=2.0.0,<2.3.0"
+    },
+    "add-lines": [
+        {
+            "file": "templates/base.html.twig",
+            "content": "            {{ encore_entry_script_tags('app') }}",
+            "position": "after_target",
+            "target": "{% block javascripts %}",
+            "warn_if_missing": true
+        },
+        {
+            "file": "templates/base.html.twig",
+            "content": "            {{ encore_entry_link_tags('app') }}",
+            "position": "after_target",
+            "target": "{% block stylesheets %}",
+            "warn_if_missing": true
+        }
+    ]
 }
diff --git a/symfony/webpack-encore-bundle/1.10/package.json b/symfony/webpack-encore-bundle/2.0/package.json
index d83a414..b4ce2a6 100644
--- a/symfony/webpack-encore-bundle/1.10/package.json
+++ b/symfony/webpack-encore-bundle/2.0/package.json
@@ -2,8 +2,6 @@
     "devDependencies": {
         "@babel/core": "^7.17.0",
         "@babel/preset-env": "^7.16.0",
-        "@hotwired/stimulus": "^3.0.0",
-        "@symfony/stimulus-bridge": "^3.2.0",
         "@symfony/webpack-encore": "^4.0.0",
         "core-js": "^3.23.0",
         "regenerator-runtime": "^0.13.9",
diff --git a/symfony/webpack-encore-bundle/1.10/post-install.txt b/symfony/webpack-encore-bundle/2.0/post-install.txt
index e53f05d..b55c0c9 100644
--- a/symfony/webpack-encore-bundle/1.10/post-install.txt
+++ b/symfony/webpack-encore-bundle/2.0/post-install.txt
@@ -1,3 +1,5 @@
-  * Install Yarn and run yarn install
+  * Install NPM and run npm install
 
-  * Start the development server: yarn encore dev-server
+  * Compile your assets: npm run dev
+
+  * Or start the development server: npm run watch
diff --git a/symfony/webpack-encore-bundle/1.10/webpack.config.js b/symfony/webpack-encore-bundle/2.0/webpack.config.js
index 408012f..9d752df 100644
--- a/symfony/webpack-encore-bundle/1.10/webpack.config.js
+++ b/symfony/webpack-encore-bundle/2.0/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()
 

[melroy89]

Just for info. I would like to see the demo also move to NPM (package-lock.json): https://github.com/symfony/demo

[stollr]

I'm curious as to why the recommendation was changed from Yarn to NPM. Are there any information?

[stof]

Back when we started this recommendation (when introducing webpack-encore), yarn was strictly superior to npm, mostly thanks to having a proper lockfile (at that time, npm did not have package-lock.json but only the shrinkwrap mechanism) and being faster.
Since then, npm has caught up on those fronts. And it has the big benefit of being installed by default when you install node, which requires 1 less step.
Note however that webpack-encore is not dropping support for yarn (it tests compatibility with several package managers) and so you can keep using yarn if you prefer (or pnpm for that matter)

[stollr]

This makes sense. Thanks for your explanation.