Écrire un bloc Gutenberg suppose d’utiliser JSX, des modules ES et souvent Sass. Sans outillage, il faut donc configurer soi-même Babel, webpack, ESLint et Stylelint, puis maintenir ces configurations au fil des montées de version de WordPress. C’est un travail fastidieux, répétitif, et source d’incohérences d’un projet à l’autre.
Le paquet @wordpress/scripts, que l’équipe Gutenberg maintient et fait évoluer en parallèle du cœur de WordPress, règle ce problème une fois pour toutes. Il embarque une configuration webpack et Babel prête à l’emploi, alignée sur les versions de dépendances utilisées par WordPress lui-même, et l’expose via une série de commandes simples à lancer depuis package.json. Voyons comment l’installer et tirer parti de chacune de ses commandes.
Installer et configurer le projet
L’installation se fait comme n’importe quel paquet npm de développement :
npm install @wordpress/scripts --save-devIl suffit ensuite de déclarer les scripts npm correspondants dans votre package.json :
{
"scripts": {
"start": "wp-scripts start",
"build": "wp-scripts build",
"lint:js": "wp-scripts lint-js",
"lint:css": "wp-scripts lint-style",
"test-unit": "wp-scripts test-unit-js",
"format": "wp-scripts format"
}
}Aucun fichier webpack.config.js n’est nécessaire pour commencer : wp-scripts détecte automatiquement votre point d’entrée par défaut, généralement src/index.js, et si votre projet contient plusieurs fichiers block.json sous src, il construit automatiquement un point d’entrée pour chacun d’eux, en s’appuyant sur les propriétés editorScript, script, viewScript et style déclarées dans ces fichiers.
Les commandes du quotidien
Chaque commande correspond à une tâche précise du cycle de développement.
wp-scripts start: lance webpack en mode développement avec surveillance des fichiers (watch), sourcemaps activées et rechargement automatique de la compilation à chaque sauvegarde.wp-scripts build: produit une version de production optimisée, minifiée, dans le dossierbuild, avec génération automatique d’un fichier.asset.phppar point d’entrée contenant la liste des dépendances et un numéro de version basé sur le hash du contenu.wp-scripts lint-js: analyse votre JavaScript avec ESLint, en s’appuyant sur la configuration@wordpress/eslint-plugin, qui reprend les conventions de codage JavaScript de WordPress.wp-scripts lint-style: fait de même pour votre CSS ou Sass via Stylelint, avec la configuration@wordpress/stylelint-config.wp-scripts test-unit-js: exécute vos tests unitaires JavaScript avec Jest, préconfiguré pour comprendre JSX et les modules@wordpress/*.wp-scripts format: reformate automatiquement votre code avec Prettier, selon les règles de style de WordPress.
Le fichier .asset.php généré par build mérite qu’on s’y attarde, car il change directement la façon d’enregistrer vos scripts côté PHP :
<?php
$asset = include __DIR__ . '/build/index.asset.php';
wp_register_script(
'wpmoderne-encadre-editor',
plugins_url( 'build/index.js', __FILE__ ),
$asset['dependencies'],
$asset['version']
);Grâce à ce fichier, plus besoin de lister à la main les dépendances (wp-blocks, wp-element, wp-i18n…) ni de gérer manuellement un numéro de version pour le cache-busting : tout est calculé automatiquement à chaque build.
Ce que webpack fait sous le capot
La configuration fournie par @wordpress/scripts repose sur webpack et @babel/preset-react pour transformer JSX en appels à wp.element.createElement, sur sass-loader pour compiler automatiquement les fichiers .scss, et sur une liste d’externals qui indique à webpack de ne pas embarquer dans le bundle les paquets déjà fournis par WordPress, comme @wordpress/blocks ou @wordpress/element. C’est justement cette liste d’externals qui alimente le fichier .asset.php : chaque import d’un module WordPress connu devient une dépendance de script déclarée, plutôt qu’un code dupliqué dans votre bundle.
Cette approche garantit aussi la cohérence des versions : votre bloc utilise la version de wp.element réellement chargée par le WordPress sur lequel il tourne, sans risque de conflit entre deux versions de React embarquées côté client.
Personnaliser la configuration sans tout réécrire
Il arrive qu’un projet ait des besoins spécifiques : ajouter une variable Sass globale, changer le dossier de sortie, ou ajouter un point d’entrée qui ne correspond à aucun block.json. Dans ce cas, il n’est pas nécessaire d’abandonner la configuration fournie : il suffit de créer un fichier webpack.config.js à la racine du projet qui étend la configuration par défaut plutôt que de la remplacer.
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
module.exports = {
...defaultConfig,
entry: {
...defaultConfig.entry(),
'mon-script-supplementaire': './src/extra/index.js',
},
};De la même façon, ESLint et Stylelint peuvent être ajustés via un fichier .eslintrc.js ou .stylelintrc.json qui étend les préréglages fournis par les paquets @wordpress/eslint-plugin et @wordpress/stylelint-config, plutôt que de repartir de zéro.
Un mot sur les tests unitaires
La commande test-unit-js installe une configuration Jest capable de simuler l’environnement de l’éditeur, ce qui permet de tester des composants React qui utilisent les hooks de @wordpress/data sans avoir à démarrer un WordPress complet. Pour un bloc qui manipule des attributs complexes ou des transformations, écrire quelques tests unitaires sur les fonctions pures de transformation évite bien des régressions silencieuses lors des mises à jour.
En résumé
Avec @wordpress/scripts, la configuration d’un environnement de développement de blocs passe de plusieurs centaines de lignes de configuration webpack et Babel à quelques lignes de package.json. Les commandes couvrent l’essentiel du cycle de vie : développement, production, qualité du code et tests. Et lorsque les besoins du projet dépassent ce que propose la configuration par défaut, rien n’empêche de l’étendre sans repartir de zéro. C’est aujourd’hui la façon la plus sûre de démarrer un nouveau bloc, et celle que nous recommandons systématiquement sur nos projets clients.
