Многие плагины WordPress подключают собственные CSS- и JavaScript-файлы глобально: на каждой странице сайта, независимо от того, используется ли там конкретный Gutenberg-блок. Такой подход увеличивает количество HTTP-запросов, объём JavaScript и CSS, размер DOM и вероятность конфликтов с другими плагинами.
Для собственных блоков лучше описывать assets в файле block.json. WordPress сможет зарегистрировать зависимости блока и подключать нужные ресурсы в соответствующем контексте — в редакторе или на frontend. Это не заменяет оптимизацию кода, но устраняет лишнюю глобальную нагрузку.
Почему глобальное подключение assets создаёт проблему
Классический подход часто выглядит так: плагин добавляет wp_enqueue_script() или wp_enqueue_style() к хуку wp_enqueue_scripts, и его файлы загружаются на всех публичных страницах. Если блок нужен только на странице с формой, галереей или специальным уведомлением, ресурсы всё равно попадают на главную, страницы записей и служебные шаблоны.
Лишние assets не всегда заметно замедляют работу каждой отдельной страницы, но на крупных сайтах эффект накапливается. Браузер загружает, анализирует и выполняет код, который не используется. Кроме того, глобальные стили могут изменять внешний вид сторонних компонентов, а JavaScript — конфликтовать с другими скриптами или редактором.
Локальная модель означает, что блок имеет собственные файлы и описание их назначения. Стили и скрипты не нужно вручную добавлять на все страницы через общий хук, если WordPress может получить эту информацию из block.json.
- меньше ненужных CSS и JavaScript на страницах;
- ниже риск конфликтов между плагинами;
- понятная связь между блоком и его assets;
- более простая поддержка и обновление собственного блока.
Какие поля block.json отвечают за assets
В block.json можно указать отдельные файлы для редактора, frontend и общих стилей. Для локальных файлов используется формат file:./имя-файла. Пути указываются относительно самого block.json или директории, которую обрабатывает сборка.
Пример описания блока с разделением ресурсов:
- editorScript — JavaScript, необходимый для работы блока в редакторе Gutenberg;
- viewScript — JavaScript для поведения блока на публичной странице;
- style — стили, предназначенные для frontend; в зависимости от конфигурации WordPress они также могут быть доступны редактору;
- editorStyle — стили только для редактора, например для удобства редактирования или визуальной имитации frontend.
{
"apiVersion": 3,
"name": "acme/notice",
"title": "Notice",
"category": "design",
"editorScript": "file:./index.js",
"style": "file:./style.css",
"editorStyle": "file:./editor.css",
"viewScript": "file:./view.js"
}
Как зарегистрировать блок через PHP
После подготовки block.json блок нужно зарегистрировать на сервере. Если файл находится в собранной директории build, передайте её путь в register_block_type(). WordPress прочитает metadata и зарегистрирует блок вместе с заявленными assets.
- убедитесь, что директория build действительно содержит block.json;
- используйте абсолютный путь через __DIR__, чтобы не зависеть от текущего URL-адреса;
- регистрируйте блок на init, когда WordPress уже готов работать с типами блоков.
<?php
add_action('init', function () {
register_block_type(__DIR__ . '/build');
});
Пример структуры файлов
В простом проекте исходная структура может выглядеть так:
- src/block.json — исходное описание блока;
- src/index.js — код редактора;
- src/view.js — поведение блока на frontend;
- src/style.css — общие стили блока;
- src/editor.css — стили редактора;
- build/block.json и собранные assets — файлы, которые WordPress использует на сайте.
plugin-folder/
├── plugin.php
├── src/
│ ├── block.json
│ ├── index.js
│ ├── view.js
│ ├── style.css
│ └── editor.css
└── build/
├── block.json
├── index.js
├── view.js
├── style.css
└── editor.css
Как WordPress определяет зависимости и версии
Во время сборки JavaScript для WordPress обычно создаётся не только основной файл, но и файл метаданных с зависимостями и версией, например index.asset.php. Если assets описаны через file: в block.json, WordPress может использовать эти данные при регистрации блока.
Это важно для скриптов, которые используют библиотеки WordPress, например wp-element, wp-components или wp-i18n. Зависимости помогают загружать необходимые скрипты в правильном порядке, а версия позволяет контролировать кеширование.
Не стоит вручную дублировать эту логику через wp_enqueue_script(), если блок уже корректно собран и зарегистрирован через metadata. Ручное подключение может привести к двойной загрузке или расхождениям между редактором и frontend.
- проверяйте, что после сборки asset-файл создаётся там, где его ожидает block.json;
- не переименовывайте сгенерированные файлы без обновления metadata;
- после деплоя очищайте кеш, если браузер или CDN продолжает отдавать старую версию assets.
Разница между editorScript, viewScript и стилями
Код редактора и код публичного интерфейса имеют разные задачи. editorScript регистрирует блок в Gutenberg, описывает его edit- и save-логику, добавляет элементы управления и взаимодействие в редакторе. Этот код не должен быть необходим посетителю готовой страницы, если блок не использует его функции на frontend.
viewScript нужен для поведения уже опубликованного блока: например, открытия accordion, работы слайдера, обработки кликов или инициализации интерактивного виджета. Если блок статичный и не имеет JavaScript-логики для посетителя, viewScript лучше не добавлять.
editorStyle предназначен для редактора. Его можно использовать, если блок в Gutenberg должен отличаться от публичной версии или требует дополнительных отступов, рамок и служебных классов. Не следует использовать editorStyle для стилей, без которых блок не работает на frontend.
- не подключайте viewScript, если блок только выводит текст или разметку;
- не смешивайте элементы управления редактора с кодом, который должен выполняться у посетителя;
- выносите общие стили в style, а специфичные для Gutenberg — в editorStyle;
- проверяйте, что JavaScript не обращается к DOM-элементам, которых нет в конкретном режиме.
Как проверить, что assets загружаются правильно
После регистрации не стоит ограничиваться проверкой отображения блока. Нужно отдельно проверить редактор, страницу с блоком и страницу без него. Так можно увидеть, не подключаются ли JavaScript или CSS глобально через другой код плагина.
Откройте инструменты разработчика браузера и просмотрите вкладки Network и Sources. Найдите файлы блока по названию, проверьте их тип, статус ответа и момент загрузки. В консоли также не должно быть ошибок, связанных с отсутствующими зависимостями или неправильными путями.
- в редакторе блок должен загружать editorScript и editorStyle;
- на frontend страницы с блоком должны быть доступны необходимые style и viewScript;
- на странице без блока не должно быть лишнего viewScript, если WordPress и тема используют стандартную block-aware регистрацию;
- в исходном HTML не должно появляться несколько одинаковых копий одного asset;
- после отключения кеширования во время теста проверьте фактические запросы, а не только визуальный результат.
Распространённые ошибки при локальном подключении
Самая частая ошибка — block.json описывает один файл, а в build фактически хранится другой. В таком случае блок может зарегистрироваться частично или не загрузить нужный скрипт. После изменения названий файлов повторно запускайте сборку и проверяйте её результат.
Другая проблема — параллельное использование metadata и глобальных enqueue-хуков. Например, block.json подключает view.js, а плагин дополнительно добавляет тот же файл через wp_enqueue_script(). Это может создать дубликаты, двойные обработчики событий и сложные для диагностики ошибки.
Также не стоит считать, что сам block.json автоматически устранит любую глобальную нагрузку. Если тема или другой код вручную подключает стили плагина, они по-прежнему будут загружаться глобально. Нужно найти и убрать дублирующий способ подключения.
- block.json отсутствует в директории, переданной register_block_type();
- сборка не создаёт или не копирует asset-файлы в build;
- путь file:./ указывает не на тот файл;
- один и тот же CSS или JavaScript подключается и через metadata, и вручную;
- viewScript содержит код, который ошибочно выполняется в редакторе;
- после изменения assets версия не обновилась или остался старый кеш.
Частые вопросы
Нужно ли использовать block.json для каждого Gutenberg-блока?
Для современных собственных блоков это рекомендуемый подход, поскольку metadata описывает не только название и редактор, но также assets, зависимости и другие свойства блока. Для старых или нестандартных решений ручная регистрация по-прежнему возможна, но её нужно тщательно контролировать.
Загружается ли viewScript на всех страницах сайта?
При стандартной регистрации block metadata WordPress может подключать frontend-ресурсы блока в контексте его использования. Точное поведение также зависит от версии WordPress, способа вывода контента, темы и сторонних оптимизаторов, поэтому его нужно проверять во вкладке Network.
Можно ли полностью отказаться от wp_enqueue_script()?
Нет, не во всех случаях. Для assets конкретного Gutenberg-блока удобнее использовать block.json. Другие ресурсы плагина, которые не относятся к одному блоку, по-прежнему могут регистрироваться и подключаться через стандартные функции WordPress.
Что делать, если JavaScript нужен и в редакторе, и на frontend?
Можно отдельно указать editorScript и viewScript, даже если они используют общие модули. Не следует без проверки подключать один большой файл в обоих контекстах: лучше разделить код и оставить в каждой сборке только необходимую функциональность.
Достаточно ли локального подключения для оптимизации скорости?
Это важный шаг, но не полная оптимизация. Дополнительно нужно уменьшать размер бандлов, удалять неиспользуемые зависимости, оптимизировать изображения, контролировать сторонние скрипты и проверять кеширование.
Вывод
Для Gutenberg-блоков лучше мыслить не категорией «подключить assets плагина везде», а категорией «каждый блок отвечает за собственные ресурсы». block.json вместе с register_block_type() даёт WordPress структурированное описание этой связи.
Начните с аудита глобальных wp_enqueue_script() и wp_enqueue_style(), перенесите assets конкретных блоков в block.json, разделите код редактора и frontend и проверьте результат во вкладке Network на страницах с блоком и без него. Так сайт получит меньше лишнего JavaScript и CSS без сложных нестандартных механизмов.