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 :

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 :

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) :

yarn add @symfony/webpack-encore
# OU
npm install @symfony/webpack-encore

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 :

const Encore = require('@symfony/webpack-encore')

const relativeThemePath = './wp-content/themes/mon-theme-wp'

Encore
	.setOutputPath('./dist')
	.setPublicPath('/dist')

    // Point d'entrée avec un fichier JS et un fichier SCSS
	.addEntry('app', [
		`${relativeThemePath}/assets/js/app.js`,
		`${relativeThemePath}/assets/scss/app.scss`
	])

    // Second point d'entrée pour une page spécifique 
	.addEntry('landing-page', `${relativeThemePath}/assets/js/landing.js`)

    // Ajout d'un fichier de style pour une page spécifique 
	.addStyleEntry('admin', `${relativeThemePath}/assets/scss/admin.scss`)

    // Pour activer la compilation de tes fichiers SCSS !
	.enableSassLoader()

    // Options supplémentaires...
	.enableSingleRuntimeChunk()
	.cleanupOutputBeforeBuild()
	.enableSourceMaps(!Encore.isProduction())
	.configureFilenames([])
	.enablePostCssLoader()

    // A décommenter si tu souhaites utiliser jQuery
	//.autoProvidejQuery()

    // A décommenter si tu souhaites utiliser TypeScript
	//.enableTypeScriptLoader()
	//.enableForkedTypeScriptTypesChecking()
;


const config = Encore.getWebpackConfig()

/*
Tu peux rajouter ici de la configuration custom
à WebPack avant de l'exporter !
*/

module.exports = config;

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

yarn run encore dev
# OU
npm run encore dev

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 :

yarn run encore build
# OU
npm run encore build

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

yarn run encore dev --watch
# OU
npm run encore dev --watch

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 :

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('app', '/build/app.js', '1.0.0', true);
});

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 :

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 :

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 :

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 :

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 !