Symfony intègre un outil puissant appelé Webpack Encore, qui simplifie la gestion des ressources front-end (JavaScript, CSS, images, etc.). Basé sur Webpack, un module bundler open source, Webpack Encore est spécialement conçu pour faciliter l’intégration avec Symfony. Il permet de regrouper, optimiser, et minifier les fichiers front-end, tout en les rendant facilement accessibles dans vos templates.
Webpack est un outil qui regroupe et optimise les ressources JavaScript, CSS, et bien plus encore. Webpack Encore, quant à lui, est un wrapper simplifié de Webpack, adapté aux besoins de Symfony. Avec Encore, vous pouvez facilement inclure des dépendances front-end, gérer vos assets, et produire des fichiers optimisés pour la production.
Avantages de Webpack Encore :
- Simplification de la configuration Webpack.
- Gestion des dépendances CSS et JavaScript via NPM.
- Optimisation des performances (minification, regroupement).
- Intégration directe avec Symfony via Twig.
Installation
a) Prérequis
Avant d’installer Webpack Encore, vous devez installer Node.js et son gestionnaire de paquets NPM. Ces outils sont nécessaires pour télécharger et gérer les dépendances front-end.
- Téléchargez Node.js depuis https://nodejs.org/en/download/.
- Installez éventuellement Yarn comme gestionnaire de paquets alternatif (facultatif).
b) Installation de Webpack Encore
- Installez le bundle Webpack Encore :
composer require symfony/webpack-encore-bundle - Initialisez les dépendances front-end avec NPM :
npm install
Après l’installation, plusieurs modifications seront apportées à votre projet :
- Un dossier
assets/sera créé pour contenir les fichiers front-end. - Un fichier
webpack.config.jssera généré à la racine pour configurer Webpack. - Un fichier
package.jsonsera créé pour référencer les dépendances JavaScript. - Un répertoire
node_modules/sera ajouté pour stocker les packages front-end téléchargés.
Structure des Fichiers Après Installation
Contenu du dossier assets/ :
- app.js : Le fichier principal où les dépendances JavaScript et CSS sont importées.
- styles/app.css : Le fichier principal pour vos styles CSS.
- bootstrap.js : Initialise l’application Stimulus (utilisée pour les interactions dynamiques).
- controllers.json et controllers/hello_controller.js : Liés à Stimulus pour des contrôleurs JavaScript modulaires.
Utilisation de Webpack Encore
a) Importer des ressources dans app.js
Le fichier app.js sert de point d’entrée pour regrouper toutes les ressources front-end :
// Importer les styles CSS
import './styles/app.css';
// Démarrer l'application Stimulus
import './bootstrap';
Toutes les dépendances CSS et JavaScript doivent être référencées ici pour être incluses dans les fichiers regroupés.
b) Référencer les fichiers dans les templates Twig
Après la compilation des fichiers, les assets sont accessibles via les fonctions Twig encore_entry_link_tags et encore_entry_script_tags. Ces fonctions injectent automatiquement les balises nécessaires pour inclure les fichiers CSS et JS dans vos pages.
Exemple dans base.html.twig :
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Bienvenue{% endblock %}</title>
{% block stylesheets %}
{{ encore_entry_link_tags('app') }}
{% endblock %}
</head>
<body>
{% block body %}Contenu de la page{% endblock %}
{% block javascripts %}
{{ encore_entry_script_tags('app') }}
{% endblock %}
</body>
</html>
c) Construire les fichiers front-end
- Mode développement avec surveillance : Pendant le développement, utilisez la commande suivante pour surveiller les modifications des fichiers et les recompiler automatiquement :
npm run watch - Mode production (optimisé) : Avant de déployer l’application, exécutez une construction optimisée :
npm run build
Les fichiers générés se trouveront dans public/build/ :
app.js: Regroupe tout le JavaScript.app.css: Regroupe tout le CSS.runtime.js: Contient le code utilitaire nécessaire à Webpack.
Configuration de Webpack Encore
Le fichier webpack.config.js à la racine du projet permet de personnaliser la configuration de Webpack Encore. Par défaut, il inclut les réglages nécessaires pour gérer JavaScript, CSS, images, et polices.
Exemple de configuration de base :
const Encore = require('@symfony/webpack-encore');
Encore
.setOutputPath('public/build/')
.setPublicPath('/build')
.addEntry('app', './assets/app.js')
.enableSingleRuntimeChunk()
.cleanupOutputBeforeBuild()
.enableSourceMaps(!Encore.isProduction())
.enableVersioning(Encore.isProduction())
.enablePostCssLoader();
module.exports = Encore.getWebpackConfig();
Ajouter des Dépendances Front-End
Vous pouvez installer et inclure des bibliothèques CSS et JavaScript avec NPM. Par exemple :
a) Installer Bootstrap :
npm install bootstrap
b) Ajouter Bootstrap dans app.js :
// Importer les styles Bootstrap
import 'bootstrap/dist/css/bootstrap.min.css';
// Importer les scripts Bootstrap
import 'bootstrap';
c) Référencer dans les templates :
Les balises Twig injecteront automatiquement les fichiers Bootstrap grâce à encore_entry_*.
Bonnes Pratiques
- Minimiser les dépendances : Installez uniquement les packages nécessaires pour éviter de surcharger
node_modules. - Versioning : Utilisez l’option
enableVersioning()pour invalider le cache en production. - Nettoyer les fichiers : La commande
cleanupOutputBeforeBuild()supprime les anciens fichiers générés avant chaque nouvelle construction.
Webpack Encore est un outil puissant et flexible pour gérer le frontend dans une application Symfony. Il simplifie la gestion des assets tout en offrant des fonctionnalités avancées comme la minification, le versioning, et la prise en charge des dépendances front-end. En l’adoptant, vous pouvez améliorer la performance, la maintenabilité, et l’apparence de vos applications web.
