Ein Gutenberg-Block kann komplett ohne zusätzliche Tools mit klassischem JavaScript erstellt werden. Einfacher und übersichtlicher (zumindest nach meinem Empfinden) wird es aber durch den Einsatz von Dingen wie JSX, damit HTML-Elemente innerhalb von JavaScript fast wie normale HTML-Elemente erstellt werden können.
Weniger einfach ist an dem Teil die Einrichtung der Entwicklungsumgebung, um etwa JSX nutzen zu können. Inzwischen ist das aber deutlich leichter geworden, so gibt es ein NPM-Package, das eigentlich alles mitbringt, was für die Gutenberg-Entwicklung notwendig ist 🎉
@wordpress/scripts to the rescue
Im Januar 2018 wurde die erste Version des @wordpress/scripts-NPM-Pakets veröffentlicht. Anfangs enthielt es Tools zum Testen von Code, später kamen Dinge wie Babel-Kompilierung von JavaScript mit Webpack und JSX-Support dazu, und dieses Jahr wurde auch die Behandlung von Style-Dateien hinzugefügt.
Damit ist das Package mindestens für den Anfang der Block-Entwicklung eigentlich die einzige Abhängigkeit, die wir benötigen. Natürlich kann es sein, dass in speziellen Fällen weitere Abhängigkeiten installiert werden müssen, aber für viele Blöcke dürfte es ausreichen.
Voraussetzung und Installation
Voraussetzung ist, dass Node und NPM installiert (NPM kommt in der Regel mit der Node-Installation) und halbwegs aktuell sind – @wordpress/scripts benötigt mindestens Node 10 und NPM 6.9.0. Außerdem wäre eine lokale WordPress-Installation nicht schlecht, in der der zu erstellende Block getestet werden kann.
Wenn das gegeben ist, erstellt einen Order für euer Plugin und führt darin mittels der Konsole den Befehl npm init aus, um eine package.json-Datei zu erstellen. Nachdem ihr den Befehl ausgeführt habt, werdet ihr einige Dinge gefragt, etwa nach dem Package-Namen und der Version. Unter anderem werdet ihr auch nach dem entry point gefragt, dessen Standardwert auf index.js gesetzt ist. Das ist nur relevant, wenn der Block als NPM-Package veröffentlicht werden würde, ich lösche den Eintrag meist manuell aus der erstellten package.json.
Als Ergebnis des Befehls solltet ihr in dem Plugin-Verzeichnis eine package.json vorfinden, die vom Prinzip so aussieht:
{
"name": "krautpress-patterns-block",
"version": "1.0.0",
"description": "",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "Florian Brinkmann",
"license": "GPL-3.0-or-later",
}Code-Sprache: JSON / JSON mit Kommentaren (json)Jetzt können wir das @wordpress/scripts-Paket mit dem folgenden Befehl installieren:
npm install @wordpress/scripts --save-devCode-Sprache: Bash (bash)Dadurch sollte in der package.json ein neuer Eintrag eingefügt werden (die Versionsnummer könnte bei euch anders sein):
"devDependencies": {
"@wordpress/scripts": "^12.6.0"
}Code-Sprache: JSON / JSON mit Kommentaren (json)Jetzt benötigen wir noch eine src/index.js-Datei. Diese Datei nutzt @wordpress/scripts als Ausgangspunkt für seine Funktionen.
Damit haben wir die Voraussetzungen erfüllt 🎉 Jetzt schauen wir uns kurz an, nach welchem Schema die Dateien und Dateitypen verarbeitet werden.
Schema der Verarbeitung von JavaScript- und Stylesheet-Dateien
Wie bereits erwähnt, muss die Haupt-JavaScript-Datei index.js heißen und im src-Verzeichnis liegen. Das Ergebnis der Verarbeitung des JavaScript-Codes durch @wordpress/scripts wird als index.js im build-Verzeichnis gespeichert.
Wenn ihr im Plugin auch CSS für den Block braucht, könnt ihr .css, .scss oder .sass-Dateien verwenden (eine Mischung der unterschiedlichen Typen ist auch möglich) und erstellt die Dateien am besten ebenfalls im src-Verzeichnis. Damit @wordpress/scripts die Dateien verarbeitet, müssen sie in die index.js (oder eine dort importierte JavaScript-Datei) eingebunden werden.
Gehen wir davon aus, dass eine src/index.css-Datei existiert, dann könnten wir die wie folgt in die src/index.js importieren:
import './index.css';Code-Sprache: JavaScript (javascript)Alle importierten Stylesheet-Dateien werden durch die später besprochenen start– und build-Skripte in die build/index.css verarbeitet. Diese Datei ist für Styles gedacht, die nur im Editor verwendet werden.
Die einzige Ausnahme ist, wenn eine style.(css|scss|sass)-Datei importiert wird: diese Datei wird zu einer build/style-index.css verarbeitet und soll Regeln beinhalten, die für das Frontend und den Editor gelten.
Kommen wir jetzt zu den Möglichkeiten, die @wordpress/scripts bietet.
@wordpress/scripts und seine Möglichkeiten
Das @wordpress/scripts-Paket kommt mit einem praktischen Modul wp-scripts, das uns erlaubt, Funktionen des Pakets relativ einfach über NPM-Skripte auszuführen.
Vielleicht fragt ihr euch jetzt, was »NPM-Skripte« sind. In der package.json seht ihr den Eintrag scripts, der nach npm init das Skript test enthält. Dieses Skript könnt ihr wie folgt ausführen:
npm run testCode-Sprache: Bash (bash)Ihr solltet als Ausgabe den Satz »Error: no test specified« sowie eine Fehlermeldung zurückbekommen.
Zurück zu wp-scripts: Ich setze bisher meist nur die Befehle start und build ein, aber es gibt noch deutlich mehr. Im folgenden werde ich auf die zum Zeitpunkt der Veröffentlichung des Beitrags verfügbaren Funktionen eingehen, vorab hier eine Liste der Befehle als NPM-Skripte, wie sie in die package.json eingefügt werden kann:
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start",
"check-engines": "wp-scripts check-engines",
"check-licenses": "wp-scripts check-licenses",
"format:js": "wp-scripts format-js",
"lint:css": "wp-scripts lint-style",
"lint:js": "wp-scripts lint-js",
"lint:md:docs": "wp-scripts lint-md-docs",
"lint:md:js": "wp-scripts lint-md-js",
"lint:pkg-json": "wp-scripts lint-pkg-json",
"packages-update": "wp-scripts packages-update",
"test:e2e": "wp-scripts test-e2e",
"test:unit": "wp-scripts test-unit-js"
},Code-Sprache: JavaScript (javascript)start- und build-Befehl
Beide Befehle nehmen sich eure src/index.js vor, verarbeiten diese sowie gegebenenfalls importierte Dateien und speichern die Ergebnisse im build-Verzeichnis, von wo sie durch das Plugin genutzt werden können.
start ist während der Entwicklung nützlich, da es einen Watcher startet und auf Änderungen in der src/index.js und eingebundenen Dateien lauscht. Sobald sich eine Datei ändert, werden die build-Dateien neu erzeugt und die Änderungen können getestet werden, ohne erst ein NPM-Skript starten zu müssen.
build erzeugt minifizierte Dateien, die für den Produktiv-Einsatz optimiert sind.
Außerdem sehr praktisch: durch das Dependency Extraction Webpack Plugin wird eine build/index.asset.php erzeugt, die unter anderem ein Array mit den WordPress-Skripten enthält, die vor unserem Plugin-Skript geladen werden müssen. Wenn in unserem Skript beispielsweise import { Component } from '@wordpress/element'; steht, führt das zum wp-element-Eintrag in dem Array. Zusätzlich sorgt das Webpack-Plugin dafür, dass diese WordPress-Abhängigkeiten nicht in dem Build-Skript eingebunden werden, da sie ja über WordPress geladen werden können. Welche Skripte dabei genau unterstützt werden und wie das Einbinden eines Skripts mit dem Abhängigkeiten-Array aussehen kann, ist beispielhaft in der verlinkten Dokumentation des Webpack-Plugins beschrieben.
Beide Befehle können angepasst werden, um zum Beispiel mehrere JavaScript-Dateien als Einstiegspunkte zu definieren und/oder das Verzeichnis für die verarbeiteten Dateien zu verändern. Mehr Informationen dazu findet ihr auf der Seite des NPM-Packages.
check-engines- und check-licenses-Befehl
Über check-engines kann geprüft werden, ob die installierte Node- und NPM-Version den Voraussetzungen entspricht.
check-licenses prüft, ob die Lizenzen der NPM-Pakete mit der Lizenz des Projekts kompatibel sind.
format-js-Befehl
Der format-js-Befehl formatiert Source-JavaScript-Dateien nach den JavaScript-Coding-Standards. Dateien in den Verzeichnissen build, node_modules, vendor und wordpress werden standardmäßig ignoriert.
lint-js-, lint-pkg-json-, lint-md-docs-, lint-md-js- und lint-style-Befehl
Wie an den Namen erkennbar, sind diese Befehle alle dafür da, um Code auf die Einhaltung von Coding-Standards zu überprüfen:
lint-jskümmert sich um JavaScript-Source-Dateien,linkt-pkg-jsonum diepackage.json-Datei,lint-md-docsum Markdown-Dateien,lint-md-jsum Code-Blöcke in Markdown-Dateien undlint-styleum Style-Dateien.
Alle fünf Skripte ignorieren Dateien in den Verzeichnissen build, node_modules, vendor und wordpress.
packages-update-Befehl
Der Befehl aktualisiert WordPress-Pakete (beginnend mit @wordpress/) in der package.json auf ihre neueste Version.
test-e2e- und test-unit-js-Befehl
Diese beiden Befehle sind für das Schreiben von Tests. test-e2e startet den End-To-End-Test-Runner, Tests können mit dem JEST-API in Verbindung mit dem Puppeteer-API geschrieben werden.
test-unit-js startet den Unit-Test-Runner, Tests können mit dem JEST-API geschrieben werden.
Weitere Möglichkeiten
Bei einigen Befehlen gibt es zusätzliche Optionen – ihr findet alle Befehle mit den verfügbaren Optionen auf der NPM-Seite des Pakets.
Weiter unten auf der Seite gibt es noch einen Bereich Advanced Usage, der beispielsweise beschreibt, wie eine eigene Webpack-Konfiguration genutzt werden kann.
Fazit
Die Möglichkeiten, die @wordpress/scripts bietet, sind auf den ersten Blick vielleicht etwas überwältigend. Die wichtigsten Befehle sind start und build, alles andere ist schön, aber nicht notwendig um für Gutenberg zu entwickeln.
Dank @wordpress/scripts brauchen wir uns in der Regel nur noch um die Installation eines NPM-Pakets zu kümmern und können dann direkt loslegen, ohne uns mit Dingen wie der Webpack-Konfiguration rumschlagen zu müssen, und das ist sehr, sehr angenehm.
Mentions