Compiler SCSS et JS comme un pro sous WordPress avec… WebPack Encore !

WordPress ne proposant pas par défaut de solution pour compiler les assets (SCSS, JS, fonts, images…), de nombreuses manières d'y parvenir aux philosophies parfois antagonistes se sont développées. Voici ma solution de prédilection, inspirée de mes expériences avec le framework Symfony : WebPack Encore.

J'ai longtemps été adepte successivement de Grunt puis Gulp, pour compiler mes fichiers assets dans WordPress. En me formant sur le framework Symfony il y a quelques années, j'ai été agréablement surpris de la facilité avec laquelle cette question était gérée, et me suis mis en tête d'intégrer cet outil à WordPress.

WebPack est une solution éprouvée pour créer un bundle unique de nos application.

Il va gérer pour nous :

• La possibilité de faire des imports de modules dans nos fichiers JS (on oublie vite que nos précédents scripts ne faisaient que les concaténer ensemble…)
• La génération d'un fichier d'entrée unique en JS, tout en gardant la possibilité de découper notre application en modules chargés de manière conditionnelle
• Un loader unique pour JS et SCSS (dont Tailwind)
• La possibilité d'étendre sa configuration avec de nombreuses librairies : SVG, PostCSS...
• Un autoprefixage et une transpilation ES5 automatiques via Babel : Très clairement, on peut oublier ces questions une bonne fois pour toutes
• La possibilité de versionner nos nom de fichiers : Finis les problèmes de vidage de cache à chaque mise à jour !
• Mais surtout : la possibilité d'installer toutes tes librairies front-end via le dépôt de paquets npm ou yarn

Avec un peu de configuration tu pourras même y ajouter un système de Hot Module Reloading.

Il est surtout, selon moi, un prérequis indispensable pour te passer définitivement de jQuery sur tes sites et pouvoir, enfin, faire du front moderne :

Toutefois, un des inconvénients de WebPack, à mon sens, est qu'il n'est pas facile d'accès pour qui ne s'en est jamais servi, et semble être une discipline à lui tout seul à en voir sa documentation. C'est ici que Symfony Encore va venir nous aider.

Symfony Encore est un wrapper pour la configuration de Webpack. Il va en simplifier grandement la configuration en rajoutant une couche d'abstraction par-dessus celle-ci.

Et à vrai dire, il ne fait rien de plus : en soi la configuration produite par Encore pourrait être écrite à la main… L'avantage ici est que tout est quasiment prêt dès l'installation, et les fonctionnalités principales ont été encapsulées dans des fonctions nommées !

Ainsi, en une seule ligne de configuration tu vas être en mesure de :

• Régler tous tes problèmes avec jQuery en l'intégrant d'office dans tous tes modules (si tu t'es déjà arraché les cheveux avec l'erreur jQuery is not defined tu vois de quoi je parle…)
• Intégrer une solution de tests unitaires (comme Jest) à ton application WordPress
• Activer la prise en charge de TypeScript (oui, faire du TypeScript dans WordPress devient un jeu d'enfant !)
• La possibilité à tout moment d'étendre cette configuration avec un object WebPack classique

C'est un outil initialement développé par l'équipe de Symfony, et intégré au framework éponyme. Mais comme chacun de leurs modules (appelés bundles), il est utilisable indépendamment : Il est ainsi possible de l'intégrer à tout type de projets, dont un site WordPress.

WebPack est un outil en ligne de commande en nodeJS, aussi nous allons avoir besoin d'utiliser le terminal avec nodeJS et npm installés (J'explique dans un article comment configurer ton workflow).

Si à la lecture des mots "ligne de commande" tu as pris peur, ne fuis pas ! C'est plus simple que tu ne le crois, vraiment. Je t'invites à lire cet article : STOP à l'angoisse de la ligne de commande.

Idéalement, assure-toi d'utiliser la bonne version de nodeJS, idéalement la version 16 qui est en Long Term Support (LTS) : C'est, à mon sens, celle qui t'assurera la meilleure compatibilité avec les librairies que tu comptes utiliser. Mon article sur Comment switcher facilement de version de nodeJS peut t'être utile !

Nous allons commencer par installer la librairie via notre Package Manager préféré (NPM ou Yarn) :

Je recommande généralement d'utiliser Yarn pour des questions de rapidité, mais l'important est de continuer à utiliser celui déjà en place sur ton projet.

Nous allons devoir créer un petit fichier de configuration pour WebPack. C'est lui qui contiendra l'ensemble des instructions que devra exécuter WebPack lorsque nous lancerons la compilation :

C'est le moment où la magie opère ! Nous allons pouvoir tester noter configuration en lançant cette commande :

Si tout se passe bien, le script devrait se terminer avec un beau message vert t'indiquant que tes fichiers ont été générés dans le dossier spécifié comme outputPath, ici /dist.

Avec la commande dev, tes assets ont été générés en mode développement : Ce sera facile de débugger grâce aux fichiers .map. Toutefois, pour envoyer nos fichiers en ligne il sera préférable de les générer avec la commande suivante :

Enfin, voici la commande magique qui va te permettre, en mode développement, de regénérer automatiquement tes assets à la volée :

Concrètement, tu lance cette commande au début de ta session de travail et tu travailles sur tes fichiers sources comme à ton habitude : Comme tout watcher, il va mettre à jour automatiquement ton dossier /dist à chaque changement dans l'un de tes fichier source ou t'indiquer si des erreurs dans ton code empêchent leur compilation. L'essayer, c'est l'adopter.

A la différence de certaines implémentations que j'ai pu croiser, je n'utilise pas de loader pour la partie PHP, jugeant plus simple de charger le fichier app.js directement via la méthode classique :

Toutefois, si tu souhaites également automatiser l'enqueue des assets dans le thème WordPress (pour pouvoir activer le versionning des noms de fichiers par exemple), tu peux t'inspirer de ce loader développé par un développeur tiers : https://github.com/PhatKoala/webpack-encore-for-wordpress/blob/master/webpack-encore.php

Pense bien à mettre le dossier node_modules dans ton fichier .gitignore à la racine de ton projet. De cette manière, il ne sera pas versionné avec le reste de tes fichiers.

Idéalement, les fichiers suivants devraient être commités avec le reste de ton projet :

• Le fichier de configuration webpack.config.json
• Les fichier package.json et package-lock.json
• Les fichiers sources de tes assets

Je ne peux que t'encourager à ne pas versionner le dossier dist contenant tes fichiers générés, et de le compiler à la volée lors de tes déploiements. (Nous verrons ensemble dans un prochain article toutes les solutions pouvant être utilisées à cette fin)

A la lecture de cette configuration tu te demanderas peut-être pourquoi je place mes fichiers compilés à la racine de mon site plutôt que dans le thème comme c'est habituellement l'usage.

Je ne suis pas fan de compiler mes fichiers dans le thème WordPress, et lui préfère un dossier dist/ placé à la racine du projet. Et ce pour différentes raisons :

• Je souhaite garder la possibilité de compiler des fichiers issus de plugins et de thèmes enfants dans mon fichier principal, afin d'améliorer les performances de mon site
• J'aime avoir des URLs propres pour mes assets et pouvoir les appeler sans avoir à connaitre le nom de mon thème. Cela limite au passage les footprints WordPress.
• Cela me facilite la vie dans la configuration de mon outil de déploiement : PHPDeployer (voir article)

Il s'agit d'un choix personnel, rien ne t'empêche de placer le dossier dist/ où tu veux en adaptant le code fourni !

WebPack Encore lève de nombreux freins à l'adoption de WebPack sous WordPress. Si tu souhaites obtenir une configuration rapide de ce dernier, Symfony Encore est une solution robuste, maintenue et extensible. Quand je te dit que Symfony et WordPress peuvent faire bon ménage :P

Je t'invite bien entendu à aller consulter la documentation de WebPack et Encore pour étendre leurs possibilités :

• Utilisation de TypeScript
• Configuration de Babel
• Intégration de TailwindCSS
• Mise en place de tests d'intégration...

Si pour une raison ou une autre cette solution ne te satisfaisait pas (je veux bien en connaître les raisons en commentaire !), je te propose deux alternatives pour utiliser WebPack avec WordPress :

• L'intégration de WebPack directement dans Gulp (lien externe)

• J'ai effectué la même opération avec Laravel Mix, l'équivalent de Symfony WebPack Encore pour Laravel. La configuration est plus simple, mais les options sont à mon goût moins avancées. On en reparle prochainement !

Je suis curieux de savoir quelle solution a retenu tes faveurs... Pour ma part WebPack Encore remplit toutes mes attentes et demeure ma préférée !

• Le package WebPack Encore sur le dépôt npmjs
• La documentation de WebPack Encore sur le site de Symfony