Публікація реєстру блоків на GitHub
Створивши кілька якісних блоків, ви захочете використовувати їх і в наступному проєкті. Копіювання папок між темами вручну працює, доки копії не починають відрізнятися і вже ніхто не пам’ятає, у якій темі є виправлена версія. Загортати кожен блок у пакет із власною збіркою — забагато зайвих дій для папки, у якій є block.json і шаблон.
Реєстр блоків вирішує цю проблему. Це файл registry.json і набір папок блоків, доступні через звичайний HTTP. Користувачі запускають команду CLI, вихідний код блока копіюється в їхню тему, і надалі вони самі керують цією копією. Для розміщення реєстру достатньо репозиторію GitHub, адже GitHub надає кожен файл із загальнодоступного репозиторію за прямим URL.
У цьому посібнику створюється реєстр acme із чотирма блоками, публікується з репозиторію acme/acme-blocks, блоки з нього встановлюються в тему, а випуск фіксується тегом git.
Пакет blockstudio на npm має версію 0.0.1. Цей випуск є заглушкою: його єдина команда, add, виводить Adding block: <name> і завершує роботу, нічого не завантажуючи. Команди й результати в цьому посібнику взято з реєстру CLI у репозиторії Blockstudio (packages/registry) — саме його описує CLIДокументація реєстру.
Як взаємодіють компоненти
Потрібно знати про два файли:
registry.jsonпублікує автор блока. У ньому перелічено блоки, файли кожного блока йbaseUrlдля їх завантаження.blocks.jsonрозміщується в темі або плагіні користувача. У ньому вказано реєстри для використання й каталог для встановлення блоків.
Під час встановлення блока CLI отримує дані з усіх реєстрів у blocks.json, знаходить блок, визначає його залежності, завантажує кожен перелічений файл із {baseUrl}/{block}/{file} і зберігає його в {directory}/{block}/{file}. Жодні перетворення не виконуються, тому файли на диску повністю відповідають файлам у репозиторії.
Крок 1: Структурування репозиторію
Створіть репозиторій із файлом registry.json у корені та окремою папкою для кожного блока в blocks/:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
Назва папки — це назва блока в реєстрі, і вона стане назвою папки в темі користувача. Вона має точно відповідати другій частині назви блока в block.json (acme/hero міститься в hero/), щоб встановлену папку було легко впізнати.
Крок 2: Створення блоків
Кожна папка — це звичайний блок Blockstudio. У головного блока є одне поле:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card має ту саму структуру й додає style.scss. tabs рендерить <InnerBlocks allowedBlocks='["acme/tab-item"]' />, а tab-item оголошує "parent": ["acme/tabs"], тож tabs не має сенсу без tab-item. На наступному кроці реєстр описує цей зв’язок.
У цих блоках немає нічого специфічного для реєстру. CLI копіює папки, тож блоки, створені за допомогою @wordpress/create-block або зареєстровані через звичайний PHP, можна публікувати так само.
Крок 3: Створення registry.json
registry.json перелічує кожен блок і кожен файл, який має завантажити CLI:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
Ось кілька правил, від яких залежить працездатність цього файла:
files— це явний список. CLI завантажує саме ці шляхи й нічого більше. Підстановки шаблонів немає, тому новий ресурс потрапить до збірки лише після додавання сюди. Шляхи можуть містити підкаталоги, які буде створено під час встановлення.baseUrlмає бути абсолютним URL. CLI перевіряє його як URL і відхиляє відносні значення. Файли блоків завжди завантажуються зbaseUrl, а не з місця, відносного до того, звідки було завантаженоregistry.json.dependenciesпозначають блоки в тому самому реєстрі. Додаванняtabsспершу встановлюєtab-item. Через відсутні або циклічні залежності встановлення переривається з помилкою.nameобов’язковий, але не відображається. Команди й вивід використовують ключ, який споживач передає реєстру вblocks.json; він не обов’язково має збігатися.typeмає інформаційний характер. Він приймаєblockstudio,create-blockабоwordpressі не змінює роботу CLI.
CLI перевіряє весь файл під час кожного завантаження й повідомляє про кожне поле з помилкою, тож описка виявиться ще до завантаження будь-якого файлу. Рядок $schema забезпечує ті самі перевірки у вашому редакторі.
Крок 4: Публікація через raw URL
Зафіксуйте зміни й надішліть репозиторій до GitHub. Після цього кожен файл у публічному репозиторії буде доступний за адресою:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> — це гілка, тег або SHA коміту. Для цього реєстру важливі дві URL-адреси:
- Реєстр URL, який налаштовують споживачі:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrlуregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
З таким baseUrl index.php для hero завантажується з
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Raw-хост повертає вміст файлу замість сторінки GitHub HTML — саме це потрібно CLI. Неправильний власник, репозиторій або посилання спричинить помилку 404 під час першої команди:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Крок 5: Встановлення блоків у тему
У корені теми, що споживає реєстр, створіть blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes створює порожній об’єкт registries. Додайте реєстр у простір імен, який хочете вводити в командах:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Запустіть init без --yes у терміналі, щоб натомість відповісти на ті самі запитання в інтерактивному режимі (каталог блоків, назви реєстрів і URL-адреси).
Переконайтеся, що реєстр знаходиться:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search виконує пошук підрядка без урахування регістру в назвах, заголовках та описах:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
Перегляньте встановлення за допомогою --dry-run. Залежність указано першою, адже її буде встановлено першою:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Тепер виконайте справжнє встановлення:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Тепер обидві папки містяться в каталозі blockstudio теми, точно як у репозиторії:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Якщо блок є лише в одному налаштованому реєстрі, простір імен можна не вказувати; також можна передати одразу кілька блоків:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio виявляє нові папки так само, як будь-які інші блоки в темі.
Оновлення встановлених блоків
Встановлені файли є копією. Система не відстежує, яку версію ви встановили, а CLI самостійно ніколи не оновлює блок. Щоб отримати новішу версію, додайте блок ще раз. Без термінала або в CI наявна папка зупиняє команду:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
У терміналі CLI натомість запитує підтвердження перед перезаписом. --dry-run показує папки, які буде замінено, а --yes виконує заміну:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Перезапис замінює перелічені файли версією з реєстру, тож спершу зафіксуйте локальні зміни, а результат перевірте за допомогою git diff.
Щоб видалити блок, видаліть папку за назвою:
npx blockstudio remove tabs --yes
Removed tabs
remove приймає назву папки, а не namespace/block. Залежності не видаляються, тож tab-item залишиться встановленим після видалення tabs.
Керування версіями за допомогою посилань git
У CLI немає поля версії чи прапорця версії. Що саме буде завантажено, повністю визначають URL-адреси, а на GitHub версією є посилання в URL. Споживач, який указує на main, отримає те, що містить main на момент встановлення.
Щоб опублікувати незмінний випуск, registry.json у тезі також має завантажуватися з цієї тези. Перед створенням тега встановіть baseUrl на тег:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Потім зафіксуйте зміни, створіть тег і надішліть його:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Після цього поверніть baseUrl до main і зафіксуйте зміни, щоб гілка й надалі надавала актуальні файли. Якщо пропустити перший крок, споживач, закріплений за тегом, отримає список блоків із цього тега, але завантажить файли з main.
Споживачі закріплюють версію, використовуючи тег у URL реєстру:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
У цьому прикладі v1.0.0 було позначено тегом до появи tabs і tab-item, тож у закріпленому реєстрі доступні лише два початкові блоки:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
SHA коміту також працює в URL реєстру, але коміт не може містити власний SHA в baseUrl. Тому закріплення за SHA фіксує список блоків, тоді як файли надходять із посилання, названого в baseUrl цього коміту. Для випусків краще використовувати теги.
Що слід пам’ятати
- Спершу завантажуються всі реєстри.
addзавантажує всі реєстри вblocks.jsonперед пошуком будь-чого, тому недоступність одного реєстру призведе до помилки команди навіть дляacme/hero. Видаліть реєстри, якими більше не користуєтеся. - Для неоднозначних назв потрібен простір імен. Якщо в обох реєстрах є
hero, у терміналі система запитає, який із них використовувати;--yesвибере перший у порядкуblocks.json, а неінтерактивний запуск завершиться зBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Для приватних репозиторіїв потрібні заголовки. Використовуйте об’єктну форму запису реєстру з
urlтаheaders. Значення заголовків підтримують заповнювачі${VAR}, які зчитуються з середовища, а CLI надсилає заголовки під час завантаження реєстру й кожного файлу. Інструкції з налаштування токена дивіться в розділі хостинг GitHub.
Наступні кроки
- Огляд реєстру: що таке реєстр і як працює CLI
- registry.json: кожне поле маніфесту
- blocks.json: конфігурація споживача, автентифікація та виявлення конфігурації
- додавання: визначення простору імен, залежності та поведінка перезапису
- GitHub хостинг: GitHub Pages і приватні репозиторії
- Власний сервер: розміщення реєстру на власній інфраструктурі