Полное руководство по настройке среды разработки для Gutenberg

Это руководство предназначено для тех, кто хочет писать код для Gutenberg с синтаксисом ES6, ESNext и JSX, и вам необходимо настроить webpack и babel для преобразования их в файлы, которые вы можете использовать в редакторе Gutenberg. Мы рассмотрим, что вам нужно сделать, почему и как мы можем использовать и расширять значения по умолчанию из WordPress и настраивать их в соответствии с нашими потребностями.

Если вы новичок во всех концепциях npm, webpcak и Babel, вам следует прочитать следующий раздел, целью которого является объяснение основ того, как эти инструменты работают и как вы их используете. Однако, если вы делали это раньше и знакомы с процессом, возможно, разрабатывая с помощью React, перейдите к следующему разделу, где мы на самом деле настроим все.

Для начинающих: npm, webpack и babel

Если вы не уверены, зачем нам нужно делать все это для написания Javascript для Gutenberg, я бы порекомендовал вам прочитать мой пост, в котором рассматриваются основы разработки для Gutenberg, где я объясняю разницу между версиями Javascript и почему это стоит усилий.

Если вы никогда раньше этого не делали, вам сначала нужно установить Node.js на свой компьютер. Нажмите на ссылку, скачайте и установите его. Включенный в Node.js, вы получите инструмент, который мы будем использовать для настройки большей части конфигурации. Это инструмент npm, который позволяет вам устанавливать библиотеки Javascript и запускать скрипты через командную строку/терминал. Вы также можете использовать yarn, если хотите, но для этого руководства мы будем использовать npm.

нпм

В этом руководстве не будут подробно описаны все, что вы можете делать с npm, но оно объяснит основную концепцию и вещи, которые имеют отношение к нашим целям. Мы будем использовать npmдля двух вещей; для установки необходимых библиотек в наш проект и для запуска команд для сборки (компиляции) наших файлов Javascript.

С помощью npmвы можете установить любые общедоступные пакеты Javascript с открытым исходным кодом. Если бы мы разрабатывали с помощью React (вне WordPress), нам нужно было бы установить библиотеки React и библиотеки веб-пакетов. WordPress предлагает целый ряд библиотек (в основном для Gutenberg), которые вы можете установить, но на самом деле нас интересует только одна: @wordpress/scripts— которая помогает нам упростить нашу настройку.

Всякий раз, когда вы устанавливаете библиотеку, npmбудет создаваться подпапка «node_modules», где хранятся установленные библиотеки. Вам никогда не нужно будет заходить в эту папку или что-либо здесь менять, но имейте в виду, что эта папка легко будет содержать (буквально!) десятки тысяч файлы. Это папка, которую вы никогда не должны фиксировать в git или включать в какую-либо готовую тему или плагин. Библиотеки нужны только во время разработки.

Когда ваша среда настроена, вы можете использовать npmее для запуска сценариев, определенных в вашем package.jsonфайле. В зависимости от проекта у вас обычно будет как минимум два сценария; один для создания сценариев и один для запуска «режима просмотра». В «режиме просмотра» npmв терминале запускается процесс, который ожидает и прослушивает изменения, сделанные в любом файле, и компилирует их во время выполнения всякий раз, когда вы нажимаете «Сохранить». Возможно, вы знакомы с этой концепцией, если раньше использовали программы-компиляторы SCSS или LESS. Гораздо эффективнее запускать в фоновом режиме «наблюдательный» скрипт, который перекомпилирует каждый раз, когда вы сохраняете, вместо того, чтобы переходить в терминал и запускать команду сборки после каждого изменения.

вебпак и бабел

Вы можете получить разработку для Gutenberg, не выполняя никаких настроек webpack или babel. Поскольку мы используем библиотеки WordPress, они сделают это за нас. Однако у этого есть один недостаток — по умолчанию используется фиксированное местоположение и имя файла как для исходных, так и для выходных файлов. Вся ваша разработка Javascript должна быть написана внутри одного файла в формате, project-folder/src/index.jsи сборка всегда будет заканчиваться в формате project-folder/build/index.js. Если вас это устраивает, вы можете пропустить всю часть о настройке веб-пакета. Однако, если вы разрабатываете тему или плагин с несколькими функциями Гутенберга (настраиваемые блоки, фильтры и т. д.), вам может понадобиться, по крайней мере, другое имя и местоположение выходного файла, а также возможность использования нескольких файлов.

Если вы используете пакет WordPress для настройки (@wordpress/scripts), Babel уже настроен. Но вы должны знать, что пакет WordPress может не включать плагины, которые вы, возможно, захотите использовать. Например, есть пакет, который позволяет вам использовать новые так называемые «стрелочные функции» (myFunction = (param) => { }) для определения функций без необходимости связывания this. Если вы абсолютно хотите использовать эти функции ESNext, вам нужно настроить Babel самостоятельно, а не использовать настройки WordPress по умолчанию. Я расскажу, как ниже.

Процесс

Процесс разработки с помощью веб-пакета после того, как все настроено и установлено, заключается в том, чтобы перейти в папку вашего проекта в терминале и запустить скрипт «watch». Он останется открытым и будет прослушивать изменения, внесенные в ваши JS-файлы. Всякий раз, когда вы нажимаете «Сохранить» в своих файлах Javascript, терминал выводит информацию (надеюсь), что он успешно перекомпилировал файл. Если были какие-либо ошибки компиляции, они появятся в терминале. Чтобы остановить процесс «смотреть», нажмите CTRL + C.

Настройка среды

Я предполагаю, что у вас уже есть локальный WordPress, работающий на некотором стеке LAMP (такие программы, как WampServer, XAMPP, Docker или аналогичные), и что у вас есть либо плагин, либо тема, готовые начать кодирование вашего Javascript.

Я рекомендую создать подпапку, предназначенную для вашей разработки Javascript, так как вы можете получить несколько конфигурационных файлов и папок. Это упрощает разделение файлов и папок (например node_modules/), которые вы не хотите включать в коммиты git или окончательные сборки. Но совершенно нормально использовать папку основной темы или плагина в качестве папки проекта для разработки Javascript.

В терминале (терминал Mac OS или командная строка Windows работают нормально) перейдите в папку проекта. Что касается этого урока, я предполагаю, что мы находимся в теме и создали пустую подпапку gutenberg-dev/в качестве папки нашего проекта.

Первый шаг — это инициализация проекта npm, который, по сути, просто говорит npmо создании package.jsonфайла. Этот package.jsonфайл сообщает npmо том, какие пакеты требуются и какие сценарии доступны для запуска. Введите это в терминале;

npm init -y

Это создает package.jsonфайл с содержимым по умолчанию в папке вашего проекта.

Далее мы установим пакет WordPress, который поможет нам уменьшить количество необходимых настроек. Запустите эту команду:

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

Тег --save-devсообщает npm, что данные библиотеки необходимы только для разработки, и следит за --save-exactтем, чтобы была установлена npm​​только одна версия, самая последняя.

Откройте package.jsonфайл в вашем редакторе. (npmтакже будет генерироваться package-lock.jsonпри установке пакетов, вы можете просто игнорировать этот файл, в него package.jsonвы будете вносить изменения). Он должен быть заполнен конфигурацией по умолчанию, и вы могли заметить, что установка пакета, которую мы сделали ранее, добавила запись @wordpress/scriptsопределенной версии в devDependencies. По мере того, как вы будете устанавливать больше пакетов, npmбудут обновляться package.jsonзаписи для каждого пакета. Все, о чем нам нужно беспокоиться в этом файле, — это scriptsсвойства, которые предназначены для сценариев (команд), которые вы можете использовать npmдля запуска. Обновите свойство scripts на это (вы можете удалить «тест» по умолчанию):

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

Этот фрагмент кода сообщает npm, что у нас есть два скрипта, которые мы можем запустить в этой папке проекта; «строить» и «начинать». Запускаем скрипт с командой npm run <scriptname>, в котором npmбудем искать package.jsonи выполнять команду, определенную как его значение. Мы используем инструмент wp-scripts, который входит в пакет, который мы только что установили, чтобы либо скомпилировать наш Javascript один раз ("build"), либо запустить режим «наблюдать» / «слушать» для компиляции всякий раз, когда мы сохраняем изменения ("start").

Это также позволяет нам использовать веб-пакет WordPress и конфигурацию Babel, поэтому нам не нужно делать это самостоятельно.

В папке вашего проекта создайте подпапку с именем src/. Внутри этой папки создайте index.jsфайл.

Если у вас все в порядке с настройками веб-пакета по умолчанию, все готово! Напишите свой код ES6 и JSX в index.js, и npmскомпилируйте их, выполнив команду сборки:

npm run build

или запустите процесс «отслеживания» в терминале, который прослушивает изменения, сделанные с помощью этой команды (используйте CTRL+C, чтобы остановить процесс наблюдения):

npm run start

Запуск любого из них приведет к созданию build/подпапки непосредственно в вашем проекте с скомпилированным результатом в формате build/index.js.

Это все для самой базовой настройки среды! Теперь вы готовы написать ES6 Javascript для Гутенберга!

Если вы хотите изменить расположение и имена исходных или выходных файлов, читайте дальше.

Настройка имен и путей исходных и выходных файлов

Если вас, как и меня, не устраивает имя файла и структура по умолчанию, особенно для выходных файлов, вам нужно изучить настройку webpack. Обычно, например, если вы занимаетесь разработкой для React вне WordPress, вам нужно настроить полную конфигурацию веб-пакета с помощью плагина Babel. К счастью, WordPress позаботится об этом за нас и позволит нам расширить собственную конфигурацию веб-пакета WordPress и настроить только те части, которые мы хотим изменить.

В папке вашего проекта (в той же папке, что и package.json) создайте файл с именем webpack.config.jsи откройте его в редакторе. Напишите в этом файле следующее:

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

Первое, что мы делаем, это @wordpress/scriptsзагружаем конфигурацию webpack в переменную defaultConfig. Внутри конфигурации веб-пакета module.exportsпервое, что мы делаем, это применяем все defaultConfig, используя оператор распространения (...). Эти две части гарантируют, что мы расширим конфигурацию веб-пакета WordPress, включив в нее все, что внутри. После оператора спреда мы можем настроить или добавить любое свойство, которое мы хотим изменить; в нашем случае исходное местоположение и выходное местоположение.

Свойство entryопределяет исходные файлы, по умолчанию это ./src/index.js. Каждая запись в entryсвойстве представляет собой пару ключ+значение, из которой webpack будет компилировать (и смотреть). В приведенном выше примере я определил ‘ block-mynamespace-myblock‘, расположенный src/block-mynamespace-myblock.jsкак одна точка входа. Вы можете добавить сюда столько пар ключ+значение для каждого исходного файла, который хотите скомпилировать.

Свойство outputопределяет расположение скомпилированных файлов. В pathвы определяете папку назначения для всех скомпилированных файлов. Я использую помощник пути, чтобы иметь возможность правильно перемещаться по каталогам в моей конфигурации. В приведенном выше примере я сообщаю веб-пакету, что все скомпилированные файлы должны оказаться в моей theme-folder/assets/js/gutenberg/папке. Важно использовать ../для перемещения вверх по дереву каталогов, из папки проекта и в другую папку, где я хочу, чтобы все файлы Javascript моей темы находились. Настройте путь в соответствии со структурой вашего проекта.

Во-вторых, я говорю веб-пакету, что все имена файлов должны называться соответствующими entryименами ключей. Эта конфигурация веб-пакета скомпилирует мой файл theme-folder/gutenberg-dev/src/block-mynamespace-myblock.jsв theme-folder/assets/js/gutenberg/block-mynamespace-myblock.js. Если бы я добавил еще один исходный файл в качестве пары ключ+значение в entry, он был бы скомпилирован в ту же папку с ключом в качестве имени файла.

Внесите необходимые изменения в webpack.config.jsфайл и сохраните. Повторно запустите любую из npmкоманд сборки, чтобы сгенерировать файлы в их новых местах.

Вот и все! Теперь вы расширили конфигурацию веб-пакета WordPress и теперь можете контролировать, куда должны идти исходные и выходные файлы.

Однако я хочу включить последний совет в это руководство. В конфигурации WordPress по умолчанию для Babel могут отсутствовать некоторые плагины Babel для определенных новых функций в ESNext. Например, с приведенным выше значением по умолчанию и значениями по умолчанию WordPress вы не сможете использовать стрелочные функции в своем коде. Если это важно для вас, читайте дальше.

Добавлена ​​поддержка новейших синтаксисов ESNext с помощью Babel.

На момент написания этой статьи в настройках Babel WordPress по умолчанию отсутствует поддержка «экспериментального синтаксиса», который включает, например, функции стрелок. Чтобы добавить поддержку этого, вам нужно предоставить свой файл конфигурации Babel, и пока я не нашел способа расширить конфигурацию Babel WordPress, как мы сделали с конфигурацией веб-пакета выше. Поэтому нам нужно переопределить пресеты Babel, а также добавить плагин «экспериментальные синтаксисы». Но не волнуйтесь, это очень маленький файл.

Первым шагом является установка некоторых пакетов, которые нам нужны для пресетов Babel — нам нужно установить те же самые пакеты, которые определены в конфигурации Babel WordPress. Запустите эту команду для установки @babel/preset-envи @babel/preset-react, а также интересующего нас пакета; @babel/plugin-proposal-class-properties:

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

Второй шаг — добавление файла конфигурации Babel. В папке проекта создайте файл с именем .babelrc(без расширения файла).

Примечание для Windows: если вы работаете на компьютере с Windows, вам не разрешено создавать файлы без расширений. Чтобы обойти это, вы можете создать этот файл с помощью терминала/командной строки. Запустите эту команду:

Эта команда выведет «привет» в файл .babelrcв текущей папке. Теперь вы можете открыть этот файл в своем редакторе, удалить «привет» и добавить фактический контент ниже.

Ваш .babelrcдолжен выглядеть примерно так:

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

Мы определяем те же пресеты, которые вы обычно делаете в проекте React, и так же, как это делает WordPress. То, что мы добавляем, является pluginsсвойством. Внутри массива pluginsмы добавляем @babel/plugin-proposal-class-propertiesнеобходимый плагин Babel для «экспериментальных синтаксисов», таких как стрелочные функции.

Вывод

Имейте в виду, что WordPress может изменить свою конфигурацию в любое время, это особенно вероятно, потому что Gutenberg довольно новый. Поскольку мы расширяем конфигурацию WordPress, в какой-то момент нам может понадобиться снова обновить нашу конфигурацию, чтобы она соответствовала нашим потребностям. Возможно, WordPress решит включить поддержку экспериментального синтаксиса, чтобы нам не пришлось выполнять всю настройку Babel.

Это ни в коем случае не исчерпывающее руководство по настройке Webpack и Babel, а результат множества экспериментов и выяснения вещей. Я надеюсь, что это помогло вам научиться настраивать собственную среду разработки Gutenberg и сделало ее достаточно простой, так что это не такое уж большое препятствие для начала изучения ES6, ESNext, JSX и всего того полезного, что полезно для разработки для Гутенберг!