# @wordpress/scripts : la boîte à outils officielle pour développer vos blocs

> Fini les configurations webpack maison. Découvrez wp-scripts, ses commandes start, build, lint-js et test-unit-js, et comment les adapter à votre projet.

- Auteur : Clément Hadrot
- Publié le : 2021-10-19
- Mis à jour le : 2021-10-19
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/wordpress-scripts-build-lint-dev/

## L’essentiel

- Zéro configuration nécessaire pour démarrer un bloc
- Une commande par tâche : build, lint, test
- Personnalisable sans réécrire tout webpack.config.js

Écrire un bloc Gutenberg suppose d'utiliser JSX, des modules ES et souvent Sass. Sans outillage, il faut donc configurer soi-même Babel, webpack, ESLint et Stylelint, puis maintenir ces configurations au fil des montées de version de WordPress. C'est un travail fastidieux, répétitif, et source d'incohérences d'un projet à l'autre.

Le paquet `@wordpress/scripts`, que l'équipe Gutenberg maintient et fait évoluer en parallèle du cœur de WordPress, règle ce problème une fois pour toutes. Il embarque une configuration webpack et Babel prête à l'emploi, alignée sur les versions de dépendances utilisées par WordPress lui-même, et l'expose via une série de commandes simples à lancer depuis `package.json`. Voyons comment l'installer et tirer parti de chacune de ses commandes.

## Installer et configurer le projet

L'installation se fait comme n'importe quel paquet npm de développement :

```
npm install @wordpress/scripts --save-dev
```

Il suffit ensuite de déclarer les scripts npm correspondants dans votre `package.json` :

```
{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-style",
    "test-unit": "wp-scripts test-unit-js",
    "format": "wp-scripts format"
  }
}
```

Aucun fichier `webpack.config.js` n'est nécessaire pour commencer : `wp-scripts` détecte automatiquement votre point d'entrée par défaut, généralement `src/index.js`, et si votre projet contient plusieurs fichiers `block.json` sous `src`, il construit automatiquement un point d'entrée pour chacun d'eux, en s'appuyant sur les propriétés `editorScript`, `script`, `viewScript` et `style` déclarées dans ces fichiers.

> L'essentiel à retenir : Zéro configuration nécessaire pour démarrer un bloc ; Une commande par tâche : build, lint, test ; Personnalisable sans réécrire tout webpack.config.js

## Les commandes du quotidien

Chaque commande correspond à une tâche précise du cycle de développement.

- `wp-scripts start` : lance webpack en mode développement avec surveillance des fichiers (watch), sourcemaps activées et rechargement automatique de la compilation à chaque sauvegarde.
- `wp-scripts build` : produit une version de production optimisée, minifiée, dans le dossier `build`, avec génération automatique d'un fichier `.asset.php` par point d'entrée contenant la liste des dépendances et un numéro de version basé sur le hash du contenu.
- `wp-scripts lint-js` : analyse votre JavaScript avec ESLint, en s'appuyant sur la configuration `@wordpress/eslint-plugin`, qui reprend les conventions de codage JavaScript de WordPress.
- `wp-scripts lint-style` : fait de même pour votre CSS ou Sass via Stylelint, avec la configuration `@wordpress/stylelint-config`.
- `wp-scripts test-unit-js` : exécute vos tests unitaires JavaScript avec Jest, préconfiguré pour comprendre JSX et les modules `@wordpress/*`.
- `wp-scripts format` : reformate automatiquement votre code avec Prettier, selon les règles de style de WordPress.

Le fichier `.asset.php` généré par `build` mérite qu'on s'y attarde, car il change directement la façon d'enregistrer vos scripts côté PHP :

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

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

Grâce à ce fichier, plus besoin de lister à la main les dépendances (`wp-blocks`, `wp-element`, `wp-i18n`...) ni de gérer manuellement un numéro de version pour le cache-busting : tout est calculé automatiquement à chaque build.

## Ce que webpack fait sous le capot

La configuration fournie par `@wordpress/scripts` repose sur `webpack` et `@babel/preset-react` pour transformer JSX en appels à `wp.element.createElement`, sur `sass-loader` pour compiler automatiquement les fichiers `.scss`, et sur une liste d'*externals* qui indique à webpack de ne pas embarquer dans le bundle les paquets déjà fournis par WordPress, comme `@wordpress/blocks` ou `@wordpress/element`. C'est justement cette liste d'externals qui alimente le fichier `.asset.php` : chaque import d'un module WordPress connu devient une dépendance de script déclarée, plutôt qu'un code dupliqué dans votre bundle.

Cette approche garantit aussi la cohérence des versions : votre bloc utilise la version de `wp.element` réellement chargée par le WordPress sur lequel il tourne, sans risque de conflit entre deux versions de React embarquées côté client.

## Personnaliser la configuration sans tout réécrire

Il arrive qu'un projet ait des besoins spécifiques : ajouter une variable Sass globale, changer le dossier de sortie, ou ajouter un point d'entrée qui ne correspond à aucun `block.json`. Dans ce cas, il n'est pas nécessaire d'abandonner la configuration fournie : il suffit de créer un fichier `webpack.config.js` à la racine du projet qui étend la configuration par défaut plutôt que de la remplacer.

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

module.exports = {
    ...defaultConfig,
    entry: {
        ...defaultConfig.entry(),
        'mon-script-supplementaire': './src/extra/index.js',
    },
};
```

De la même façon, ESLint et Stylelint peuvent être ajustés via un fichier `.eslintrc.js` ou `.stylelintrc.json` qui étend les préréglages fournis par les paquets `@wordpress/eslint-plugin` et `@wordpress/stylelint-config`, plutôt que de repartir de zéro.

### Un mot sur les tests unitaires

La commande `test-unit-js` installe une configuration Jest capable de simuler l'environnement de l'éditeur, ce qui permet de tester des composants React qui utilisent les hooks de `@wordpress/data` sans avoir à démarrer un WordPress complet. Pour un bloc qui manipule des attributs complexes ou des transformations, écrire quelques tests unitaires sur les fonctions pures de transformation évite bien des régressions silencieuses lors des mises à jour.

## En résumé

Avec `@wordpress/scripts`, la configuration d'un environnement de développement de blocs passe de plusieurs centaines de lignes de configuration webpack et Babel à quelques lignes de `package.json`. Les commandes couvrent l'essentiel du cycle de vie : développement, production, qualité du code et tests. Et lorsque les besoins du projet dépassent ce que propose la configuration par défaut, rien n'empêche de l'étendre sans repartir de zéro. C'est aujourd'hui la façon la plus sûre de démarrer un nouveau bloc, et celle que nous recommandons systématiquement sur nos projets clients.