Utiliser wp-scripts pour traiter votre JavaScript dans WordPress

Vous avez surement déjà utilisé du JavaScript dans WordPress. Il suffit de placer son script dans un dossier de son extension ou thème enfant et de le charger correctement.

Mais l’éditeur de blocs et l’éditeur de site sont des applications JavaScript modernes qui utilisent un outillage plus sophistiqué et utiliser cet outillage plus complexe est maintenant la norme.

Dans cet article, on va voir comment utiliser le package wp-scripts pour traiter votre JavaScript dans vos développements WordPress, que vous développiez un bloc, un thème ou une extension.

Qu’est-ce que wp-scripts ?

Les wp-scripts (@wordpress/scripts de leur nom complet) sont un ensemble de scripts utiles dédiés à simplifier vos développements et vous aider à gérer votre JavaScript.

Comme vous le savez surement, le nouvel éditeur de WordPress est une grosse application React. Initialement, les wp-scripts sont destinés au développement de blocs car les blocs sont des composants React écrits à l’aide de JSX et qui nécessitent d’être transpilés pour que le navigateur puisse comprendre votre code.

Mais comme on va le voir, on peut utiliser ce même outillage pour les scripts des thèmes et extensions plus classiques, ce qui va nous permettre d’utiliser un même outil pour tous vos besoins dans le même thème ou extension.

Installation

Imaginons que nous développions une extension WordPress classique. Dans le dossier de notre extension, nous allons utiliser une commande npm pour installer les wp-scripts :

npm install --save-dev @wordpress/scripts

Cette commande va créer un dossier node_modules/ dans votre projet et y installer toutes les dépendances nécessaires. Aussi, elle va créer un fichier package.json s’il n’existe pas déjà. Ce fichier contient des métadonnées sur votre projet et liste vos dépendances JavaScript. C’est l’équivalent du fichier composer.json pour les dépendances PHP.

Une nouvelle commande CLI wp-scripts est maintenant disponible dans votre projet, mais le plus simple pour travailler est de créer des raccourcis dans votre fichier package.json.

Si vous n’avez jamais utilisé l’entrée scripts de votre fichier package.json pour créer des raccourcis, je vous invite fortement à lire l’article que j’ai écrit à ce sujet : Automatiser ses tâches de développement avec des scripts npm. Cet article vous aidera à comprendre le fichier package.json et à mettre en place vos premiers raccourcis.

Pour le moment, le fichier package.json de notre extension fictive ressemble à ceci :

{
  "name": "example-plugin",
  "version": "0.1.0",
  "main": "index.js",
  "author": "Vincent Dubroeucq",
  "devDependencies": {
    "@wordpress/scripts": "^30.15.0"
  }
}

Comprendre le fonctionnement de wp-scripts

Lancer les développements avec wp-scripts start

Comme expliqué précédemment, les wp-scripts servent à transpiler votre JavaScript quand vous développez des blocs. Pour lancer vos développements et surveiller vos fichiers, on utilise wp-scripts start.

Note : Dans cet article, j’utilise le terme “compiler” et “transpiler” de façon interchangeable, mais techniquement ce n’est pas correct. “Transpiler” veut dire “convertir un langage de haut niveau vers un autre langage de haut niveau”. Dans notre cas, quand on développe un bloc, on va écrire des composants React avec du Javascript avancé et du JSX, et on va convertir tout ça en JavaScript “normal” que le navigateur peut comprendre. “Compiler” c’est convertir un langage de haut niveau comme le JavaScript ou le Rust en langage de bas niveau que la machine va comprendre directement. J’utilise donc ce terme par simplicité. Retenez simplement que le JavaScript qu’on écrit quand on développe un bloc n’est pas compréhensible directement par le navigateur et doit être transformé.

Dans votre fichier package.json, on va donc ajouter une entrée scripts et une entrée start à l’intérieur.

{
  "name": "example-plugin",
  "version": "0.1.0",
  "main": "index.js",
  "author": "Vincent Dubroeucq",
  "scripts": {
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^30.15.0"
  }
}

wp-scripts s’attend à ce que les fichiers JavaScript à traiter soient dans un dossier src/, et il s’attend à trouver un fichier index.js comme point d’entrée. Créons donc ce dossier et ce fichier. Dans le fichier src/index.js, insérons le code suivant. Peu importe ce qu’il fait, l’objectif étant de comprendre comment wp-scripts fonctionne.

document.addEventListener('DOMContentLoaded', e => {
    console.log('Hello from src/index.js');
});

Ensuite, on va surveiller les changements dans ce fichier et recompiler notre JavaScript au fur et à mesure. Dans un terminal, placez-vous dans votre projet et lancez la commande npm start. Cela va appeler wp-scripts start et surveiller nos fichiers.

npm start

Un dossier build/ est créé et il contient trois fichiers : index.asset.php, index.js, et index.js.map.

• index.js est notre fichier compilé. C’est le fichier livré au navigateur.
• index.js.map est un fichier utilisé par le navigateur pour tracer les sources de votre code. Quand votre script sera minifié, ce fichier va grandement vous aider à débugger vos erreurs. Il est auto-généré, vous n’avez pas à vous en soucier.
• index.asset.php contient les dépendances du script que vous pouvez utiliser lors de sa déclaration avec wp_enqueue_script() par exemple.

Si vous effectuez une modification dans src/index.js, le contenu du dossier build/ est automatiquement rafraîchi dès que vous sauvegardez.

Comment wp-scripts gère les dépendances

Une application JavaScript n’est que très rarement écrite dans un seul fichier. En général, on va découper notre application en modules JS et on va importer les modules dont on a besoin dans chaque fichier. Chaque module va aussi potentiellement avoir besoin d’autres modules. On a donc une interdépendances entre les modules.

Par exemple, on va utiliser le package @wordpress/i18n de WordPress pour insérer une chaîne traduisible.

// index.js
import { __ } from '@wordpress/i18n';
document.addEventListener('DOMContentLoaded', e => {
    console.log(__('Hello from src/index.js', 'example-plugin'));
});

En important la fonction __() du package @wordpress/i18n, wp-scripts détecte automatiquement la dépendance et va faire en sorte qu’elle soit satisfaite.

La dépendance peut être interne (un module dans votre dossier node_modules/) ou externe (un package externe à charger). Ici, @wordpress/i18n est un package externe : il fait partie de WordPress mais n’est pas inclus dans notre projet. Il faut donc que wp-scripts s’assure que ce package soit disponible quand notre script sera chargé.

Heureusement, wp-scripts est déjà préconfiguré et connait les packages de WordPress. Il sait donc quel package charger AVANT notre script. Dans index.asset.php, vous pouvez voir qu’il a automatiquement ajouté wp-i18n dans nos dépendances.

Plus précisément, wp-scripts va détecter nos dépendances, les organiser selon leur priorité et va combiner notre script et ses dépendances en un seul fichier JavaScript à servir au navigateur.

Il existe beaucoup d’outils de bundling qui permettent de faire ceci : Webpack, Vite, Rollup, etc… Tous ces outils JavaScript font plus ou moins la même chose : ils prennent vos fichiers JavaScript, détectent les dépendances, les organisent et combinent le tout.

En réalité, wp-scripts utilise Webpack, avec une configuration spécifique pour le développement de blocs WordPress.

Préparer la mise en production avec wp-scripts build

Maintenant, imaginons que nous ayons terminé nos développements. Nous souhaitons livrer en production une version minifiée de notre script.

Dans package.json, ajoutons un script raccourci :

{
  ...
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build"
  },
  "devDependencies": {
    "@wordpress/scripts": "^30.15.0"
  }
}

Puis utilisons ce script :

npm run build

Dans le dossier build/ vous verrez que index.js est minifié et le fichier index.assets.php a été mis à jour. Votre script est prêt pour la production !

Pour résumer :

• wp-scripts start permet de lancer vos développements. Par défaut, wp-scripts cherche un fichier index.js dans un dossier src/ et place les fichiers traités dans un dossier build/
• wp-scripts build prépare vos fichiers pour la production en les minifiant.
• wp-scripts va détecter les packages importés et va satisfaire les dépendances. Notre fichier compilé sera une combinaison de notre script et de ses dépendances. Si des dépendances sont externes, il va s’assurer qu’elles soient chargées.

Utiliser wp-scripts pour développer des blocs

Comment structurer vos fichiers pour développer un bloc

Imaginons que vous développiez un bloc pour le nouvel éditeur. Tout commence par le fichier block.json qui va contenir les métadonnées du bloc. Dans le dossier src/ on va simplement ajouter un fichier block.json qui va faire référence à quatre autres fichiers :

• le fichier editor.js qui contient le code de notre bloc,
• editor.css qui contient les styles dans l’éditeur,
• un fichier view.js qui contient un script à charger sur le devant du site
• et view.css qui contient les styles à charger uniquement sur le devant du site.

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "example-plugin/example-block",
    "title": "An example block",
    "version": "1.0.0",
    "textdomain": "example-plugin",
    "editorScript": "file:./editor.js",
    "viewScript": "file:./view.js",
    "editorStyle": "file:./editor.css",
    "viewStyle": "file:./view.css"
}

// src/editor.js
import './editor.css';
document.addEventListener('DOMContentLoaded', e => {
    console.log('Hello from src/editor.js');
});

// src/view.js
import './view.css';
document.addEventListener('DOMContentLoaded', e => {
    console.log('Hello from src/view.js');
});

/* editor.css */
p {
    color: green;
}

/* view.css */
p {
    color: yellow;
}

Les entrées editorScript, viewScript, editorStyle, et viewStyle dans block.json permettent à WordPress de charger automatiquement les bonnes ressources quand votre bloc est déclaré avec register_block_type() en PHP.

Si on utilise npm start pour lancer le développement, vous remarquerez qu’on a beaucoup de fichiers différents générés.

Chaque fichier JavaScript déclaré dans block.json est traité automatiquement par wp-scripts. Vous remarquerez que le fichier src/index.js est absent. A la place, wp-scripts détecte automatiquement le fichier block.json et traite uniquement les fichiers JavaScript déclarés dans ce fichier.

C’est un des avantages à utiliser wp-scripts : il détecte automatiquement vos blocs et va lire le fichier block.json pour trouver les fichiers JavaScript à traiter.

Importer d’autres types de fichiers

Vous remarquerez aussi que dans nos scripts nous avons importé des fichiers CSS. C’est surprenant, car normalement, on ne devrait pouvoir importer que des modules JavaScript.

C’est un autre avantage de wp-scripts. Grâce à sa configuration Webpack particulière, il va détecter les imports d’autres types de fichiers et va les extraire et les traiter de façon adaptée.

Ici, notre fichier CSS a été extrait et placé dans son propre fichier dans le dossier build/.

Si vous travaillez avec SASS, vous pouvez même directement inclure des fichiers .scss, et wp-scripts va automatiquement extraire le contenu de ces fichiers et les compiler.

// src/editor.scss
$color: green;

p {
    color: $color;
}

// src/editor.js
import { __ } from '@wordpress/i18n';
import './editor.scss';

document.addEventListener('DOMContentLoaded', e => {
    console.log(__('Hello from src/editor.js'));
});

Dans le dossier build/, le fichier CSS extrait devient :

p {
  color: green;
}

Travailler avec plusieurs blocs

Imaginons que nous ayons deux blocs à déclarer dans notre extension. Il suffit alors de créer deux dossiers dans src/ qui ont chacun leur fichier block.json, et wp-scripts va automatiquement scanner les sous-dossiers de src/, trouver les fichiers block.json et créer les dossiers correspondants dans build/.

On obtient une arborescence de la forme :

example-plugin/
  build/
    block1/
    block2/
  src/
    block1/
    block2/

Modifier les emplacements des dossiers source et destination

Si vous devez ajouter des blocs à un projet existant, vous disposez surement déjà d’un dossier contenant vos sources JavaScript et/ou un dossier avec les ressources publiques.

Vous pouvez simplement passer des paramètres supplémentaires --source-path et --output-path à vos appels à wp-scripts pour personnaliser ces emplacements.

// package.json
{
  "name": "example-plugin",
  ...
  "scripts": {
    "start": "wp-scripts start --source-path=assets/src --output-path=assets/public",
    "build": "wp-scripts build --source-path=assets/src --output-path=assets/public"
  },
  ...
}

Dans cet exemple, les fichiers source sont à placer dans assets/src/ et les fichiers compilés seront placés dans assets/public/.

Cela donne une arborescence du type :

example-plugin/
  assets/
    public/
      block1/
      block2/
    src/
      block1/
      block2/
  example-plugin.php

Selon votre organisation, vous pouvez donc placer vos dossiers source et destination où vous le souhaitez.

Utiliser wp-scripts avec des scripts traditionnels

Si vous travaillez sur un projet existant, vous avez probablement aussi des scripts traditionnels (pas des blocs) que vous souhaitez traiter et minifier avec wp-scripts. Même si cet outil est fait pour le développement de blocs, dans votre script vous pouvez tout à fait importer d’autres modules et laisser wp-scripts combiner vos dépendances et minifier le script résultant à charger sur le devant du site.

Par défaut, wp-scripts cherche un fichier index.js dans un dossier src/, mais vous pouvez lui spécifier exactement quel(s) point(s) d’entrée utiliser.

Supposons par exemple que vous ayez deux fichiers navigation.js et toggle.js dans votre dossier assets/. Vous pouvez importer n’importe quel package dans ces scripts, les compiler et les minifier en listant les fichiers à traiter dans l’appel à wp-scripts.

// package.json
{
  "name": "example-plugin",
  ...
  "scripts": {
    "start": "wp-scripts start assets/navigation.js assets/toggle.js --output-path=assets/public",
    "build": "wp-scripts build assets/navigation.js assets/toggle.js --output-path=assets/public"
  },
  ...
}

Les commandes vont maintenant compiler les fichiers assets/navigation.js et assets/toggle.js et les placer dans assets/public/.

Vous pouvez aussi demander à wp-scripts de traiter tous les blocs situés dans un dossier source ET des scripts spécifiques. Il faudra simplement que vos scripts soient placés dans le dossier source, à côté de vos blocs :

example-plugin/
  assets/
    public/
    src/
      navigation.js
      toggle.js
      blocks/
        block1/
        block2/
  example-plugin.php

// package.json
{
  "name": "example-plugin",
  ...
  "scripts": {
    "start": "wp-scripts start --source-path=assets/src navigation.js toggle.js --output-path=assets/public",
    "build": "wp-scripts start --source-path=assets/src navigation.js toggle.js --output-path=assets/public",
  },
  ...
}

Dans cet exemple, wp-scripts va traiter tous les blocs qu’il trouve dans assets/src/ et ses sous-dossiers, ainsi que les fichiers navigation.js et toggle.js.

Vous pouvez donc parfaitement utiliser wp-scripts pour traiter tous vos fichiers JavaScript, que ce soit des blocs ou d’autres scripts.

Conclusion

Le package wp-scripts est un outil très puissant et est maintenant l’outil par défaut pour traiter votre JavaScript dans vos développements WordPress.

Initialement prévu pour le développement de blocs, il permet en réalité de traiter tout fichier JavaScript. Mais son plus gros avantage est qu’il ne nécessite aucune configuration car toute la configuration Webpack utilisée en coulisse est embarquée dans le package. Vous pouvez toujours fournir un fichier de configuration Webpack personnalisé, mais c’est assez rarement utile.

Pour résumer :

• wp-scripts est un bundler : il sert à combiner et traiter nos fichiers JavaScript et autres ressources.
• Aucune configuration n’est nécessaire. Il est optimisé pour le développement de blocs.
• Par défaut, wp-scripts cherche vos fichiers source dans un dossier src/ et place les fichiers compilés dans un dossier build/.
• Il détecte automatiquement les blocs en scannant le dossier source et ses sous-dossiers pour trouver les fichiers block.json.
• Il détecte les dépendances de nos scripts, les organise et les combine en un seul fichier de destination.
• Il gère automatiquement les dépendances internes et externes des scripts.
• Il permet d’importer des fichiers SCSS dans votre JavaScript. Vous pouvez même importer des fichiers JSON.
• Les dossiers source et destination sont personnalisables.
• Il permet de traiter simultanément plusieurs blocs et autres fichiers.

J’espère vous avoir aidé à comprendre ce package, et je vous recommande fortement de l’adopter, car il vous simplifiera grandement vos développements !