Сборка через wp-scripts

Современная сборка в классической теме

Интеграция современных JavaScript-фреймворков, таких как React, в традиционные темы WordPress исторически была связана с ручной настройкой сложных сборщиков вроде Webpack. Это требовало значительных усилий для конфигурации, управления зависимостями и оптимизации. Пакет кардинально упрощает этот процесс, предоставляя готовую, оптимизированную под WordPress конфигурацию Webpack без необходимости ручного вмешательства.

Данный подход позволяет использовать всю мощь современного JS-стека, включая горячую перезагрузку модулей (HMR), синтаксис ESNext и JSX, прямо внутри стандартной PHP-темы. Давайте настроим такое окружение.

Настройка окружения

Первым шагом является инициализация Node.js проекта в корневой директории вашей темы WordPress. Перейдите в папку темы (wp-content/themes/your-theme-name) и выполните команду:

npm init -y

Эта команда создаст файл package.json со значениями по умолчанию. Далее установим необходимые зависимости. Нам понадобится сам пакет @wordpress/scripts для сборки и @wordpress/element — абстракция над React, оптимизированная для WordPress.

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

Теперь необходимо настроить скрипты для запуска и сборки проекта. Откройте package.json и добавьте секцию scripts:

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

Команда start запускает режим разработки с отслеживанием изменений и HMR. Команда build создает оптимизированную, минифицированную версию ассетов для продакшена.

Структура папок и процесс сборки

По соглашению, @wordpress/scripts ожидает, что ваши исходные файлы будут находиться в директории src, а скомпилированные ассеты будут помещены в директорию build. Создайте папку src в корне вашей темы.

Внутри src создайте index.js — это будет точка входа для вашего JavaScript. Давайте добавим простой React-компонент, чтобы проверить работу JSX.

// src/index.js
import { render } from '@wordpress/element';

const App = () => {
    return <h1>Hello from React in WordPress!</h1>;
};

// Убедитесь, что в вашем PHP-шаблоне есть <div id="my-react-app"></div>
const target = document.getElementById('my-react-app');
if (target) {
    render(<App />, target);
}

Теперь запустите процесс разработки командой npm start. Вы увидите, что автоматически создалась папка build с тремя файлами: index.js (скомпилированный JS), index.css (если у вас есть src/index.scss) и index.asset.php.

Магия index.asset.php

Файл index.asset.php является ключевым элементом, который связывает современную JavaScript-экосистему с PHP-бэкендом WordPress. Он генерируется автоматически при каждой сборке и содержит PHP-массив с двумя важными ключами.

Ключ	Описание
`dependencies`	Массив строк, содержащий идентификаторы скриптов WordPress, от которых зависит ваш код (например, 'wp-element').
`version`	Уникальный хеш, основанный на содержимом файла. Используется для эффективного сброса кеша в браузерах пользователей.

Пример содержимого index.asset.php:

<?php
return [
    'dependencies' => ['wp-element'],
    'version' => 'a1b2c3d4e5f6g7h8',
];

Благодаря этому файлу, мы можем подключить наши ассеты в functions.php наиболее эффективным способом. WordPress автоматически обработает зависимости и обеспечит корректную версию файла.

// functions.php
function my_theme_enqueue_assets() {
    // Подключаем сгенерированный файл ассетов
    $asset_file = include(get_template_directory() . '/build/index.asset.php');

    wp_enqueue_script(
        'my-theme-scripts', // Уникальный идентификатор скрипта
        get_template_directory_uri() . '/build/index.js',
        $asset_file['dependencies'], // Динамические зависимости
        $asset_file['version'] // Динамическая версия для кеширования
    );
}
add_action('wp_enqueue_scripts', 'my_theme_enqueue_assets');

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

Quiz Questions 1/5

Какую основную проблему решает пакет @wordpress/scripts при разработке тем для WordPress?

Quiz Questions 2/5

Какой файл, генерируемый пакетом @wordpress/scripts, является ключевым для связи между JavaScript-сборкой и PHP-бэкендом WordPress?

React в WordPress: Создание классических тем WooCommerce