Faut-il remplacer Webpack Encore par AssetMapper pour passer à Sylius 2 ?

Non. Le guide officiel de mise à niveau indique que Webpack est devenu le seul outil de build fourni par Sylius 2. La configuration de référence de Sylius-Standard 2.0 repose toujours sur Webpack Encore. Changer d'outil en même temps que la migration ajouterait un risque sans rien apporter.

Quelle version de Node.js faut-il pour Sylius 2 ?

Le guide UPGRADE-2.0 recommande Node.js 20 ou 22, le support de la version 18 ayant été abandonné. Vérifiez la version installée sur vos postes, sur la chaîne d'intégration continue et sur le serveur qui compile les assets.

Pourquoi le build front échoue-t-il après un simple composer update ?

Souvent parce que l'ancien dossier node_modules contient encore des paquets de Sylius 1.x. Le guide officiel conseille de le supprimer et de réinstaller les dépendances. En Sylius 2, les paquets du front pointent aussi vers le dossier vendor, donc Composer doit avoir tourné avant l'installation JavaScript.

Mes plugins Sylius ont-ils leurs propres assets à déclarer ?

Souvent, oui. Dans Sylius-Standard 2.0, un plugin de paiement importe son propre point d'entrée depuis le fichier assets/shop/entrypoint.js du projet. Lisez le README de chaque plugin porté en version 2 : l'étape d'import des assets y figure en général.

Comment migrer Webpack Encore vers le frontend Sylius 2 ?

On ne remplace pas Webpack Encore pour passer à Sylius 2 : il reste l'outil de build, et le guide officiel précise qu'il est désormais le seul fourni par Sylius. Ce qui change, c'est l'organisation autour de lui : les paquets JavaScript de Sylius sont chargés depuis le dossier vendor, la configuration de l'administration et de la boutique est générée par Sylius, vos propres assets passent par deux points d'entrée dédiés, et Stimulus est branché par un fichier controllers.json. La migration consiste donc à réaligner votre package.json et votre webpack.config.js sur ceux de Sylius-Standard 2.0, puis à y reporter vos ajouts.

Je suis développeur Sylius indépendant et j'ai mené des montées de version 1.x vers 2.x de boutiques en production. Cette partie est courte en jours, mais elle bloque tout le reste quand elle est mal faite : sans build qui passe, on ne peut tester aucune page. Elle mérite donc d'être traitée tôt, sur une branche dédiée.

Qu'est-ce qui change dans l'organisation frontend de Sylius 2 ?

Le plus simple est de comparer les fichiers de référence. Dans Sylius-Standard 1.14, le webpack.config.js déclarait lui-même les entrées de la boutique et de l'administration en pointant vers des fichiers du cœur, comme vendor/sylius/sylius/src/Sylius/Bundle/ShopBundle/Resources/private/entry.js, et définissait des alias sylius/ui, sylius/ui-resources et sylius/bundle. Le package.json dépendait de @sylius-ui/frontend et lançait semantic-ui-css-patch après installation.

Dans le webpack.config.js de Sylius-Standard 2.0, la configuration de l'administration et celle de la boutique sont fournies par Sylius, via SyliusAdmin.getWebpackConfig() et SyliusShop.getWebpackConfig(). Le projet ajoute deux configurations à lui, app.shop et app.admin, avec les entrées app-shop-entry et app-admin-entry qui partent de assets/shop/entrypoint.js et assets/admin/entrypoint.js. Chacune active le pont Stimulus avec son propre controllers.json et un alias @vendor vers le dossier vendor. Le fichier exporte quatre configurations.

Côté package.json, les paquets @sylius-ui/admin et @sylius-ui/shop pointent vers les bundles installés par Composer, avec une syntaxe file:vendor/sylius/sylius/src/Sylius/Bundle/.... On y trouve aussi les assets de Symfony UX Autocomplete et Live Component, @hotwired/stimulus, @symfony/stimulus-bridge et @symfony/webpack-encore en version 5.

Que dit la documentation officielle sur Webpack Encore ?

La partie front du guide UPGRADE-2.0 tient en quelques lignes, mais chacune compte. Les paquets Node inutilisés ou hérités ont été retirés et les autres mis à jour, avec la recommandation explicite de supprimer le dossier node_modules et de réinstaller. Les versions conseillées de Node.js sont 20 ou 22. L'option use_webpack de la configuration sylius_ui et la variable Twig du même nom ont disparu, Webpack étant toujours utilisé.

Pour le fonctionnement général d'Encore, la référence reste la documentation Webpack Encore de Symfony.

Comment migrer Webpack Encore, étape par étape ?

Repartir des fichiers de référence

Je ne retouche pas l'ancien webpack.config.js ligne par ligne. Je pars de celui de Sylius-Standard pour la version visée, puis j'y reporte uniquement ce que le projet ajoutait : entrées supplémentaires, copie d'images, réglages Sass, alias maison. Même chose pour le package.json : les dépendances de Sylius d'abord, vos bibliothèques ensuite, en vérifiant pour chacune qu'elle sert encore.

Déplacer vos assets dans les points d'entrée du projet

Vos feuilles de style, images et scripts se rangent sous assets/shop/ et assets/admin/, importés depuis les deux fichiers entrypoint.js. Les plugins suivent la même logique : dans Sylius-Standard 2.0, le plugin Mollie est chargé par une ligne d'import de son propre point d'entrée dans assets/shop/entrypoint.js. Chaque plugin porté en version 2 a sa procédure, à lire dans son README.

Brancher Stimulus

Les contrôleurs Stimulus de votre projet se déclarent dans assets/shop/controllers.json et assets/admin/controllers.json, ou dans un dossier controllers, selon le fonctionnement décrit par la documentation de StimulusBundle. La réécriture de vos scripts jQuery en contrôleurs est un chantier à part, que je détaille dans l'article sur l'adaptation du frontend existant à Symfony UX.

Remettre l'ordre de build dans votre déploiement

Comme @sylius-ui/admin et @sylius-ui/shop pointent vers le dossier vendor, l'installation JavaScript ne peut réussir qu'après composer install. Un script de déploiement ou une chaîne d'intégration continue qui installait les paquets Node en parallèle de Composer doit être revu. C'est un détail, mais c'est typiquement lui qui fait échouer une première mise en recette.

Quels pièges surveiller pendant la migration du build ?

Le premier est le dossier node_modules conservé « pour gagner du temps » : il garde des paquets de la 1.x et produit des erreurs incompréhensibles. Le second concerne les gabarits qui appelaient les anciennes entrées de build avec les fonctions encore_entry_link_tags et encore_entry_script_tags : si les noms d'entrée ou de configuration ont changé, la page s'affiche sans style ni script, sans erreur côté PHP. Le troisième est la version de Node du serveur de build, souvent plus ancienne que celle des postes de développement.

Pour le dirigeant, l'enjeu est simple : un build front qui casse en production, c'est une boutique qui s'affiche sans mise en page devant vos clients. Ce risque se traite en recette, pas le jour de la bascule. Si vous voulez savoir où en est votre configuration, le diagnostic de migration Sylius 2 l'inclut, avec le reste du chantier front décrit dans le guide sur la migration vers Bootstrap 5 et Stimulus.

Ce que je vous propose

La 1.14 n'a plus de correctifs de sécurité après le 31 décembre 2026. La configuration de build est l'une des premières marches du chantier : tant qu'elle ne passe pas, rien d'autre ne peut être testé. Je lance Sylius Upgrade Analyzer sur votre projet, je relis votre webpack.config.js, votre package.json et votre chaîne de déploiement, et je vous remets un diagnostic offert avec une estimation en jours. Je vous rappelle sous 24 heures ouvrées.