Guide complet sur la configuration d’un environnement de développement pour Gutenberg

Ce guide est destiné à ceux qui souhaitent écrire du code pour Gutenberg avec les syntaxes ES6, ESNext et JSX, et qui doivent configurer webpack et babel pour les transformer en fichiers utilisables dans l’éditeur Gutenberg. Nous examinerons ce que vous devez faire, pourquoi et comment nous pouvons utiliser et étendre les valeurs par défaut de WordPress et les personnaliser en fonction de nos besoins.

Si vous êtes tout nouveau dans l’ensemble des concepts npm, webpcak et Babel, vous devriez lire la section suivante qui vise à expliquer les bases du fonctionnement de ces outils et comment vous les utilisez. Cependant, si vous l’avez déjà fait et que vous connaissez le processus, peut-être en développant avec React, passez à la section suivante où nous allons réellement configurer les choses.

Pour les débutants: npm, webpack et babel

Si vous ne savez pas pourquoi nous devons faire tout cela pour écrire Javascript pour Gutenberg, je vous recommande de lire mon article qui explore les bases du développement pour Gutenberg – où j’explique la différence entre les versions de Javascript et pourquoi cela en vaut la peine.

Si vous ne l’avez jamais fait auparavant, vous devrez d’abord installer Node.js sur votre ordinateur. Cliquez sur le lien, téléchargez-le et installez-le. Inclus dans Node.js, vous obtiendrez un outil que nous utiliserons pour configurer la majeure partie de la configuration. Cet outil est npm, qui vous permet d’installer des bibliothèques Javascript et d’exécuter des scripts via la ligne de commande/le terminal. Vous pouvez également utiliser yarnsi vous le préférez, mais pour ce guide, nous utiliserons npm.

npm

Ce guide n’entrera pas dans les détails de toutes les choses que vous pouvez faire avec npm, mais il en expliquera le concept de base et les éléments pertinents pour nos besoins. Nous allons utiliser npmpour deux choses ; pour installer les bibliothèques requises dans notre projet et pour exécuter des commandes pour créer (compiler) nos fichiers Javascript.

Avec npm, vous pouvez installer n’importe quel package Javascript open source public. Si nous devions développer avec React (en dehors de WordPress), nous aurions besoin d’installer des bibliothèques React et des bibliothèques Webpack. WordPress propose toute une gamme de bibliothèques (principalement pour Gutenberg) que vous pouvez installer, mais nous ne sommes vraiment intéressés que par une: @wordpress/scripts– qui nous aide à simplifier notre configuration.

Chaque fois que vous installez une bibliothèque, npmcréera un sous-dossier " node_modules" où les bibliothèques installées sont stockées. Vous n’aurez jamais besoin d’entrer dans ce dossier ou de modifier quoi que ce soit ici, mais gardez à l’esprit que ce dossier contiendra facilement (littéralement !) Des dizaines de milliers de fichiers. Il s’agit d’un dossier que vous ne devriez jamais engager dans git ou inclure dans un thème ou un plugin fini. Les bibliothèques ne sont nécessaires que lors du développement.

Lorsque votre environnement est configuré, vous pouvez utiliser npmpour exécuter des scripts définis dans votre package.jsonfichier. Selon le projet, vous auriez normalement au moins deux scripts ; un pour construire les scripts et un pour démarrer le "mode montre". En "mode montre", npmdémarre un processus dans le terminal qui attend et écoute les modifications apportées à n’importe quel fichier, et les compile au moment de l’exécution chaque fois que vous cliquez sur Enregistrer. Vous connaissez peut-être ce concept si vous avez déjà utilisé des programmes de compilation SCSS ou LESS. Il est beaucoup plus efficace d’exécuter un script "watch" en arrière-plan qui se recompile à chaque fois que vous enregistrez, au lieu d’aller au terminal et d’exécuter la commande build après chaque modification.

webpack et babel

Vous pouvez développer en développant pour Gutenberg sans faire de configuration webpack ou babel. Parce que nous utilisons les bibliothèques de WordPress, ils s’en chargeront pour nous. Cependant, cela présente un inconvénient – il utilise par défaut un emplacement et un nom de fichier fixes pour vos fichiers source et de sortie. L’ensemble de votre développement Javascript doit être écrit dans un seul fichier, dans project-folder/src/index.js, et la construction finira toujours dans project-folder/build/index.js. Si cela vous convient, vous pouvez ignorer toute la partie sur la configuration du webpack. Cependant, si vous développez un thème ou un plug-in avec plusieurs fonctionnalités de Gutenberg (blocs personnalisés, filtres, etc.), vous souhaiterez peut-être au moins un nom de fichier et un emplacement de sortie différents, ainsi que l’autorisation de plusieurs fichiers.

Si vous utilisez le package WordPress pour gérer la configuration (@wordpress/scripts), Babel est déjà configuré. Mais vous devez savoir que le package de WordPress peut ne pas inclure les plugins que vous souhaitez utiliser. Il y a par exemple un package qui vous permet d’utiliser les nouvelles «fonctions fléchées» (myFunction = (param) => { }), pour définir des fonctions sans avoir besoin de lier this. Si vous voulez absolument utiliser ces fonctionnalités ESNext, vous devrez configurer Babel vous-même au lieu d’utiliser les paramètres par défaut de WordPress. Je vais expliquer comment ci-dessous.

Le processus

Le processus de développement avec Webpack une fois que tout est configuré et installé, consiste à accéder à votre dossier de projet dans le terminal et à démarrer le script "watch". Il restera ouvert et écoutera les modifications apportées à vos fichiers JS. Chaque fois que vous appuyez sur Enregistrer dans vos fichiers Javascript, le terminal affichera (espérons-le) des informations indiquant qu’il a recompilé le fichier avec succès. S’il y a eu des erreurs de compilation, elles apparaîtront dans le terminal. Pour arrêter le processus de "montre", appuyez sur CTRL + C.

Mise en place de l’environnement

Je suppose que vous avez déjà un WordPress local en cours d’exécution sur une pile LAMP (des programmes tels que WampServer, XAMPP, Docker ou similaire), et que vous avez soit un plugin ou un thème prêt à commencer à coder votre Javascript.

Je recommande de créer un sous-dossier dédié à votre développement Javascript car vous pourriez vous retrouver avec plusieurs fichiers et dossiers de configuration. Cela facilite la séparation des fichiers et des dossiers (par exemple node_modules/) que vous ne souhaitez pas inclure dans les commits git ou les versions finales. Mais il est parfaitement possible d’utiliser votre thème principal ou votre dossier de plug-in comme dossier de projet pour le développement Javascript.

Dans le terminal (terminal Mac OS ou invite de commande Windows, les deux fonctionnent correctement), accédez au dossier de votre projet. En ce qui concerne ce didacticiel, je suppose que nous sommes dans un thème et que nous avons créé un sous-dossier vide comme dossier gutenberg-dev/de projet.

La première étape consiste à initialiser un projet npm – qui consiste essentiellement npmà générer un package.jsonfichier. Ce package.jsonfichier informe npmsur les packages requis et les scripts disponibles pour l’exécution. Tapez ceci dans le terminal ;

npm init -y

Cela génère un package.jsonfichier avec un contenu par défaut dans votre dossier de projet.

Ensuite, nous installerons le package WordPress qui nous aidera à réduire la quantité de configuration que nous aurons à faire. Exécutez cette commande :

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

La balise --save-devinforme npmque les bibliothèques données ne sont nécessaires qu’au développement et --save-exacts’assure npmqu’une seule version est installée, la plus récente.

Ouvrez le package.jsonfichier dans votre éditeur. (npmaura également généré un package-lock.jsonlors de l’installation des packages, vous pouvez simplement ignorer ce fichier, c’est dans celui-ci package.jsonque vous apporterez des modifications). Il devrait être rempli avec la configuration par défaut, et vous remarquerez peut-être que l’installation du package que nous avons effectuée précédemment a ajouté une entrée d’ @wordpress/scriptsune certaine version dans devDependencies. Au fur et à mesure que vous installerez plus de packages, npmmettra à jour package.jsonavec des entrées pour chaque package. Tout ce dont nous devons nous préoccuper dans ce fichier est la scriptspropriété, qui concerne les scripts (commandes) que vous pouvez utiliser npmpour exécuter. Mettez à jour la propriété scripts dans celle-ci (vous pouvez supprimer le "test" par défaut) :

"scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
},

Ce morceau de code indique npmque nous avons deux scripts que nous pouvons exécuter dans ce dossier de projet ; "construire" et "démarrer". Nous exécutons un script avec la commande npm run <scriptname>, dans laquelle npmrecherchera package.jsonet exécutera la commande définie comme sa valeur. Nous utilisons l’outil wp-scriptsfourni dans le package que nous venons d’installer pour compiler notre Javascript une fois ("build") ou démarrer le mode "regarder" / "écouter" pour compiler chaque fois que nous enregistrons les modifications ("start").

Cela nous permet également d’utiliser le webpack de WordPress et la configuration Babel, nous n’avons donc pas à le faire nous-mêmes.

Dans votre dossier de projet, créez un sous-dossier appelé src/. Dans ce dossier, créez un index.jsfichier.

Si vous êtes d’accord avec les valeurs par défaut du webpack, vous avez maintenant terminé ! Écrivez votre code ES6 et JSX dans index.js, et dites npmde les compiler en exécutant la commande build :

npm run build

ou démarrez un processus "watch" dans le terminal qui écoute les modifications apportées avec cette commande (utilisez CTRL + C pour arrêter le processus de surveillance):

npm run start

L’exécution de l’un de ces éléments générera directement un sous- build/dossier dans votre projet avec le résultat compilé dans build/index.js.

C’est tout pour la configuration de l’environnement la plus basique ! Vous êtes maintenant prêt à écrire du Javascript ES6 pour Gutenberg !

Si vous souhaitez modifier l’emplacement et les noms de fichiers de vos fichiers source ou de sortie, lisez la suite.

Configuration des noms et chemins des fichiers source et de sortie

Si, comme moi, vous n’êtes pas satisfait du nom de fichier et de la structure par défaut, en particulier pour le ou les fichiers de sortie, vous devez envisager de configurer Webpack. Normalement, par exemple si vous développiez pour React en dehors de WordPress, vous auriez besoin de mettre en place une configuration complète de webpack avec le plugin Babel. Heureusement, WordPress s’en charge pour nous et nous permet d’étendre la propre configuration du pack Web de WordPress et d’ajuster uniquement les parties que nous voulons modifier.

Dans votre dossier de projet (même dossier que package.json) créez un fichier nommé webpack.config.jset ouvrez-le dans votre éditeur. Écrivez ce qui suit dans ce fichier :

const defaultConfig = require("@wordpress/scripts/config/webpack.config");
const path = require('path');
module.exports = {
    ...defaultConfig,
    entry: {
        'block-mynamespace-myblock': './src/block-mynamespace-myblock.js'
    },
    output: {
        path: path.join(__dirname, '../assets/js/gutenberg'),
        filename: '[name].js'
    }
}

La première chose que nous faisons est @wordpress/scriptsde récupérer la configuration du webpack dans la variable defaultConfig. Dans la configuration du webpack module.exports, la première chose que nous faisons est d’appliquer tout en defaultConfigutilisant l’opérateur de propagation (...). Ces deux parties garantissent que nous étendons la configuration du pack Web de WordPress en incluant tout ce qu’il contient. Après l’opérateur de propagation, nous pouvons ajuster ou ajouter toute propriété que nous souhaitons modifier ; dans notre cas, l’emplacement source et l’emplacement de sortie.

La entrypropriété définit les fichiers source, qui est par défaut ./src/index.js. Chaque entrée dans entryla propriété est une paire clé + valeur à partir de laquelle Webpack compilera (et surveillera). Dans l’exemple ci-dessus, j’ai défini ‘ block-mynamespace-myblock‘ situé dans src/block-mynamespace-myblock.jscomme un point d’entrée. Vous pouvez ajouter autant de paires clé + valeur ici pour chaque fichier source que vous souhaitez compiler.

La outputpropriété décide de l’emplacement des fichiers compilés. Dans pathvous définissez le dossier de destination pour tous les fichiers compilés. J’utilise un assistant de chemin pour pouvoir naviguer correctement dans les répertoires de ma configuration. Dans l’exemple ci-dessus, je dis à webpack que tous les fichiers compilés doivent se retrouver dans mon theme-folder/assets/js/gutenberg/dossier. L’important est d’utiliser ../pour remonter dans l’arborescence des répertoires, hors du dossier du projet et dans un autre dossier où je veux que tous les fichiers Javascript de mon thème soient. Ajustez le chemin pour l’adapter à la structure de votre projet.

Deuxièmement, je dis à webpack que tous les noms de fichiers doivent être nommés comme leurs entrynoms de clé correspondants. Cette configuration Webpack compilera mon theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsfichier theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Si je devais ajouter un autre fichier source en tant que paire clé + valeur dans entry, il serait compilé dans le même dossier avec la clé comme nom de fichier.

Effectuez les ajustements souhaités dans votre webpack.config.jsfichier et enregistrez. Réexécutez l’une des npmcommandes de construction pour générer des fichiers dans leurs nouveaux emplacements.

C’est ça! Vous avez maintenant étendu la configuration webpack de WordPress et vous contrôlez maintenant où vos fichiers source et vos fichiers de sortie doivent aller.

Cependant, je souhaite inclure un dernier conseil dans ce guide. La configuration par défaut de WordPress pour Babel peut manquer de certains plugins Babel pour certaines nouvelles fonctionnalités dans ESNext. Par exemple, avec la valeur par défaut ci-dessus et les valeurs par défaut de WordPress, vous ne pourrez pas utiliser les fonctions fléchées dans votre code. Si cela vous intéresse, lisez la suite.

Ajout de la prise en charge des nouvelles syntaxes ESNext avec Babel

Au moment de la rédaction de cette configuration Babel par défaut de WordPress, il manque la prise en charge des «syntaxes expérimentales», qui incluent par exemple les fonctions fléchées. Pour ajouter la prise en charge de cela, vous devez fournir votre fichier de configuration Babel, et pour l’instant je n’ai pas trouvé de moyen d’étendre la configuration Babel de WordPress comme nous l’avons fait avec la configuration webpack ci-dessus. Nous devons donc redéfinir les préréglages de Babel ainsi que l’ajout du plugin "syntaxes expérimentales". Mais ne vous inquiétez pas, c’est un très petit fichier.

La première étape consiste à installer certains packages dont nous avons besoin pour les préréglages Babel – nous devons installer les mêmes que ceux définis dans la configuration Babel de WordPress. Exécutez cette commande pour installer @babel/preset-envet @babel/preset-react, ainsi que le package qui nous intéresse ; @babel/plugin-proposal-class-properties:

npm install --save-dev @babel/preset-env @babel/preset-react @babel/plugin-proposal-class-properties

La deuxième étape consiste à ajouter le fichier de configuration de Babel. Dans votre dossier de projet, créez un fichier nommé .babelrc(sans extension de fichier).

Remarque pour Windows : si vous êtes assis sur une machine Windows, vous n’êtes pas autorisé à créer des fichiers sans extensions de fichier. Pour contourner cela, vous pouvez créer ce fichier à l’aide du terminal/invite de commande. Exécutez cette commande :

Cette commande affichera "salut" dans le fichier .babelrcdu dossier actuel. Vous pouvez maintenant ouvrir ce fichier dans votre éditeur, supprimer le "salut" et ajouter le contenu réel ci-dessous.

Votre .babelrcdevrait ressembler à ceci :

{
    "presets": ["@babel/preset-env", "@babel/preset-react"],
    "plugins": [
        [
            "@babel/plugin-proposal-class-properties"
        ]
    ]
}

Nous définissons les mêmes préréglages que vous feriez normalement dans un projet React, et de la même manière que WordPress le fait. Ce que nous ajoutons est la pluginspropriété. À l’intérieur du tableau, pluginsnous ajoutons le @babel/plugin-proposal-class-propertiesplug-in Babel nécessaire pour les "syntaxes expérimentales" telles que les fonctions fléchées.

Conclusion

Gardez à l’esprit que WordPress peut modifier sa configuration à tout moment, cela est particulièrement susceptible de se produire car Gutenberg est relativement nouveau. Parce que nous étendons la configuration de WordPress, nous pourrions à un moment donné avoir besoin de mettre à jour notre configuration à nouveau pour répondre à nos besoins. Peut-être que WordPress décide d’inclure la prise en charge des syntaxes expérimentales afin que nous n’ayons pas à faire toute la configuration de Babel.

Ce n’est en aucun cas un guide exhaustif pour configurer Webpack et Babel, mais le résultat de nombreuses expérimentations et découvertes. J’espère que cela vous a aidé à apprendre à configurer votre propre environnement de développement Gutenberg et l’a rendu assez facile pour que ce ne soit pas un si gros obstacle pour commencer à apprendre ES6, ESNext, JSX et toutes ces bonnes choses bénéfiques pour développer pour Gutenberg !