Chapitre 8.2 — Scaffolding : @wordpress/scripts & block.json

⏱️ TL;DR — On ne configure pas webpack à la main. @wordpress/create-block génère un plugin de bloc complet en une commande, et @wordpress/scripts fournit les scripts de build (wp-scripts build/start) préconfigurés (JSX, SCSS, minification, hot rebuild). Au cœur : block.json, le manifeste du bloc (nom, titre, attributs, supports, fichiers editorScript/style/render). WordPress lit block.json et enqueue automatiquement les bons assets, avec les dépendances déclarées dans un .asset.php généré. C’est le pipeline moderne, proche d’un projet React classique.

🎯 Objectifs

• Générer un bloc avec create-block.
• Comprendre la structure produite et le rôle de block.json.
• Lancer le build (start/build) et le rechargement.
• Comprendre l’enqueue automatique via block.json.

1. Générer un bloc en une commande

# Dans wp-content/plugins/
npx @wordpress/create-block wpr-livre-une

Cela crée un plugin complet wpr-livre-une/ : en-tête de plugin, block.json, src/ (JS/SCSS), configuration de build via @wordpress/scripts. Le bloc est immédiatement fonctionnel (« Hello World »).

Pour l’ajouter à un plugin existant (comme wpr-books), on utilise --no-plugin ou on copie la structure src/ + block.json et on enregistre le bloc depuis le plugin (ch. 8.9).

npm install     # installe @wordpress/scripts et les deps
npm run start   # build en watch (dev) → rebuild à chaque sauvegarde
npm run build   # build de production (minifié) → dossier build/

💡 Pour un dev React — create-block est le create-next-app de Gutenberg : un starter opinionated avec build prêt. wp-scripts start = votre dev server / watch (rebuild auto), wp-scripts build = le build de prod. Vous retrouvez npm, un dossier src/, du JSX, du SCSS — un projet front familier, sans config webpack à écrire.

2. La structure générée

wpr-livre-une/
├── wpr-livre-une.php     ← plugin : enregistre le bloc via block.json
├── block.json            ← LE manifeste du bloc
├── package.json          ← scripts (start/build) + deps @wordpress/*
├── src/
│   ├── index.js          ← registerBlockType(metadata, { edit, save })
│   ├── edit.js           ← composant edit
│   ├── save.js           ← fonction save
│   ├── editor.scss       ← styles éditeur uniquement
│   ├── style.scss        ← styles front + éditeur
│   └── render.php        ← (si bloc dynamique)
└── build/                ← généré (ne pas versionner : bundles + .asset.php)

Le PHP du plugin se contente d’enregistrer le bloc à partir du dossier de build :

add_action( 'init', function () {
    register_block_type( __DIR__ . '/build' ); // lit build/block.json
} );

register_block_type() avec un chemin lit le block.json et branche tout (scripts, styles, attributs, render) automatiquement.

3. block.json : le manifeste

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "wpr/livre-une",
  "title": "Livre à la une",
  "category": "widgets",
  "icon": "book",
  "description": "Met en avant un livre du catalogue.",
  "textdomain": "wpr-books",
  "attributes": {
    "livreId": { "type": "number" },
    "afficherPrix": { "type": "boolean", "default": true }
  },
  "supports": {
    "html": false,
    "align": ["wide", "full"],
    "color": { "background": true, "text": true },
    "spacing": { "padding": true }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css",
  "render": "file:./render.php"
}

Champs clés :

• name : identifiant unique namespace/slug (wpr/livre-une).
• attributes : l’état du bloc (types, défauts) — l’équivalent de props typées (ch. 8.3).
• supports : fonctionnalités natives activées (couleurs, alignement, espacement…) — gratuites, gérées par le cœur.
• editorScript / editorStyle / style : les assets, chargés automatiquement par WordPress seulement quand le bloc est présent.
• render : un fichier PHP pour un bloc dynamique (ch. 8.5).

⚠️ Piège — enqueue manuel inutile. Avec block.json, vous n’enqueue rien à la main : WordPress charge editorScript/style/etc. quand c’est nécessaire (bloc présent sur la page). Tenter d’enqueue vous-même ces assets crée des doublons. Laissez block.json gérer.

4. Les dépendances et le .asset.php

wp-scripts build génère, à côté de chaque bundle, un fichier index.asset.php :

<?php return array('dependencies' => array('wp-blocks','wp-block-editor','wp-element','wp-i18n'), 'version' => 'a1b2c3');

WordPress lit ces dépendances pour charger @wordpress/blocks, @wordpress/element, etc. avant votre bloc, et la version (hash) pour le cache-busting. Vous n’avez rien à déclarer : le build détecte les imports @wordpress/* et les traduit en handles (wp-blocks…). C’est l’enqueue moderne (ch. 6.4) automatisé.

5. Workflow de dev

1. npm run start (watch) pendant que vous codez.
2. Dans l’éditeur WordPress, insérez votre bloc, rechargez après un rebuild.
3. npm run build avant de livrer (bundle minifié).
4. Ne versionnez pas build/ ni node_modules/ ; versionnez src/, block.json, package.json. (Un pipeline CI reconstruit build/.)

📚 Aller plus loin — @wordpress/scripts fournit aussi lint-js, lint-css, format, et test-unit-js (Jest) : un outillage complet (Partie 11). Vous pouvez ajouter TypeScript, du SCSS, des imports d’images — comme un projet front moderne. wp-scripts masque webpack, mais reste extensible si besoin.

✏️ Exercices

1. Quelle commande génère un plugin de bloc prêt à l’emploi ?
2. Que déclare block.json et qu’est-ce que WordPress en fait automatiquement ?
3. Pourquoi ne versionne-t-on pas le dossier build/ ?

🧠 Quiz de révision

Chapitre suivant : edit, save & attributs.