Багато 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 без складних нестандартних механізмів.