Depuis les débuts de Gutenberg, déclarer un bloc personnalisé obligeait à répéter la même information à deux endroits : une fois dans le PHP, via register_block_type() avec un tableau d’arguments, et une fois dans le JavaScript, via registerBlockType() avec son propre objet de configuration. Les deux déclarations devaient rester synchronisées à la main, ce qui provoquait régulièrement des oublis : un attribut ajouté côté JS mais jamais reporté côté PHP, une icône modifiée dans un seul des deux fichiers.
WordPress 5.8, sorti le 20 juillet 2021, change la donne en généralisant le fichier block.json. Ce format existait déjà de façon expérimentale, mais il devient désormais la méthode recommandée par l’équipe Gutenberg pour tout nouveau bloc. Voyons comment il fonctionne, ce qu’il contient, et pourquoi il vaut la peine de migrer vos blocs existants.
La structure de base d’un fichier block.json
Le fichier block.json se place à la racine du dossier de votre bloc, aux côtés de vos fichiers PHP et JS. Il s’agit d’un objet JSON classique, sans logique conditionnelle, ce qui le rend lisible aussi bien par PHP que par JavaScript, et même par des outils tiers qui voudraient inspecter vos blocs sans exécuter de code.
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 2,
"name": "wpmoderne/encadre-conseil",
"title": "Encadré conseil",
"category": "text",
"icon": "lightbulb",
"description": "Un encadré mis en valeur pour un conseil ou une astuce.",
"keywords": [ "astuce", "conseil", "encadré" ],
"textdomain": "wpmoderne",
"attributes": {
"contenu": {
"type": "string",
"source": "html",
"selector": "p"
}
},
"supports": {
"html": false
},
"editorScript": "file:./index.js",
"editorStyle": "file:./editor.css",
"style": "file:./style.css"
}
Les propriétés essentielles à connaître
Certaines propriétés reviennent systématiquement et méritent d’être bien comprises avant d’écrire votre premier bloc via ce format.
name: l’identifiant unique du bloc, toujours sous la formeespace-de-nom/nom-du-bloc.title: le nom affiché dans l’inserteur de blocs.category: la catégorie dans laquelle le bloc apparaît (text,media,design,widgets,embed, ou une catégorie personnalisée).icon: soit le nom d’une icône Dashicons, soit un SVG personnalisé défini côté JS.attributes: la définition des données que le bloc stocke, avec leur type et leur source d’extraction dans le balisage.supports: les fonctionnalités natives activées ou désactivées pour ce bloc (alignement, couleurs, anchor, etc.).textdomain: le domaine de traduction, indispensable pour l’internationalisation.
Viennent ensuite les propriétés qui pointent vers vos fichiers : editorScript pour le JavaScript chargé uniquement dans l’éditeur, script pour un script chargé à la fois dans l’éditeur et sur le site public, editorStyle pour le CSS de l’éditeur, et style pour le CSS commun à l’éditeur et au site. La notation file:./index.js indique un chemin relatif au fichier block.json lui-même, ce que WordPress résout automatiquement.
Comment WordPress lit ce fichier
Côté PHP, l’enregistrement du bloc tient désormais en une seule ligne :
function wpmoderne_enregistrer_bloc_encadre() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'wpmoderne_enregistrer_bloc_encadre' );En passant un chemin de dossier à register_block_type() plutôt qu’un nom de bloc et un tableau d’arguments, WordPress cherche automatiquement le fichier block.json dans ce dossier, lit ses propriétés, enregistre les scripts et styles associés avec wp_register_script() et wp_register_style(), puis enregistre le bloc lui-même. Toute la mécanique de chargement des assets, autrefois écrite à la main, disparaît.
Côté JavaScript, l’appel à registerBlockType() peut lui aussi s’appuyer sur ce même fichier grâce à un import direct :
import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';
registerBlockType( metadata.name, {
edit: Edit,
save: () => null,
} );Le nom du bloc, ses attributs, son icône et sa catégorie sont ainsi lus depuis le même fichier des deux côtés. Il n’existe plus qu’une seule source de vérité.
Les avantages concrets par rapport à l’ancienne méthode
Au-delà du confort d’écriture, ce changement apporte des bénéfices tangibles sur un projet réel.
- Fin de la duplication : plus besoin de maintenir deux déclarations en parallèle, donc moins de bugs liés à un désynchronisme entre PHP et JS.
- Meilleures performances : WordPress peut lire les métadonnées du bloc côté serveur sans avoir à exécuter le JavaScript, ce qui accélère certains traitements internes, notamment le rendu côté serveur des blocs dynamiques.
- Compatibilité avec les outils de build :
@wordpress/scriptssait désormais repérer automatiquement les fichiersblock.jsonprésents dans votre dossiersrcpour construire les points d’entrée correspondants, sans configuration webpack manuelle. - Meilleure découvrabilité : des outils comme l’annuaire des blocks du répertoire WordPress.org peuvent lire ce fichier statiquement pour indexer vos blocs, sans avoir besoin d’exécuter PHP.
Conseil maison : même sur un bloc très simple, prenez l’habitude d’écrire le
block.jsondès le départ. Le réflexe se prend vite, et il évite de tout réécrire le jour où vous voudrez publier le bloc sous forme de plugin autonome.
Migrer un bloc existant
Si vous avez des blocs enregistrés à l’ancienne méthode, la migration reste simple dans la majorité des cas. Il suffit de reporter les arguments passés à register_block_type() côté PHP et l’objet passé à registerBlockType() côté JS dans un fichier block.json commun, puis de simplifier les deux appels pour qu’ils pointent vers ce fichier. Les blocs qui utilisent un rendu dynamique via une fonction render_callback continuent de fonctionner normalement : cette propriété se déclare toujours côté PHP, via l’argument render_callback passé en second paramètre de register_block_type(), en complément du chemin vers le dossier.
Pensez également à vérifier la propriété apiVersion. Un bloc déclaré avec "apiVersion": 2 bénéficie du rendu du wrapper via useBlockProps() côté éditeur, une amélioration qui simplifie l’écriture des composants d’édition et de sauvegarde.
En résumé
Le fichier block.json n’est pas un simple gadget de confort : il s’agit désormais du socle recommandé pour tout développement de bloc sous WordPress 5.8 et au-delà. Il centralise la déclaration, réduit les risques d’erreur, accélère le chargement et prépare naturellement le terrain pour les outils de build officiels que nous verrons dans un prochain article. Si vous démarrez un nouveau bloc aujourd’hui, il n’y a tout simplement plus de raison de s’en passer.
