Vollständiger Leitfaden zum Einrichten einer Entwicklungsumgebung für Gutenberg

Dieses Handbuch richtet sich an Sie, die Code für Gutenberg mit ES6-, ESNext- und JSX-Syntax schreiben möchten und Webpack und Babel einrichten müssen, um diese in Dateien umzuwandeln, die Sie im Gutenberg-Editor verwenden können. Wir werden uns ansehen, was Sie tun müssen, warum und wie wir die Standardeinstellungen von WordPress verwenden, erweitern und an unsere Bedürfnisse anpassen können.

Wenn Sie mit den gesamten Konzepten von npm, webpcak und Babel ganz neu sind, sollten Sie den folgenden Abschnitt lesen, der darauf abzielt, die Grundlagen zu erklären, wie diese Tools funktionieren und wie Sie sie verwenden. Wenn Sie dies jedoch schon einmal getan haben und mit dem Prozess vertraut sind, vielleicht durch die Entwicklung mit React, fahren Sie mit dem nächsten Abschnitt fort, in dem wir die Dinge tatsächlich einrichten.

Für Anfänger: npm, webpack und babel

Wenn Sie sich nicht sicher sind, warum wir all dies tun müssen, um Javascript für Gutenberg zu schreiben, würde ich Ihnen empfehlen, meinen Beitrag zu lesen, der die Grundlagen der Entwicklung für Gutenberg untersucht – wo ich den Unterschied zwischen den Javascript-Versionen erkläre und warum es die Mühe wert ist.

Wenn Sie dies noch nie zuvor getan haben, müssen Sie zunächst Node.js auf Ihrem Computer installieren. Klicken Sie auf den Link, laden Sie es herunter und installieren Sie es. In Node.js enthalten, erhalten Sie ein Tool, mit dem wir den größten Teil der Konfiguration einrichten. Dieses Tool ist npm, mit dem Sie Javascript-Bibliotheken installieren und Skripte über die Befehlszeile / das Terminal ausführen können. Sie können alternativ verwenden, yarnwenn Sie es bevorzugen, aber für diese Anleitung verwenden wir npm.

npm

Dieser Leitfaden geht nicht ins Detail auf all die Dinge, die Sie mit tun können npm, aber er erklärt das grundlegende Konzept davon und Dinge, die für unsere Zwecke relevant sind. Wir werden npmfür zwei Dinge verwenden; zum Installieren erforderlicher Bibliotheken in unserem Projekt und zum Ausführen von Befehlen zum Erstellen (Kompilieren) unserer Javascript-Dateien.

Mit npmkönnen Sie beliebige öffentliche Open-Source-JavaScript-Pakete installieren. Wenn wir mit React (außerhalb von WordPress) entwickeln würden, müssten wir React-Bibliotheken und Webpack-Bibliotheken installieren. WordPress bietet eine ganze Reihe von Bibliotheken (hauptsächlich für Gutenberg) an, die Sie installieren können, aber uns interessiert wirklich nur eine: @wordpress/scripts– die uns hilft, unsere Konfiguration zu vereinfachen.

Wann immer Sie eine Bibliothek installieren, npmwird ein Unterordner „ node_modules” erstellt, in dem die installierten Bibliotheken gespeichert werden. Sie müssen diesen Ordner niemals öffnen oder hier etwas ändern, aber denken Sie daran, dass dieser Ordner leicht (buchstäblich!) Zehntausende von Bibliotheken enthalten wird Dateien. Dies ist ein Ordner, den Sie niemals in Git übernehmen oder in ein fertiges Design oder Plugin einbinden sollten. Die Bibliotheken werden nur während der Entwicklung benötigt.

Wenn Ihre Umgebung eingerichtet ist, können Sie verwenden npm, um in Ihrer package.jsonDatei definierte Skripts auszuführen. Je nach Projekt haben Sie normalerweise mindestens zwei Skripte; eine zum Erstellen der Skripte und eine zum Starten des „Überwachungsmodus”. Im „Überwachungsmodus” npmstartet ein Prozess im Terminal, der auf Änderungen in einer beliebigen Datei wartet und diese abhört und sie zur Laufzeit kompiliert, wenn Sie auf „Speichern” klicken. Sie sind möglicherweise mit diesem Konzept vertraut, wenn Sie zuvor SCSS- oder LESS-Compilerprogramme verwendet haben. Es ist viel effizienter, ein „Überwachungs”-Skript im Hintergrund auszuführen, das jedes Mal neu kompiliert, wenn Sie speichern, anstatt nach jeder Änderung zum Terminal zu gehen und den Build-Befehl auszuführen.

webpack und babel

Sie können für Gutenberg entwickeln, ohne eine Webpack- oder Babel-Konfiguration vorzunehmen. Da wir die Bibliotheken von WordPress verwenden, werden sie das für uns handhaben. Dies hat jedoch einen Nachteil – es verwendet standardmäßig einen festen Speicherort und Dateinamen für Ihre Quell- und Ausgabedateien. Ihre gesamte Javascript-Entwicklung muss in eine Datei geschrieben werden, in project-folder/src/index.js, und der Build endet immer in project-folder/build/index.js. Wenn Sie damit einverstanden sind, können Sie den gesamten Teil über die Webpack-Konfiguration überspringen. Wenn Sie jedoch ein Design oder Plugin mit mehreren Gutenberg-Funktionen (benutzerdefinierte Blöcke, Filter usw.) entwickeln, möchten Sie möglicherweise zumindest einen anderen Ausgabedateinamen und -speicherort sowie die Möglichkeit, mehrere Dateien zuzulassen.

Wenn Sie das WordPress-Paket für die Einrichtung verwenden (@wordpress/scripts), ist Babel bereits eingerichtet. Sie sollten sich jedoch bewusst sein, dass das WordPress-Paket möglicherweise keine Plugins enthält, die Sie möglicherweise verwenden möchten. Es gibt zum Beispiel ein Paket, mit dem Sie die neuen sogenannten „Pfeilfunktionen” (myFunction = (param) => { }) verwenden können, um Funktionen zu definieren, ohne binden zu müssen this. Wenn Sie diese ESNext-Funktionen unbedingt nutzen möchten, müssen Sie Babel selbst konfigurieren, anstatt die Standardeinstellungen von WordPress zu verwenden. Ich werde unten durchgehen, wie.

Der Prozess

Der Prozess der Entwicklung mit Webpack, sobald alles eingerichtet und installiert ist, besteht darin, zu Ihrem Projektordner im Terminal zu navigieren und das „Watch”-Skript zu starten. Es bleibt geöffnet und hört auf Änderungen, die in Ihren JS-Dateien vorgenommen wurden. Immer wenn Sie in Ihren Javascript-Dateien auf Speichern klicken, gibt das Terminal (hoffentlich) Informationen aus, dass es die Datei erfolgreich neu kompiliert hat. Wenn Kompilierungsfehler aufgetreten sind, werden diese im Terminal angezeigt. Um den „Watch”-Prozess zu stoppen, drücken Sie STRG + C.

Umgebung einrichten

Ich nehme an, Sie haben bereits ein lokales WordPress, das auf einem LAMP-Stack läuft (Programme wie WampServer, XAMPP, Docker oder ähnliches), und Sie haben entweder ein Plugin oder ein Design, mit dem Sie Ihr Javascript programmieren können.

Ich empfehle, einen Unterordner für Ihre Javascript-Entwicklung zu erstellen, da Sie am Ende möglicherweise mehrere Konfigurationsdateien und Ordner haben. Dies erleichtert das Aussondern von Dateien und Ordnern (z. B. node_modules/), die Sie nicht in Git-Commits oder endgültige Builds einbeziehen möchten. Aber es ist völlig in Ordnung, Ihr Hauptthema oder Ihren Plugin-Ordner als Projektordner für die Javascript-Entwicklung zu verwenden.

Navigieren Sie im Terminal (Mac OS-Terminal oder Windows-Eingabeaufforderung funktionieren beide einwandfrei) zu Ihrem Projektordner. Für dieses Tutorial gehe ich davon aus, dass wir uns in einem Design befinden und einen leeren Unterordner gutenberg-dev/als unseren Projektordner erstellt haben.

Der erste Schritt ist die Initialisierung eines npm-Projekts – was im Grunde nur bedeutet, eine Datei npmzu generieren. package.jsonDiese package.jsonDatei informiert npmdarüber, welche Pakete erforderlich sind und welche Skripte zum Ausführen verfügbar sind. Geben Sie dies im Terminal ein;

npm init -y

Dadurch wird eine package.jsonDatei mit Standardinhalt in Ihrem Projektordner erstellt.

Als Nächstes installieren wir das WordPress-Paket, das uns dabei hilft, den Konfigurationsaufwand zu reduzieren. Führen Sie diesen Befehl aus:

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

Das Tag --save-devinformiert npm, dass die angegebenen Bibliotheken nur für die Entwicklung erforderlich sind, und --save-exactstellt sicher, dass npmnur eine Version installiert wird, die neueste.

Öffnen Sie die package.jsonDatei in Ihrem Editor. (npmwird beim Installieren von Paketen auch eine generiert haben package-lock.json, Sie können diese Datei einfach ignorieren, package.jsonSie werden darin Änderungen vornehmen). Es sollte mit der Standardkonfiguration gefüllt sein, und Sie werden vielleicht bemerken, dass die Paketinstallation, die wir zuvor durchgeführt haben, einen Eintrag @wordpress/scriptseiner bestimmten Version in hinzugefügt hat devDependencies. Wenn Sie weitere Pakete installieren, wird es mit Einträgen für jedes Paket npmaktualisiert. package.jsonAlles, worum wir uns in dieser Datei kümmern müssen, ist die scriptsEigenschaft, die für Skripte (Befehle) bestimmt ist, die Sie npmzum Ausführen verwenden können. Aktualisieren Sie die scripts-Eigenschaft in diese (Sie können den Standard „test” entfernen):

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

Dieses Stück Code sagt npm, dass wir zwei Skripte haben, die wir in diesem Projektordner ausführen können; „bauen” und „starten”. Wir führen ein Skript mit dem Befehl npm run <scriptname>aus, in dem der als Wert definierte Befehl gesucht und ausgeführt wird npm. package.jsonWir verwenden das Tool wp-scripts, das in dem Paket enthalten war, das wir gerade installiert haben, um entweder unser Javascript einmal zu kompilieren ("build") oder den „Watch” / „Listen”-Modus zu starten, um es zu kompilieren, wenn wir Änderungen speichern ("start").

Dadurch können wir auch das Webpack von WordPress und die Babel-Konfiguration verwenden, sodass wir es nicht selbst tun müssen.

Erstellen Sie in Ihrem Projektordner einen Unterordner namens src/. Erstellen Sie in diesem Ordner eine index.jsDatei.

Wenn Sie mit den Webpack-Standardeinstellungen zufrieden sind, sind Sie jetzt fertig! Schreiben Sie Ihren ES6- und JSX-Code in index.jsund weisen Sie npman, sie zu kompilieren, indem Sie entweder den build-Befehl ausführen:

npm run build

oder starten Sie einen „Überwachungsprozess” im Terminal, der auf Änderungen lauscht, die mit diesem Befehl vorgenommen wurden (verwenden Sie STRG+C, um den Überwachungsprozess zu stoppen):

npm run start

Wenn Sie eines davon ausführen, wird in Ihrem Projekt direkt ein build/Unterordner mit dem kompilierten Ergebnis in build/index.js.

Das ist alles für die grundlegendste Umgebungseinrichtung! Sie sind jetzt bereit, ES6 Javascript für Gutenberg zu schreiben!

Wenn Sie den Speicherort und die Dateinamen Ihrer Quell- oder Ausgabedateien ändern möchten, lesen Sie weiter.

Konfigurieren von Quell- und Ausgabedateinamen und -pfaden

Wenn Sie, wie ich, mit dem Standarddateinamen und der Standardstruktur nicht zufrieden sind – insbesondere für die Ausgabedatei(en), müssen Sie sich mit der Konfiguration von Webpack befassen. Wenn Sie beispielsweise außerhalb von WordPress für React entwickeln, müssen Sie normalerweise eine vollständige Webpack-Konfiguration mit dem Babel-Plugin einrichten. Glücklicherweise übernimmt WordPress dies für uns und ermöglicht es uns, die eigene Webpack-Konfiguration von WordPress zu erweitern und nur die Teile anzupassen, die wir ändern möchten.

Erstellen Sie in Ihrem Projektordner (gleicher Ordner wie package.json) eine Datei mit dem Namen webpack.config.jsund öffnen Sie sie in Ihrem Editor. Schreiben Sie Folgendes in diese Datei:

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'
    }
}

Als erstes laden wir die @wordpress/scriptsWebpack-Konfiguration in die Variable defaultConfig. In der Webpack-Konfiguration wenden module.exportswir als Erstes alles an, defaultConfigindem wir den Spread-Operator (...) verwenden. Diese beiden Teile stellen sicher, dass wir die Webpack-Konfiguration von WordPress erweitern, indem wir alles darin einschließen. Nach dem Spread-Operator können wir jede Eigenschaft, die wir ändern möchten, anpassen oder hinzufügen; in unserem Fall Quellort und Ausgangsort.

Die entryEigenschaft definiert die Quelldateien, die standardmäßig ./src/index.js. Jeder Eintrag in entryEigenschaft ist ein Schlüssel+Wert-Paar, aus dem Webpack kompiliert (und überwacht). Im obigen Beispiel habe ich „ block-mynamespace-myblock” befindet sich in src/block-mynamespace-myblock.jsals einen Einstiegspunkt definiert. Sie können hier beliebig viele Schlüssel+Wert-Paare für jede Quelldatei hinzufügen, die Sie kompilieren möchten.

Die outputEigenschaft entscheidet über den Speicherort der kompilierten Dateien. In pathdefinieren Sie den Zielordner für alle kompilierten Dateien. Ich verwende einen Pfadhelfer, um in meiner Konfiguration richtig durch Verzeichnisse navigieren zu können. Im obigen Beispiel sage ich webpack, dass alle kompilierten Dateien in meinem theme-folder/assets/js/gutenberg/Ordner landen sollen. Wichtig ist, dass ../Sie im Verzeichnisbaum nach oben aus dem Projektordner in einen anderen Ordner wechseln, in dem sich alle Javascript-Dateien meines Themas befinden sollen. Passen Sie den Pfad an Ihre Projektstruktur an.

Zweitens sage ich webpack, dass alle Dateinamen als ihre entsprechenden entrySchlüsselnamen benannt werden sollten. Diese Webpack-Konfiguration kompiliert meine theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsin theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Wenn ich eine weitere Quelldatei als Schlüssel+Wert-Paar in hinzufügen entrywürde, würde sie in denselben Ordner mit dem Schlüssel als Dateinamen kompiliert.

Nehmen Sie die gewünschten Anpassungen in Ihrer webpack.config.jsDatei vor und speichern Sie. Führen Sie einen der npmBuild-Befehle erneut aus, um Dateien an ihren neuen Speicherorten zu generieren.

Das ist es! Sie haben jetzt die Webpack-Konfiguration von WordPress erweitert und steuern jetzt, wohin Ihre Quell- und Ihre Ausgabedateien gehen sollen.

Ich möchte jedoch einen letzten Tipp in diesen Leitfaden aufnehmen. In der Standardkonfiguration von WordPress für Babel fehlen möglicherweise bestimmte Babel-Plugins für bestimmte neue Funktionen in ESNext. Mit der obigen Standardeinstellung und den Standardeinstellungen von WordPress können Sie beispielsweise keine Pfeilfunktionen in Ihrem Code verwenden. Wenn Ihnen das wichtig ist, lesen Sie weiter.

Unterstützung für die neuesten ESNext-Syntaxen mit Babel hinzufügen

Zum Zeitpunkt des Schreibens dieses WordPress-Standard-Babel-Setups fehlt die Unterstützung für „experimentelle Syntaxen”, die beispielsweise Pfeilfunktionen umfassen. Um dies zu unterstützen, müssen Sie Ihre Babel-Konfigurationsdatei bereitstellen, und bis jetzt habe ich keine Möglichkeit gefunden, die Babel-Konfiguration von WordPress zu erweitern, wie wir es oben mit der Webpack-Konfiguration getan haben. Also müssen wir die Babel-Voreinstellungen neu definieren und das Plugin „experimentelle Syntaxen” hinzufügen. Aber keine Sorge, es ist eine sehr kleine Datei.

Der erste Schritt ist die Installation einiger Pakete, die wir für Babel-Voreinstellungen benötigen – wir müssen die gleichen installieren, die in der Babel-Konfiguration von WordPress definiert sind. Führen Sie diesen Befehl aus, um @babel/preset-envund @babel/preset-reactsowie das Paket, an dem wir interessiert sind, zu installieren. @babel/plugin-proposal-class-properties:

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

Der zweite Schritt ist das Hinzufügen der Babel-Konfigurationsdatei. Erstellen Sie in Ihrem Projektordner eine Datei mit dem Namen .babelrc(ohne Dateierweiterung).

Hinweis für Windows: Wenn Sie auf einem Windows-Rechner sitzen, dürfen Sie keine Dateien ohne Dateierweiterungen erstellen. Um dies zu umgehen, können Sie diese Datei mit Terminal/Eingabeaufforderung erstellen. Führen Sie diesen Befehl aus:

Dieser Befehl gibt „hi” in die Datei .babelrcim aktuellen Ordner aus. Sie können diese Datei nun in Ihrem Editor öffnen, das „hi” entfernen und den eigentlichen Inhalt unten hinzufügen.

Ihr .babelrcsollte ungefähr so ​​​​aussehen:

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

Wir definieren die gleichen Voreinstellungen wie normalerweise in einem React-Projekt und genauso wie WordPress es tut. Was wir hinzufügen, ist die pluginsEigenschaft. Innerhalb des Arrays von pluginsfügen wir das hinzu, @babel/plugin-proposal-class-propertieswas das notwendige Babel-Plugin für „experimentelle Syntaxen” wie Pfeilfunktionen ist.

Fazit

Denken Sie daran, dass WordPress seine Konfiguration jederzeit ändern kann, dies ist besonders wahrscheinlich, weil Gutenberg ziemlich neu ist. Da wir die Konfiguration von WordPress erweitern, müssen wir unsere Konfiguration möglicherweise irgendwann erneut aktualisieren, um sie an unsere Anforderungen anzupassen. Vielleicht beschließt WordPress, Unterstützung für experimentelle Syntaxen einzuschließen, damit wir nicht die gesamte Babel-Konfiguration vornehmen müssen.

Dies ist keineswegs eine erschöpfende Anleitung zum Einrichten von Webpack und Babel, sondern das Ergebnis einer ganzen Menge Experimentieren und Herausfinden von Dingen. Ich hoffe, dies hat Ihnen beim Erlernen der Einrichtung Ihrer eigenen Gutenberg-Entwicklungsumgebung geholfen und es so einfach gemacht, dass dies keine so große Hürde darstellt, um mit dem Erlernen von ES6, ESNext, JSX und all den guten Dingen zu beginnen, die für die Entwicklung von Vorteil sind Gutenberg!