# block.json

> Le fichier block.json centralise, au format JSON, toutes les métadonnées d'un bloc : son nom, ses attributs, sa catégorie, ses styles et ses scripts, lus à la fois par PHP et par JavaScript.

- Auteur : Clément Hadrot
- Publié le : 2026-09-25
- Mis à jour le : 2026-09-25
- URL : https://wpmoderne.dev.wordpress-developpement.fr/lexique/block-json/

Avant l'introduction de ce fichier, déclarer un bloc demandait de dupliquer les mêmes informations à deux endroits : une fois côté PHP pour l'enregistrement serveur, une fois côté JavaScript pour l'éditeur, avec le risque que les deux versions divergent. `block.json` règle ce problème en devenant la source unique de vérité : un seul fichier, lu aussi bien par `register_block_type()` en PHP que par les outils de compilation JavaScript, décrit tout ce qui définit le bloc.

## Fonctionnement dans WordPress

Ce fichier déclare notamment `name` (au format `espace-de-nom/nom-du-bloc`), `attributes`, `supports` (les fonctionnalités activées comme les couleurs ou l'alignement), `category`, ainsi que les points d'entrée de scripts et styles (`editorScript`, `style`, `viewScript`, ou leur équivalent moderne en modules). Depuis WordPress 5.8, l'appel `register_block_type( __DIR__ )` côté PHP suffit à lire automatiquement ce fichier, sans avoir à recopier ses informations dans un tableau PHP séparé.

## Exemple

```
{
  "apiVersion": 3,
  "name": "mon-plugin/encart",
  "title": "Encart",
  "category": "widgets",
  "attributes": { "texte": { "type": "string" } },
  "editorScript": "file:./index.js"
}
```

## Bon à savoir

- La propriété `apiVersion` détermine certains comportements du bloc dans l'éditeur (comme la gestion des styles imbriqués) ; la valeur 3 est la référence actuelle pour les nouveaux blocs.
- Un outil comme `@wordpress/scripts` peut générer et compléter ce fichier automatiquement à partir d'un modèle de départ créé avec `@wordpress/create-block`.
- Un bloc du répertoire officiel des extensions doit obligatoirement fournir un `block.json` valide pour être correctement indexé et affiché dans la bibliothèque de blocs.