Un boilerplate pour développer des thèmes WordPress

Qu’est-ce qu’un boilerplate ?

Il s’agit, vous l’aurez compris, d’un anglicisme. En français, il faudrait utiliser le mot standard… mais du « code standard » ce n’est pas forcément parlant. Il est également possible de parler de prototype non fonctionnel, c’est peut-être un peu plus parlant mais également un peu plus long et moins souvent utilisé. Je préfère donc utiliser l’anglicisme.

Un boilerplate, appliqué au code, est ainsi une maquette avancée ou un prototype. Il ne s’agit pas seulement de décrire une structure. Le boilerplate peut intégrer une configuration et des fonctionnalités qui restent quasiment les mêmes à chaque utilisation. Dans le cas d’un thème WordPress, il peut ainsi s’agir des différents fichiers à utiliser pour créer le thème (index.php, header.php, footer.php, single.php, etc.) mais également de la configuration d’outils qui seront utilisés pour chaque développement de thème.

Les fonctionnalités de mon WordPress boilerplate

Ce que j’utilise à chaque fois

Lorsque je développe un thème WordPress :

• je m’efforce de respecter les WordPress Coding Standards,
• j’utilise Gulp pour compiler Sass en CSS, pour transpiler les fichiers JS, pour minifier les fichiers ou encore pour optimiser les images,
• je génère un fichier pot pour gérer la traduction du thème,
• j’utilise un fichier CSS pour que le rendu dans les navigateurs soit plus uniformisé (j’utilisais normalize.css mais je suis passé à modern-normalize).

De manière générale, lorsque je crée un projet, j’essaie de :

• respecter la gestion des versions avec Semver,
• générer un changelog,
• utiliser les dotenv pour gérer la configuration.

Ce que le boilerplate contient

Pour faciliter le développement de thème, le boilerplate que je propose contient tout ça. Le fichier modern-normalize.css est importé dans Sass après installation avec npm. Il est déjà présent dans le fichier style.scss.

Un automatiseur de tâches

Le boilerplate utilise Gulp pour définir différentes tâches qui vont permettre de :

• générer les fichiers style.css, style-rtl.css, style-editor.css, style-editor-rtl.css, print.css ainsi que print-rtl.css et d’ajouter les préfixes nécessaires,
• transpiler les fichiers JS avec Babel,
• de générer un unique fichier JS par point d’entrée (suivant s’ils doivent être dans le footer ou dans l’éditeur par exemple) avec RollUp,
• optimiser les images,
• copier les polices,
• générer un fichier .pot pour traduire le thème,
• créer une archive du thème en excluant les fichiers dédiés au développement,
• surveiller les changements apportés aux fichiers pour exécuter de nouveau les tâches et pour recharger le navigateur avec Browsersync,
• générer les sourcemaps en mode développement,
• minifier les fichiers CSS et JS en mode production.

Le fichier Gulp contient également des tâches qui vont être utilisées pour la gestion des versions. Grâce à standard-version, il est possible de créer une nouvelle version et de générer un changelog. Cependant, il incrémente le numéro de version uniquement dans package.json. WordPress utilise le numéro de version déclaré dans le fichier style.css et, éventuellement, dans le fichier functions.php. Gulp va permettre de récupérer le nouveau numéro de version et de le copier dans ces fichiers.

Il contient également une tâche qui va permettre d’initialiser le thème avec la configuration définie dans un fichier dotenv. Il s’agit d’un basique « chercher/remplacer ». En exécutant la tâche, Gulp va, par exemple, remplacer le nom du package, son auteur, l’URL du dépôt ou encore le préfixe à utiliser.

Des scripts npm et Composer

Le boilerplate propose également :

• la gestion des versions avec standard-version,
• la génération d’un changelog basé sur Conventional Changelog,
• un linter et un hook git grâce à Husky pour vérifier que les commits respectent le standard Conventional Commits,
• des linters pour vérifier que le code respectent les WordPress Coding Standard et des scripts pour essayer de corriger ces erreurs automatiquement,
• des scripts pour exécuter les tâches Gulp,
• un script pour prendre une capture d’écran de la page d’accueil au format requis par WordPress.

Comment utiliser ce boilerplate ?

Vous pouvez récupérer les sources sur mon dépôt Github. Une fois téléchargées, il vous suffit de copier le dossier wordpress-theme dans votre installation WordPress et de le renommer.

Prérequis

Pour que le boilerplate fonctionne, il faut :

• installer Composer et npm,
• configurer un hôte virtuel,
• respecter le format de Conventional Commits pour vos commits.

Premières étapes

Pour commencer, il faut initialiser un nouveau dépôt Git sinon l’une des dépendances (Husky) ne voudra pas s’installer. Ensuite, vous pouvez exécuter npm install et composer update pour installer toutes les dépendances.

Pour initialiser votre thème, il vous faut un fichier dotenv. Votre répertoire contient un fichier .env.example, il vous suffit de créer une copie et de la nommer .env. Ensuite, il faut remplacer les valeurs dans le fichier.

Pour utiliser Browsersync et éviter les avertissements liés à l’usage de https en local, il vous faut un certificat valide et renseigner le chemin dans le fichier dotenv. Vous pouvez en générer un avec mkcert.

Une fois ces étapes réalisées, vous pouvez exécuter npm run init. Pour mettre à jour le fichier package-lock.json, vous devriez exécuter de nouveau npm install.

Pour installer les hooks Git, il vous faudra également exécuter npx husky install.

Développer votre thème WordPress

Le fichier Composer vous propose deux scripts faisant appel à PHPCode_Sniffer et aux WordPress Coding Standard. Ils vous permettent de détecter et de corriger les erreurs. Il vous suffit d’exécuter composer run lint <fichier(s)> ou composer run lint . (pour l’ensemble du dossier) afin d’afficher les problèmes. Il suffit de remplacer lint par fix pour les corriger.

Le fichier package.json vous propose également plusieurs scripts :

• npm run build supprime les précédents fichiers générés et en génère de nouveaux (images, polices, css, js et fichier de traduction),
• npm run watch exécute BrowserSync et surveille les changements apportés à vos fichiers pour exécuter automatiquement les bonnes tâches,
• npm run release crée une nouvelle version du thème ainsi qu’un commit et un tag pour cette version,
• npm run zip crée une archive de votre thème en excluant les fichiers uniquement nécessaires au développement,
• npm run lint / npm run fix permet de vérifier que vos fichiers respectent les WPCS et de les corriger si possible,
• npm run screenshot génère une capture d’écran de la page d’accueil,
• npm run translate crée ou actualise le fichier .pot individuellement de build.

Si vous avez besoin d’ajouter de faire des ajouts et des modifications dans Gulp, il faudra fouiller du côté du dossier tools. Dans tools/config, vous trouverez plusieurs fichiers pour gérer les chemins, les données importées de .env et les options utilisées par les plugins Gulp.

Si vous souhaitez ajouter des plugins, vous pouvez éditer le fichier tools/gulp/error-handler.js pour gérer les erreurs.

Ce que ce WordPress boilerplate ne fait pas

La création d’une nouvelle version n’est pas automatisée à 100 %. La plupart des thèmes sont traduits dans différentes langues. Pour cela, il est nécessaire de créer les traductions manuellement. Ainsi, il n’est pas possible de combiner les tâches build, release et zip. Toutefois, si vous n’avez pas besoin de traduction, vous pouvez toujours adapter le boilerplate pour automatiser ce processus.

Les fichiers PHP propres à WordPress (functions.php, header.php, etc.) et les fichiers SCSS ne contiennent que très peu de code. Le but n’est pas d’offrir un thème tout fait, mais de proposer une base pour que chacun puisse créer son propre thème avec sa propre structure plus rapidement.

Enfin, si vous estimez qu’il manque des fonctionnalités qui peuvent être utiles pour tout le monde et non pas uniquement pour vos projets, vous êtes libres de les proposer.