@wordpress/create-block : générer la structure d’un bloc en quelques minutes

Depuis la sortie de WordPress 5.7 le mois dernier, avec ses patterns de blocs désormais directement accessibles dans l’inserteur, l’écosystème Gutenberg continue de s’outiller. Pour les développeurs, la nouveauté la plus appréciable de ces derniers mois reste sans doute @wordpress/create-block, le générateur officiel maintenu par l’équipe Core, qui automatise toute la tuyauterie qu’on écrivait encore à la main il y a un an : configuration webpack, structure de dossiers, enregistrement PHP de base.

Dans cet article, on installe et on utilise create-block pour générer un plugin de bloc complet, on décortique chaque fichier produit, et on passe en revue les commandes npm start et npm run build qui rythment désormais le quotidien de développement d’un bloc.

Pourquoi ce générateur change la donne

Jusqu’ici, démarrer un nouveau bloc impliquait de recopier une configuration webpack, d’installer soi-même Babel et ses presets, de définir les externals pour éviter de dupliquer React, puis d’écrire à la main l’enregistrement PHP avec register_block_type(). C’est un travail répétitif, source d’erreurs de copier-coller, et qui décourage un peu les développeurs venant du thème classique.

@wordpress/create-block supprime cette friction : une seule commande scaffold un plugin autonome, avec son build déjà fonctionnel, en s’appuyant en coulisses sur @wordpress/scripts, le paquet qui encapsule la configuration webpack et Babel recommandée par l’équipe Core elle-même. Vous n’avez plus à maintenir votre propre webpack.config.js : c’est @wordpress/scripts qui s’en charge, avec les mises à jour de l’équipe Gutenberg suivies automatiquement à chaque montée de version du paquet.

Générer un premier bloc

Aucune installation globale n’est nécessaire : on utilise directement npx, qui télécharge et exécute le paquet à la volée.

npx @wordpress/create-block wpmoderne-encadre-alerte

Le script pose quelques questions si l’on omet les options (titre du bloc, description, catégorie, icône Dashicons), puis installe les dépendances npm et lance un premier build. On peut aussi tout préciser en ligne de commande pour un usage scriptable :

npx @wordpress/create-block wpmoderne-encadre-alerte \
  --title "Encadré d'alerte" \
  --short-description "Un encadré coloré pour mettre en avant un message." \
  --category common

Au bout de quelques dizaines de secondes, un dossier wpmoderne-encadre-alerte apparaît, prêt à être copié dans wp-content/plugins puis activé depuis l’administration WordPress comme n’importe quel plugin.

La structure de fichiers générée

Voici, dans les grandes lignes, ce que produit le générateur :

wpmoderne-encadre-alerte/
├── build/
├── src/
│   ├── block.json
│   ├── index.js
│   ├── edit.js
│   ├── save.js
│   ├── editor.scss
│   └── style.scss
├── wpmoderne-encadre-alerte.php
├── readme.txt
└── package.json

Deux différences sautent aux yeux par rapport à ce qu’on écrivait à la main il y a un an. D’abord, edit() et save() sont désormais séparés dans deux fichiers distincts plutôt qu’imbriqués dans un unique index.js, ce qui aère la lecture à mesure que le bloc grandit. Ensuite, et c’est la vraie nouveauté, le scaffolding introduit un fichier block.json : un format de métadonnées qui commence tout juste à être adopté par l’équipe Core pour centraliser le nom du bloc, son titre, sa catégorie et ses attributs dans un seul fichier JSON, lu à la fois par le PHP et le JavaScript. Ce mécanisme est encore récent et mérite un article dédié pour être exploré en détail ; retenez pour l’instant simplement qu’il existe et qu’il remplace peu à peu l’appel manuel à register_block_type() avec un tableau d’arguments.

Le fichier PHP principal

Le fichier wpmoderne-encadre-alerte.php généré reste très court, puisque l’essentiel des métadonnées a été déplacé vers block.json :

<?php
/**
 * Plugin Name:       Wpmoderne Encadre Alerte
 * Description:       Un encadré coloré pour mettre en avant un message.
 * Version:           0.1.0
 * Requires at least: 5.7
 * Requires PHP:      7.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * Text Domain:       wpmoderne-encadre-alerte
 */

function wpmoderne_encadre_alerte_block_init() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'wpmoderne_encadre_alerte_block_init' );

On retrouve un appel à register_block_type(), mais avec un chemin de dossier en argument plutôt qu’un nom de bloc suivi d’un tableau : WordPress va chercher automatiquement le fichier block.json à cet emplacement pour en déduire toutes les métadonnées, y compris les scripts et styles à enregistrer. C’est une évolution notable par rapport à la syntaxe qu’on utilisait jusqu’ici, où chaque script et chaque style devait être enregistré manuellement avec wp_register_script() avant d’être référencé dans le tableau d’arguments.

Le quotidien du développement : npm start et npm run build

Le package.json généré expose deux scripts qui couvrent l’essentiel du cycle de développement :

Commande	Effet
npm start	Build en mode développement avec rechargement automatique à chaque modification d’un fichier source
npm run build	Build de production, code minifié, prêt à livrer

Au quotidien, on laisse simplement npm start tourner dans un terminal pendant qu’on édite les fichiers du dossier src : chaque sauvegarde régénère automatiquement le contenu de build, qu’il ne reste plus qu’à recharger dans le navigateur. Avant de livrer le plugin sur un site de production, on lance npm run build pour obtenir une version optimisée, sans les cartes source volumineuses ni le code de développement.

Ce que le générateur ne fait pas à votre place

• Il ne devine pas votre logique métier : edit.js et save.js restent à écrire entièrement, le générateur ne fournit qu’un exemple minimal affichant un simple paragraphe.
• Il ne gère pas le versionnement du dossier build : à vous de décider si vous le committez dans votre dépôt Git ou si vous le régénérez en intégration continue avant chaque déploiement.
• Il ne configure aucun outil de linting avancé au-delà de ce que fournit @wordpress/scripts par défaut : pas de règles ESLint personnalisées, pas de Prettier préconfiguré selon vos préférences.

Même avec le générateur, prenez le temps de relire le readme.txt produit et d’y consigner un vrai changelog dès la première version : c’est un réflexe qui coûte deux minutes et qui évite bien des questions en support un an plus tard.

En résumé

@wordpress/create-block ne remplace pas la compréhension de l’API des blocs qu’on a détaillée dans les précédents articles de cette série : il en automatise simplement l’échafaudage répétitif, pour que vous passiez directement au code qui a de la valeur, l’edit() et le save() de votre bloc. Le fichier block.json qu’il introduit mérite qu’on s’y attarde de plus près dans un prochain article, tant il est appelé à devenir le point d’entrée standard de tout nouveau bloc. En attendant, pour tout nouveau projet, il n’y a plus vraiment de raison de repartir d’une configuration webpack manuelle : gardez cette dernière pour les cas où vous avez besoin d’un contrôle très fin sur le build, et laissez le générateur officiel s’occuper du reste.