npm et @wordpress/scripts : outiller la création de blocs Gutenberg

Développer un bloc Gutenberg en JavaScript moderne implique une chaîne de compilation : JSX à transformer, imports ES modules à empaqueter, CSS à extraire. Configurer ça à la main avec Webpack et Babel prend facilement une demi-journée, et il faut la maintenir sur chaque projet. Depuis WordPress 5.8 et la stabilisation de theme.json, on utilise systématiquement @wordpress/scripts pour éviter ce travail répétitif.

@wordpress/scripts est le paquet npm officiel de l’équipe WordPress : il embarque une configuration Webpack et Babel déjà alignée sur ce qu’utilise le cœur de WordPress pour compiler Gutenberg lui-même. Le résultat : des blocs compilés de façon cohérente avec l’éditeur, sans configuration à écrire.

Démarrer un plugin de bloc avec create-block

L’outil @wordpress/create-block génère un plugin de bloc complet, avec @wordpress/scripts déjà configuré :

npx @wordpress/create-block mon-bloc
cd mon-bloc
npm start

La commande npm start exécute en réalité wp-scripts start, qui surveille les fichiers sources et recompile automatiquement à chaque modification, avec le rechargement à chaud côté éditeur. Le fichier package.json généré illustre bien la simplicité de la configuration :

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-style",
    "format": "wp-scripts format"
  },
  "devDependencies": {
    "@wordpress/scripts": "^19.2.4"
  }
}

Ce que wp-scripts build produit

La commande de build compile le JavaScript source (généralement dans src/index.js) vers un dossier build/, en générant au passage un fichier de dépendances PHP indispensable pour l’enregistrement correct du script :

build/
├── index.js
├── index.js.map
├── index.asset.php
├── style-index.css
└── index.css

<?php
// build/index.asset.php généré automatiquement
return array(
    'dependencies' => array( 'react-jsx-runtime', 'wp-block-editor', 'wp-blocks', 'wp-i18n' ),
    'version'      => 'a3f8e21b4c9d0125',
);

Ce fichier index.asset.php évite d’avoir à lister manuellement les dépendances du script dans wp_register_script() : on le charge directement avec require pour récupérer la liste des handles WordPress dont le bloc dépend, et un numéro de version qui change à chaque build pour invalider le cache navigateur.

<?php
$asset = require __DIR__ . '/build/index.asset.php';

wp_register_script(
    'mon-bloc-editor',
    plugins_url( 'build/index.js', __FILE__ ),
    $asset['dependencies'],
    $asset['version']
);

Lint et formatage inclus

Au-delà de la compilation, @wordpress/scripts embarque des configurations ESLint et Stylelint alignées sur les standards de codage JavaScript de WordPress, ainsi qu’un formateur basé sur Prettier :

• wp-scripts lint-js vérifie le JavaScript selon les règles officielles WordPress
• wp-scripts lint-style fait de même pour le CSS et le SCSS
• wp-scripts format reformate automatiquement le code selon ces mêmes standards
• wp-scripts test-unit-js lance les tests unitaires JavaScript via Jest, déjà configuré

On intègre systématiquement lint-js et lint-style dans notre pipeline d’intégration continue, pour bloquer une fusion de branche si le code JavaScript ne respecte pas les standards — un sujet qu’on détaille par ailleurs dans notre article sur les pipelines GitHub Actions pour WordPress.

Personnaliser sans tout réécrire

Quand la configuration par défaut ne suffit pas — ajouter un point d’entrée supplémentaire, par exemple pour un script de partie publique séparé de l’éditeur — on étend la configuration Webpack plutôt que de l’écraser :

// webpack.config.js
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );

module.exports = {
    ...defaultConfig,
    entry: {
        ...defaultConfig.entry(),
        frontend: './src/frontend.js',
    },
};

Cette approche garde le bénéfice de toutes les optimisations et compatibilités déjà réglées par l’équipe WordPress, tout en ajoutant précisément ce dont le projet a besoin.

Sur tous nos projets de blocs custom depuis un an, on n’a plus jamais écrit de configuration Webpack complète à la main. Le temps gagné se voit surtout à la maintenance : une mise à jour de @wordpress/scripts suffit à rester aligné avec les évolutions de l’éditeur.

En résumé

@wordpress/scripts a considérablement simplifié le développement de blocs Gutenberg en supprimant le besoin de configurer soi-même Webpack et Babel. Pour un développeur qui découvre le développement de blocs, c’est un gain de temps immédiat ; pour une équipe qui maintient plusieurs plugins de blocs, c’est surtout une garantie de cohérence et une charge de maintenance considérablement réduite.