Komplett guide för att skapa en utvecklingsmiljö för Gutenberg

Den här guiden är till för dig som vill skriva kod för Gutenberg med syntaxerna ES6, ESNext och JSX, och behöver sätta upp webpack och babel för att omvandla dessa till filer du kan använda i Gutenberg-editorn. Vi kommer att titta på vad du behöver göra, varför och hur vi kan använda och utöka standardinställningarna från WordPress och anpassa dem för att passa våra behov.

Om du är helt ny på hela npm, webpcak och Babel-koncepten bör du läsa följande avsnitt som syftar till att förklara grunderna för hur dessa verktyg fungerar och hur du använder dem. Men om du har gjort detta tidigare och är bekant med processen, kanske genom att utveckla med React, hoppa vidare till nästa avsnitt där vi faktiskt ska ställa in saker och ting.

För nybörjare: npm, webpack och babel

Om du är osäker på varför vi behöver göra allt detta för att skriva Javascript för Gutenberg, rekommenderar jag att du läser mitt inlägg som utforskar grunderna för att utveckla för Gutenberg – där jag förklarar skillnaden i Javascript-versioner och varför det är värt besväret.

Om du aldrig har gjort detta förut måste du först installera Node.js på din dator. Klicka på länken, ladda ner och installera den. Inkluderat i Node.js får du ett verktyg som vi kommer att använda för att ställa in det mesta av konfigurationen. Detta verktyg är npm, som låter dig installera Javascript-bibliotek och köra skript via kommandoraden/terminalen. Du kan alternativt använda yarnom du föredrar det, men för den här guiden kommer vi att använda npm.

npm

Den här guiden kommer inte att gå in i detalj om alla saker du kan göra med npm, men den kommer att förklara det grundläggande konceptet för det och saker som är relevanta för våra syften. Vi kommer att använda npmför två saker; för att installera nödvändiga bibliotek i vårt projekt och för att köra kommandon för att bygga (kompilera) våra Javascript-filer.

Med npmkan du installera alla offentliga Javascript-paket med öppen källkod. Om vi ​​skulle utveckla med React (utanför WordPress) skulle vi behöva installera React-bibliotek och webpack-bibliotek. WordPress erbjuder en hel rad bibliotek (främst för Gutenberg) som du kan installera, men vi är egentligen bara intresserade av ett: @wordpress/scripts– vilket hjälper oss att förenkla vår konfiguration.

Närhelst du installerar ett bibliotek, npmskapas en undermapp " node_modules" där de installerade biblioteken lagras. Du behöver aldrig gå in i den här mappen eller ändra något här, men kom ihåg att den här mappen lätt kommer att innehålla (bokstavligen!) tiotusentals filer. Detta är en mapp som du aldrig bör förbinda dig till git eller inkludera i något färdigt tema eller plugin. Biblioteken behövs bara under utveckling.

När din miljö är inställd kan du använda npmför att köra skript definierade i din package.jsonfil. Beroende på projektet skulle du normalt ha minst två skript; en för att bygga skripten och en för att starta "bevakningsläge". I "bevakningsläge" npmstartar en process i terminalen som väntar och lyssnar på ändringar som görs i valfri fil, och kompilerar dem vid körning när du trycker på spara. Du kanske är bekant med detta koncept om du har använt SCSS eller LESS kompilatorprogram tidigare. Det är mycket effektivare att köra ett "watch"-skript i bakgrunden som kompileras om varje gång du sparar, istället för att gå till terminalen och köra byggkommandot efter varje ändring.

webpack och babel

Du kan få genom att utveckla för Gutenberg utan att göra någon webbpack eller babel-konfiguration. Eftersom vi använder WordPress bibliotek kommer de att hantera det åt oss. Detta har dock en nackdel – det har som standard en fast plats och filnamn för både dina käll- och utdatafiler. Hela din Javascript-utveckling måste skrivas i en fil, i project-folder/src/index.js, och bygget kommer alltid att hamna i project-folder/build/index.js. Om du är bra med detta kan du hoppa över hela delen om webbpaketkonfiguration. Men om du utvecklar ett tema eller plugin med flera Gutenberg-funktioner (anpassade block, filter, etc) kanske du åtminstone vill ha ett annat utdatafilnamn och plats samt tillåta flera filer.

Om du använder WordPress paket för att hantera installationen (@wordpress/scripts), är Babel redan konfigurerat. Men du bör vara medveten om att WordPress-paketet kanske inte innehåller plugins som du kanske vill använda. Det finns till exempel ett paket som låter dig använda de nya så kallade "pilfunktionerna" (myFunction = (param) => { }), för att definiera funktioner utan att behöva binda this. Om du absolut vill använda dessa ESNext-funktioner måste du konfigurera Babel själv istället för att använda WordPresss standardinställningar. Jag ska gå igenom hur nedan.

Processen

Processen att utveckla med webpack när allt är konfigurerat och installerat, är att navigera till din projektmapp i terminalen och starta "watch"-skriptet. Den förblir öppen och lyssnar på ändringar som görs i dina JS-filer. När du trycker på spara i dina Javascript-filer kommer terminalen att mata ut information (förhoppningsvis) om att den framgångsrikt har kompilerat om filen. Om det fanns några kompileringsfel kommer de att visas i terminalen. För att stoppa "bevakning"-processen, tryck CTRL + C.

Att sätta upp miljön

Jag antar att du redan har en lokal WordPress som körs på någon LAMP-stack (program som WampServer, XAMPP, Docker eller liknande), och att du har antingen ett plugin eller tema redo att börja koda ditt Javascript i.

Jag rekommenderar att du skapar en undermapp dedikerad för din Javascript-utveckling eftersom du kan få flera konfigurationsfiler och mappar. Detta gör det enklare att separera filer och mappar (till exempel node_modules/) som du inte vill inkludera i git-commits eller final builds. Men det går alldeles utmärkt att använda ditt huvudtema eller plugin-mapp som projektmapp för Javascript-utveckling.

I terminal (Mac OS-terminal eller Windows Kommandotolk fungerar båda bra) navigera till din projektmapp. När det gäller denna handledning antar jag att vi är i ett tema och har skapat en tom undermapp gutenberg-dev/som vår projektmapp.

Det första steget är att initiera ett npm-projekt – vilket i princip bara säger npmatt man ska generera en package.jsonfil. Den här package.jsonfilen informerar npmom vilka paket som krävs och vilka skript som är tillgängliga för körning. Skriv detta i terminal;

npm init -y

Detta genererar en package.jsonfil med standardinnehåll i din projektmapp.

Därefter installerar vi WordPress-paketet som hjälper oss att minska mängden konfiguration vi behöver göra. Kör detta kommando:

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

Taggen --save-devinformerar npmom att de givna biblioteken bara är nödvändiga för utveckling och --save-exactser till att npmbara en version installeras, den senaste.

Öppna package.jsonfilen i din editor. (npmkommer också att ha genererat en package-lock.jsonvid installation av paket, du kan bara ignorera den här filen, det är package.jsondu som gör ändringar i). Den bör vara fylld med standardkonfiguration, och du kanske märker att paketinstallationen vi gjorde tidigare lade till en post @wordpress/scriptsav en viss version i devDependencies. När du kommer att installera fler paket, npmkommer att uppdateras package.jsonmed poster för varje paket. Allt vi behöver tänka på i den här filen är scriptsegenskapen, som är till för skript (kommandon) som du kan använda npmför att köra. Uppdatera skriptegenskapen till detta (du kan ta bort standardtestet):

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

Denna kodbit berättar npmatt vi har två skript vi kan köra i den här projektmappen; "bygga" och "starta". Vi kör ett skript med kommandot npm run <scriptname>, som npmkommer att titta in package.jsonoch utföra kommandot definierat som dess värde. Vi använder verktyget wp-scriptssom kom i paketet vi installerade nyss för att antingen kompilera vårt Javascript en gång ("build") eller starta "titta" / "lyssna"-läge för att kompilera när vi sparar ändringar ("start").

Detta gör att vi också kan använda WordPress webbpaket och Babel-konfiguration, så vi behöver inte göra det själva.

Skapa en undermapp som heter src/. Skapa en index.jsfil i den här mappen.

Om du är bra med webbpaketets standardinställningar är du nu klar! Skriv din ES6- och JSX-kod i index.js, och be om npmatt kompilera dem genom att antingen köra byggkommandot:

npm run build

eller starta en "bevakningsprocess" i terminalen som lyssnar på ändringar gjorda med det här kommandot (använd CTRL+C för att stoppa bevakningsprocessen):

npm run start

Att köra någon av dessa kommer att generera en build/undermapp i din projektkatalog med det kompilerade resultatet i build/index.js.

Det är allt för den mest grundläggande miljöinställningen! Du är nu redo att skriva ES6 Javascript för Gutenberg!

Om du vill ändra platsen och filnamnen för dina käll- eller utdatafiler, läs vidare.

Konfigurera käll- och utdatafilnamn och sökvägar

Om du, som jag, inte är nöjd med standardfilnamnet och -strukturen – speciellt för utdatafilen/filerna, måste du undersöka hur du konfigurerar webpack. Normalt, om du till exempel utvecklade för React utanför WordPress, skulle du behöva konfigurera en fullständig webbpaketkonfiguration med Babel-plugin. Som tur är tar WordPress hand om detta åt oss och låter oss utöka WordPresss egna webbpaketkonfiguration och justera bara de delar vi vill ändra.

package.jsonSkapa en fil med namnet i din projektmapp (samma mapp som) webpack.config.jsoch öppna den i din editor. Skriv följande i denna fil:

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

Det första vi gör är att hämta @wordpress/scriptswebbpaketets konfiguration till variabeln defaultConfig. Inuti webpack-konfigurationen module.exportsär det första vi gör att applicera allt defaultConfiggenom att använda spread-operatorn (...). Dessa två delar ser till att vi utökar WordPress webbpaketkonfiguration genom att inkludera allt i den. Efter spridningsoperatorn kan vi justera eller lägga till vilken egenskap vi vill ändra; i vårt fall källplatsen och utgångsplatsen.

Egenskapen entrydefinierar källfilerna, vilket är som standard ./src/index.js. Varje post i entryegenskapen är ett nyckel+värdepar som webpack kommer att kompilera (och titta på) från. I exemplet ovan har jag definierat ’ block-mynamespace-myblock’ som ligger i src/block-mynamespace-myblock.jssom en ingångspunkt. Du kan lägga till så många nyckel+värdepar här för varje källfil du vill kompilera.

Egenskapen outputbestämmer platsen för kompilerade filer. I pathdefinierar du målmappen för alla kompilerade filer. Jag använder en sökvägshjälp för att kunna navigera korrekt i kataloger i min konfiguration. I exemplet ovan säger jag till webpack att alla kompilerade filer ska hamna i min theme-folder/assets/js/gutenberg/mapp. Det viktiga är att använda ../för att gå upp i katalogträdet, ut ur projektmappen och till en annan mapp där jag vill att alla mitt temas Javascript-filer ska finnas. Justera banan så att den passar din projektstruktur.

För det andra säger jag till webpack att alla filnamn ska namnges som deras motsvarande entrynyckelnamn. Den här webbpaketkonfigurationen kommer att kompilera min theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jstill theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Om jag skulle lägga till ytterligare en källfil som nyckel+värdepar i entry, skulle den kompileras till samma mapp med nyckeln som filnamn.

Gör önskade justeringar i din webpack.config.jsfil och spara. Kör något av npmbyggkommandona igen för att generera filer på deras nya platser.

Det är allt! Du har nu utökat WordPress webbpaketkonfiguration och du styr nu var din källkod och dina utdatafiler ska hamna.

Men jag vill ta med ett sista tips i den här guiden. WordPress standardkonfiguration för Babel kan sakna vissa Babel-plugins för vissa nya funktioner i ESNext. Till exempel med ovanstående standard och WordPresss standardvärden kommer du inte att kunna använda pilfunktioner i din kod. Om detta är viktigt för dig, läs vidare.

Lägg till stöd för de senaste ESNext-syntaxerna med Babel

I skrivande stund saknar WordPresss standard-Babel-inställning stöd för "experimentella syntaxer", som inkluderar till exempel pilfunktioner. För att lägga till stöd för detta måste du tillhandahålla din Babel-konfigurationsfil, och än så länge har jag inte hittat något sätt att utöka WordPress Babel-konfiguration som vi gjorde med webpack-konfigurationen ovan. Så vi måste omdefiniera Babel-förinställningar samt lägga till pluginet "experimentella syntaxer". Men oroa dig inte, det är en väldigt liten fil.

Det första steget är att installera några paket som vi behöver för Babel-förinställningar – vi måste installera samma som definierats i WordPress Babel-konfiguration. Kör det här kommandot för att installera @babel/preset-envoch @babel/preset-react, samt paketet vi är intresserade av; @babel/plugin-proposal-class-properties:

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

Det andra steget är att lägga till Babels konfigurationsfil. .babelrcSkapa en fil med namnet (ingen filtillägg) i din projektmapp .

Notera för Windows: Om du sitter på en Windows-maskin får du inte skapa filer utan filtillägg. För att gå runt detta kan du skapa den här filen med terminal/kommandotolk. Kör detta kommando:

echo hi > .babelrc

Detta kommando kommer att mata ut "hej" i filen .babelrci den aktuella mappen. Du kan nu öppna den här filen i din editor, ta bort "hej" och lägga till det faktiska innehållet nedan.

Du .babelrcborde se ut ungefär så här:

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

Vi definierar samma förinställningar som du normalt skulle göra i ett React-projekt, och samma som WordPress gör det. Det vi lägger till är pluginsfastigheten. Inuti arrayen pluginslägger vi till den @babel/plugin-proposal-class-propertiessom är den nödvändiga Babel-plugin för "experimentella syntaxer" som pilfunktioner.

Slutsats

Tänk på att WordPress kan ändra sin konfiguration när som helst, det är särskilt troligt att detta händer eftersom Gutenberg är ganska ny. Eftersom vi utökar WordPress konfiguration kan vi vid ett tillfälle behöva uppdatera vår konfiguration igen för att passa våra behov. Kanske väljer WordPress att inkludera stöd för experimentella syntaxer så att vi inte behöver göra hela Babel-konfigurationen.

Detta är inte på något sätt en uttömmande guide för att ställa in Webpack och Babel, utan resultatet av en hel del experimenterande och klurande av saker. Jag hoppas att detta har hjälpt dig att lära dig hur du sätter upp din egen Gutenberg-utvecklingsmiljö och gjort det enkelt nog så att detta inte är ett så stort hinder för att börja lära dig ES6, ESNext, JSX och allt det där bra som är bra för utveckling för Gutenberg!