Kompletny przewodnik po tworzeniu środowiska programistycznego dla Gutenberg

Ten przewodnik jest dla tych, którzy chcą pisać kod dla Gutenberga za pomocą składni ES6, ESNext i JSX i muszą skonfigurować pakiet webpack i babel, aby przekształcić je w pliki, których można używać w edytorze Gutenberg. Przyjrzymy się, co musisz zrobić, dlaczego i jak możemy używać i rozszerzać domyślne ustawienia WordPressa oraz dostosowywać je do naszych potrzeb.

Jeśli jesteś nowy w koncepcji całych npm, webpcak i Babel, powinieneś przeczytać następną sekcję, która ma na celu wyjaśnienie podstaw działania tych narzędzi i sposobu ich używania. Jeśli jednak robiłeś to już wcześniej i znasz ten proces, być może poprzez programowanie w React, przejdź do następnej sekcji, w której będziemy właściwie konfigurować.

Dla początkujących: npm, webpack i babel

Jeśli nie masz pewności, dlaczego musimy to wszystko zrobić, aby pisać JavaScript dla Gutenberga, polecam przeczytanie mojego postu, który bada podstawy programowania dla Gutenberga – gdzie wyjaśniam różnicę w wersjach JavaScript i dlaczego jest to warte zachodu.

Jeśli nigdy wcześniej tego nie robiłeś, najpierw musisz zainstalować Node.js na swoim komputerze. Kliknij link, pobierz i zainstaluj. Zawarte w Node.js otrzymasz narzędzie, którego użyjemy do skonfigurowania większości konfiguracji. Jest to narzędzie npm, które pozwala instalować biblioteki Javascript i uruchamiać skrypty za pomocą wiersza poleceń / terminala. Możesz alternatywnie użyć yarn, jeśli wolisz, ale w tym przewodniku użyjemy npm.

npm

Ten przewodnik nie zawiera szczegółowych informacji o wszystkich czynnościach, z którymi możesz zrobić npm, ale wyjaśni podstawową koncepcję i rzeczy, które są istotne dla naszych celów. Użyjemy npmdo dwóch rzeczy; za instalowanie wymaganych bibliotek w naszym projekcie i uruchamianie poleceń do budowania (kompilacji) naszych plików JavaScript.

Dzięki npmniemu możesz zainstalować dowolne publiczne pakiety JavaScript o otwartym kodzie źródłowym. Gdybyśmy mieli programować w React (poza WordPress), musielibyśmy zainstalować biblioteki React i biblioteki webpack. WordPress oferuje całą gamę bibliotek (głównie dla Gutenberga), które możesz zainstalować, ale tak naprawdę interesuje nas tylko jedna: @wordpress/scripts– która pomaga nam uprościć konfigurację.

Za każdym razem, gdy instalujesz bibliotekę, npmutworzy podfolder „ node_modules", w którym przechowywane są zainstalowane biblioteki. Nigdy nie będziesz musiał wchodzić do tego folderu ani niczego tutaj zmieniać, ale pamiętaj, że ten folder z łatwością będzie zawierał (dosłownie!) dziesiątki tysięcy Pliki. Jest to folder, którego nigdy nie powinieneś zobowiązywać się do git ani dołączać do żadnego gotowego motywu lub wtyczki. Biblioteki są potrzebne tylko podczas programowania.

Po skonfigurowaniu środowiska możesz używać npmdo uruchamiania skryptów zdefiniowanych w package.jsonpliku. W zależności od projektu normalnie masz co najmniej dwa skrypty; jeden do budowania skryptów, a drugi do uruchamiania „trybu oglądania”. W „trybie oglądania” npmuruchamia proces w terminalu, który czeka i nasłuchuje zmian dokonanych w dowolnym pliku i kompiluje je w czasie wykonywania, gdy klikniesz Zapisz. Być może znasz tę koncepcję, jeśli wcześniej korzystałeś z kompilatorów SCSS lub LESS. O wiele bardziej wydajne jest uruchomienie skryptu „obserwującego” w tle, który rekompiluje się za każdym razem, gdy zapisujesz, zamiast przechodzić do terminala i uruchamiać polecenie budowania po każdej zmianie.

webpack i babel

Możesz uzyskać, rozwijając dla Gutenberga bez robienia jakiejkolwiek konfiguracji webpacka lub babel. Ponieważ korzystamy z bibliotek WordPressa, zajmą się tym za nas. Ma to jednak jedną wadę – domyślnie ma stałą lokalizację i nazwę pliku zarówno dla plików źródłowych, jak i wyjściowych. Cały program JavaScript musi być napisany w jednym pliku, w project-folder/src/index.js, a kompilacja zawsze kończy się w project-folder/build/index.js. Jeśli nie masz nic przeciwko, możesz pominąć całą część dotyczącą konfiguracji webpacka. Jeśli jednak tworzysz motyw lub wtyczkę z kilkoma funkcjami Gutenberga (niestandardowe bloki, filtry itp.), Możesz przynajmniej chcieć mieć inną nazwę pliku wyjściowego i lokalizację, a także zezwalać na wiele plików.

Jeśli używasz pakietu WordPress do obsługi instalacji (@wordpress/scripts), Babel jest już skonfigurowany. Ale powinieneś mieć świadomość, że pakiet WordPressa może nie zawierać wtyczek, których możesz chcieć użyć. Istnieje na przykład pakiet, który pozwala na użycie nowych tak zwanych „funkcji strzałek” (myFunction = (param) => { }), do definiowania funkcji bez konieczności wiązania this. Jeśli absolutnie chcesz korzystać z tych funkcji ESNext, musisz samodzielnie skonfigurować Babel zamiast korzystać z domyślnych ustawień WordPressa. Przejdę poniżej.

Proces

Proces tworzenia za pomocą webpacka po skonfigurowaniu i zainstalowaniu wszystkiego polega na przejściu do folderu projektu w terminalu i uruchomieniu skryptu „obserwuj”. Pozostanie otwarty i będzie słuchać zmian wprowadzonych w plikach JS. Za każdym razem, gdy klikniesz zapisz w plikach JavaScript, terminal wyświetli informacje (miejmy nadzieję), że pomyślnie ponownie skompilował plik. Jeśli wystąpiły jakieś błędy kompilacji, pojawią się one w terminalu. Aby zatrzymać proces „oglądania”, naciśnij CTRL + C.

Konfigurowanie środowiska

Zakładam, że masz już lokalny WordPress działający na jakimś stosie LAMP (programy takie jak WampServer, XAMPP, Docker lub podobne) i że masz wtyczkę lub motyw gotowy do rozpoczęcia kodowania JavaScript.

Zalecam utworzenie podfolderu dedykowanego do rozwoju JavaScript, ponieważ możesz otrzymać kilka plików konfiguracyjnych i folderów. Ułatwia to oddzielanie plików i folderów (na przykład node_modules/), których nie chcesz uwzględniać w zatwierdzeniach git lub ostatecznych kompilacjach. Ale całkiem dobrze jest użyć głównego motywu lub folderu wtyczek jako folderu projektu do programowania JavaScript.

W terminalu (terminal Mac OS lub wiersz poleceń systemu Windows działają dobrze) przejdź do folderu projektu. Jeśli chodzi o ten samouczek, założę, że jesteśmy w motywie i utworzyliśmy pusty podfolder gutenberg-dev/jako folder naszego projektu.

Pierwszym krokiem jest zainicjowanie projektu npm – co w zasadzie jest po prostu nakazem npmwygenerowania package.jsonpliku. Ten package.jsonplik informuje npm, jakie pakiety są wymagane i jakie skrypty są dostępne do uruchomienia. Wpisz to w terminalu;

npm init -y

Spowoduje to wygenerowanie package.jsonpliku z domyślną zawartością w folderze projektu.

Następnie zainstalujemy pakiet WordPress, który pomoże nam zmniejszyć ilość konfiguracji, które będziemy musieli wykonać. Uruchom to polecenie:

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

Znacznik --save-devinformuje npm, że dane biblioteki są potrzebne tylko do rozwoju i --save-exactzapewnia, że npm​​zainstalowano tylko jedną wersję, najnowszą.

Otwórz package.jsonplik w swoim edytorze. (npmbędzie również wygenerowany package-lock.jsonpodczas instalacji pakietów, możesz po prostu zignorować ten plik, package.jsonbędziesz w nim wprowadzać zmiany). Powinien być wypełniony domyślną konfiguracją, a możesz zauważyć, że instalacja pakietu, którą przeprowadziliśmy wcześniej, dodała wpis o @wordpress/scriptsokreślonej wersji w devDependencies. Gdy zainstalujesz więcej pakietów, npmzaktualizuje package.jsonsię wpisy dla każdego pakietu. Jedyne, o co musimy się martwić w tym pliku, to scriptswłaściwość, która dotyczy skryptów (komend), których można używać npmdo uruchamiania. Zaktualizuj właściwość scripts do tego (możesz usunąć domyślny „test”):

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

Ten fragment kodu mówi npm, że mamy dwa skrypty, które możemy uruchomić w tym folderze projektu; „buduj” i „startuj”. Uruchamiamy skrypt z poleceniem npm run <scriptname>, w którym npmzajrzy package.jsoni wykona polecenie zdefiniowane jako jego wartość. Używamy narzędzia wp-scripts, które było w pakiecie, który właśnie zainstalowaliśmy, aby albo raz skompilować nasz Javascript ("build") albo uruchomić tryb „watch” / „listen”, aby kompilować za każdym razem, gdy zapisujemy zmiany ("start").

Pozwala nam to również korzystać z webpacka WordPress i konfiguracji Babel, więc nie musimy tego robić sami.

W folderze projektu utwórz podfolder o nazwie src/. Wewnątrz tego folderu utwórz index.jsplik.

Jeśli zgadzasz się z domyślnymi ustawieniami webpacka, to już koniec! Napisz kod ES6 i JSX w programie index.jsi powiedz, npmaby je skompilować, uruchamiając polecenie build:

npm run build

lub uruchom proces „obserwuj” w terminalu, który nasłuchuje zmian wprowadzonych za pomocą tego polecenia (użyj CTRL + C, aby zatrzymać proces oglądania):

npm run start

Uruchomienie któregokolwiek z nich spowoduje wygenerowanie build/podfolderu w projekcie bezpośrednio ze skompilowanym wynikiem w programie build/index.js.

To wszystko dla najbardziej podstawowej konfiguracji środowiska! Jesteś teraz gotowy do napisania JavaScript ES6 dla Gutenberga!

Jeśli chcesz zmienić lokalizację i nazwy plików źródłowych lub wyjściowych, czytaj dalej.

Konfigurowanie nazw i ścieżek plików źródłowych i wyjściowych

Jeśli tak jak ja nie jesteś zadowolony z domyślnej nazwy pliku i struktury – szczególnie w przypadku plików wyjściowych, musisz zastanowić się nad konfiguracją webpacka. Normalnie, na przykład jeśli programujesz dla Reacta poza WordPressem, musisz skonfigurować pełną konfigurację webpacka z wtyczką Babel. Na szczęście WordPress zajmuje się tym za nas i pozwala nam rozszerzyć własną konfigurację webpacka WordPressa i dostosować tylko te części, które chcemy zmienić.

W folderze projektu (tym samym folderze co package.json) utwórz plik o nazwie webpack.config.jsi otwórz go w swoim edytorze. Napisz w tym pliku:

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

Pierwszą rzeczą, którą robimy, jest @wordpress/scriptspobranie konfiguracji pakietu webpack do zmiennej defaultConfig. Wewnątrz webpack config module.exports, pierwszą rzeczą, którą robimy, jest zastosowanie wszystkiego defaultConfigza pomocą operatora rozprzestrzeniania (...). Te dwie części zapewniają, że rozszerzymy konfigurację webpacka WordPressa o wszystko, co się w nim znajduje. Po operatorze spreadu możemy dostosować lub dodać dowolną właściwość, którą chcemy zmienić; w naszym przypadku lokalizacja źródłowa i lokalizacja wyjściowa.

Właściwość entrydefiniuje pliki źródłowe, czyli domyślnie ./src/index.js. Każdy wpis we entrywłaściwości jest parą klucz+wartość, z której pakiet webpack będzie kompilował (i obserwował). W powyższym przykładzie zdefiniowałem ‘ block-mynamespace-myblock‘ src/block-mynamespace-myblock.jsjako jeden punkt wejścia. Tutaj możesz dodać dowolną liczbę par klucz+wartość dla każdego pliku źródłowego, który chcesz skompilować.

Właściwość outputdecyduje o lokalizacji skompilowanych plików. W pathokreślasz folder docelowy dla wszystkich skompilowanych plików. Używam pomocnika ścieżki, aby móc prawidłowo nawigować po katalogach w mojej konfiguracji. W powyższym przykładzie mówię webpackowi, że wszystkie skompilowane pliki powinny trafić do mojego theme-folder/assets/js/gutenberg/folderu. Ważną rzeczą jest ../przechodzenie w górę w drzewie katalogów, z folderu projektu i do innego folderu, w którym chcę, aby znajdowały się wszystkie pliki JavaScript mojego motywu. Dostosuj ścieżkę, aby dopasować ją do struktury projektu.

Po drugie mówię webpackowi, że wszystkie nazwy plików powinny być nazwane jako odpowiadające im entrynazwy kluczy. Ten webpack config skompiluje mój theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsdo theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Gdybym miał dodać inny plik źródłowy jako parę klucz+wartość w entry, zostałby on skompilowany w tym samym folderze z kluczem jako jego nazwą pliku.

Dokonaj żądanych zmian w webpack.config.jspliku i zapisz. Uruchom ponownie dowolne npmpolecenia kompilacji, aby wygenerować pliki w ich nowych lokalizacjach.

Otóż ​​to! Rozszerzyłeś konfigurację webpacka WordPressa i teraz kontrolujesz, gdzie powinny znajdować się pliki źródłowe i wyjściowe.

W tym przewodniku chcę jednak zawrzeć ostatnią wskazówkę. W domyślnej konfiguracji WordPress dla Babel może brakować niektórych wtyczek Babel dla niektórych nowych funkcji w ESNext. Na przykład z powyższymi ustawieniami domyślnymi i ustawieniami domyślnymi WordPressa nie będziesz mógł używać funkcji strzałek w swoim kodzie. Jeśli ma to dla ciebie znaczenie, czytaj dalej.

Dodaj obsługę najnowszych składni ESNext z Babel

W chwili pisania tego tekstu domyślna konfiguracja Babel WordPressa nie obsługuje „eksperymentalnej składni”, która obejmuje na przykład funkcje strzałek. Aby dodać obsługę tego, musisz dostarczyć swój plik konfiguracyjny Babel, a jak dotąd nie znalazłem sposobu na rozszerzenie konfiguracji Babel WordPressa, tak jak to zrobiliśmy z konfiguracją webpack powyżej. Musimy więc przedefiniować ustawienia Babel, a także dodać wtyczkę „eksperymentalne składnie”. Ale nie martw się, to bardzo mały plik.

Pierwszym krokiem jest zainstalowanie niektórych pakietów, które są nam potrzebne do predefiniowanych ustawień Babel – musimy zainstalować te same, które zostały zdefiniowane w konfiguracji Babel WordPressa. Uruchom to polecenie, aby zainstalować @babel/preset-envi @babel/preset-react, a także pakiet, który nas interesuje; @babel/plugin-proposal-class-properties:

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

Drugim krokiem jest dodanie pliku konfiguracyjnego Babel. W folderze projektu utwórz plik o nazwie .babelrc(bez rozszerzenia pliku).

Uwaga dla systemu Windows: Jeśli siedzisz na komputerze z systemem Windows, nie możesz tworzyć plików bez rozszerzeń plików. Aby obejść ten problem, możesz utworzyć ten plik za pomocą terminala / wiersza poleceń. Uruchom to polecenie:

To polecenie wygeneruje „hi” do pliku .babelrcw bieżącym folderze. Możesz teraz otworzyć ten plik w swoim edytorze, usunąć „cześć” i dodać rzeczywistą zawartość poniżej.

.babelrcPowinieneś wyglądać mniej więcej tak :

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

Definiujemy te same ustawienia wstępne, które normalnie robisz w projekcie React i tak samo, jak robi to WordPress. To, co dodajemy, to pluginswłasność. Wewnątrz tablicy pluginsdodajemy @babel/plugin-proposal-class-propertiesniezbędną wtyczkę Babel do „eksperymentalnych składni”, takich jak funkcje strzałek.

Wniosek

Pamiętaj, że WordPress może zmienić swoją konfigurację w dowolnym momencie, jest to szczególnie prawdopodobne, ponieważ Gutenberg jest dość nowy. Ponieważ rozszerzamy konfigurację WordPressa, być może w pewnym momencie będziemy musieli ponownie zaktualizować naszą konfigurację, aby dopasować ją do naszych potrzeb. Być może WordPress zdecyduje się na włączenie obsługi składni eksperymentalnych, abyśmy nie musieli wykonywać całej konfiguracji Babel.

W żadnym wypadku nie jest to wyczerpujący przewodnik po konfigurowaniu Webpack i Babel, ale jest wynikiem wielu eksperymentów i odkrywania rzeczy. Mam nadzieję, że pomogło ci to w nauczeniu się, jak skonfigurować własne środowisko programistyczne Gutenberg i uczyniło to wystarczająco łatwym, więc nie jest to tak duża przeszkoda w rozpoczęciu nauki ES6, ESNext, JSX i wszystkich innych dobrych rzeczy, które są korzystne dla programowania dla Gutenbergu!